Use TouchID as an SSH key on macOS

ssh-macos-touchid.md

Use TouchID as an SSH key on macOS

on macOS, an ssh-keychain SecurityKeyProvider is available that supports touchID.

TL;DR

The gist of this gist is:

$ sc_auth create-ctk-identity -l SSH -k p-256-ne -t bio -N username -E user@example.org
$ cd ~/.ssh
$ ssh-keygen -K -w /usr/lib/ssh-keychain.dylib -N "" 
# copy id_ecdsa_sk_rk.pub to your.server.tld:~/.ssh/authorized_keys
$ ssh your.server.tld -i ~/.ssh/id_ecdsa_sk_rk -o SecurityKeyProvider=/usr/lib/ssh-keychain.dylib

For a bit more explaination, read on...

Introduction

This setup lets you use touchID as a FIDO security key, which is supported by OpenSSH since version 8.2.

This feature is undocumented as for as I know. I learned its existence from Jan Schermer in his email to the openssh-unix-dev.

Note that unlike a real FIDO security key, touchID is bound to your macOS system: you cannot use it on another system. To have a true roaming FIDO Authenticator, use a USB Security Key, such as a YubiKey.

Use TouchID for convenience: never rely on it as a sole key as losing your macOS system then means losing access!

Also note that on macOS, security keys are supported only recently. Even though its OpenSSH client version has been recent enough, upgrade to the latest version of macOS for full support. Alternatively, use HomeBrew's version of OpenSSH.

I am using OpenSSH_10.2p1.

Setup

To set this up, first create a CTK Identity with private key protection. For example, to create a non-exportable p-256 key for use with touchID:

$ sc_auth create-ctk-identity -l SSH -k p-256-ne -t bio -N username -E user@example.org

You should then see a CTK identity labeled SSH. For instance

$ sc_auth identities
SmartCard: com.apple.ctkcard:user
Unpaired identities:
1234CAFE5678BABE8765DEAD4321MEAT12345678	SSH

Using the ssh-keychain provider, you can use your CTK identity as any other FIDO authenticator (security key). This means you can download the key files:

$ ssh-keygen -K -w /usr/lib/ssh-keychain.dylib -N "" 
Enter PIN for authenticator: 
You may need to touch your authenticator to authorize key download.
Saved ECDSA-SK key to id_ecdsa_sk_rk

You don't need to enter a PIN (as with any biometric security key). Just press enter.

The generated files can now be used just like any other SSH key of type ecdsa-sk. Note that as with other security keys, the private key file will contain a reference to the private key, not the private key itself.

Test without a server

As a quick test, try signing some data. This may save you some headache by eliminating issues with for instance server configuration.

Create a file with public keys you trust for verifying signatures:

$ (/bin/echo -n "user@example "; cat ./id_ecdsa_sk_rk.pub ) > allowed_signers

Create some data to be signed:

$ echo I owe you a beer > datatobesigned

Sign the data using TouchID:

$ ssh-keygen -w /usr/lib/ssh-keychain.dylib -Y sign -f ./id_ecdsa_sk_rk -n file datatobesigned
Signing file datatobesigned
Confirm user presence for key ECDSA-SK SHA256:JO+OTpC4UMSMvFHqdxQv8ZSvdLmOKjmg5U7P0rc3jFI
Write signature to datatobesigned.sig

Verify the signature using the public keys in allowed_signers:

$ ssh-keygen -Y verify -n file -s datatobesigned.sig -f ./allowed_signers -I user@example < datatobesigned
Good "file" signature for user@example with ECDSA-SK key SHA256:JO+OTpC4UMSMvFHqdxQv8ZSvdLmOKjmg5U7P0rc3jFI

Test using GitHub

Signin to an SSH server just like with any other SSH key:

• copy your key files to ~/.ssh on the client
• copy your public key file to ~/.ssh/authorized_keys on the server

As a quick test, add your public key (the contents of id_ecdsa_sk_rk.pub) to your GitHub authentication keys

% ssh -T git@github.com -i ~/.ssh/id_ecdsa_sk_rk -o SecurityKeyProvider=/usr/lib/ssh-keychain.dylib
Hi username! You've successfully authenticated, but GitHub does not provide shell access.