keychain-fingerprint

A CLI tool for secure and convenient macOS Keychain access using Touch ID authentication.

📖 Blog post: Secure and Convenient Keychain Access with Touch ID

Why?

When accessing passwords stored in macOS Keychain, you face a security vs convenience dilemma:

The Problem

Running security find-generic-password shows this dialog:

"security" wants to use your confidential information stored in "myapp" in your keychain.
[Deny] [Allow] [Always Allow]

"Allow": Requires typing Mac password every time → Inconvenient
"Always Allow": Any app can access without authentication → Insecure

The Solution: Touch ID

This tool uses Touch ID for authentication: - Fast and convenient: One touch to authenticate (no password typing) - Secure: Other apps still require Mac password to access

Installation

# Compile
swiftc -o keychain-fingerprint main.swift -framework LocalAuthentication -framework Security

# Install (optional)
sudo cp keychain-fingerprint /usr/local/bin/

# IMPORTANT: Set root ownership (security)
sudo chown root:wheel /usr/local/bin/keychain-fingerprint
sudo chmod 755 /usr/local/bin/keychain-fingerprint

⚠️ Security Note: The binary must be owned by root with execute-only permission for regular users. This prevents malicious code injection into a tool that accesses Keychain.

Usage

# Save password (Touch ID → secure input)
keychain-fingerprint set myapp user@example.com

# Get password (Touch ID → stdout)
keychain-fingerprint get myapp user@example.com

# List saved items (Touch ID)
keychain-fingerprint list

# Delete password (Touch ID)
keychain-fingerprint delete myapp user@example.com

Shell Variable (Recommended)

# Capture password in variable (not displayed on screen)
PASSWORD=$(keychain-fingerprint get myapp user@example.com)

# Use the password
echo "Using password..."

# Clear the variable when done
unset PASSWORD

Security

Access Method	Authentication Required
This app	Touch ID
Other apps / `security` command	Mac password

How it works

┌─────────────────────────────────────────┐
│         keychain-fingerprint            │
├─────────────────────────────────────────┤
│  1. Touch ID authentication             │
│  2. Access Keychain (auto-authorized)   │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│         Other apps / terminal           │
├─────────────────────────────────────────┤
│  Keychain access → Mac password prompt  │
└─────────────────────────────────────────┘

Features

All commands require Touch ID
Passwords stored encrypted in macOS Keychain
Password input is hidden (no echo)
Passwords only output to stdout (for variable capture)
Device-only access (kSecAttrAccessibleWhenUnlockedThisDeviceOnly)

Requirements

macOS with Touch ID
Xcode Command Line Tools (xcode-select --install)

License

MIT