Based on https://davecoyle.com/tech-notes/ssh-keys-on-a-yubikey-mac/
-
Install the YubiKey Manager CLI (ykman); alternative installation options can be found here:
brew install ykman -
Install GPG >= 2.1. Version 2.1 simplified the running of gpg-agent. The version isn’t a hard requirement, but it might make your life easier.
brew install gpg -
Install GPGTools’s pinentry-mac GUI for password entry:
brew install pinentry-mac -
Add the following lines to ~/.gnupg/gpg-agent.conf (the pinentry-program line is optional):
enable-ssh-support pinentry-program /opt/homebrew/bin/pinentry-mac -
Add the following lines to your
~/.zshrc. The second line will start gpg-agent if required.export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket) gpg-connect-agent /bye -
If it’s running you should disable the system default ssh-agent
launchctl stop com.openssh.ssh-agent sudo launchctl disable system/com.openssh.ssh-agent
-
Insert the YubiKey into your Mac. You can verify it’s working via:
% ykman info Device type: YubiKey 5 Nano Serial number: _________ Firmware version: _____ Form factor: Keychain (USB-A) Enabled USB interfaces: OTP, FIDO, CCID NFC transport is enabled. Applications USB NFC FIDO2 Enabled Enabled OTP Enabled Enabled FIDO U2F Enabled Enabled OATH Enabled Enabled YubiHSM Auth Not available Not available OpenPGP Enabled Enabled PIV Enabled Enabled -
Change some defaults for the OpenPGP app on the YubiKey. Even though it refers to a “PIN”, alphanumeric and special characters are supported. Here are the default values:
Default PIN: 123456 Default Admin PIN: 12345678
% gpg --card-edit gpg/card> admin Admin commands are allowed gpg/card> passwd gpg: OpenPGP card no. _________ detected 1 - change PIN 2 - unblock PIN 3 - change Admin PIN 4 - set the Reset Code Q - quit Your selection? 1 PIN changed. 1 - change PIN 2 - unblock PIN 3 - change Admin PIN 4 - set the Reset Code Q - quit Your selection? 3 PIN changed. 1 - change PIN 2 - unblock PIN 3 - change Admin PIN 4 - set the Reset Code Q - quit Your selection? 4 Reset Code set. 1 - change PIN 2 - unblock PIN 3 - change Admin PIN 4 - set the Reset Code Q - quit Your selection? q gpg/card> key-attr Changing card key attribute for: Signature key Please select what kind of key you want: (1) RSA (2) ECC Your selection? 1 What keysize do you want? (2048) 4096 The card will now be re-configured to generate a key of 4096 bits Changing card key attribute for: Encryption key Please select what kind of key you want: (1) RSA (2) ECC Your selection? 1 What keysize do you want? (2048) 4096 The card will now be re-configured to generate a key of 4096 bits Changing card key attribute for: Authentication key Please select what kind of key you want: (1) RSA (2) ECC Your selection? 1 What keysize do you want? (2048) 4096 The card will now be re-configured to generate a key of 4096 bits gpg/card> list <...> Key attributes ...: rsa4096 rsa4096 rsa4096 <...> Signature key ....: [not set] Encryption key....: [not set] Authentication key: [not set] <...> gpg/card> -
Generate new keys directly on the YubiKey:
gpg/card> generate Make off-card backup of encryption key? (Y/n) n -
Don’t bother backing up the key when prompted; you won’t get the full key anyway and it can’t be used to restore to a new YubiKey. You’ll get a standard set of PGP key creation prompts for your key settings, then your YubiKey’s light (if it has one) will flash for a while while it generates keys. After about 5 minutes you should see:
public and secret key created and signed. gpg/card> list <...> Signature key ....: <key fingerprint> Encryption key....: <key fingerprint> Authentication key: <key fingerprint> <...> gpg/card> q -
(Optional) Set the YubiKey to require a physical touch before using the keys you just created:
% ykman openpgp set-touch aut on Enter admin PIN: Set touch policy of authentication key to on? [y/N]: y % ykman openpgp set-touch enc on Enter admin PIN: Set touch policy of encryption key to on? [y/N]: y % ykman openpgp set-touch sig on Enter admin PIN: Set touch policy of signature key to on? [y/N]: y -
Verify gpg-agent, ssh, and your YubiKey are all playing along nicely. The following should print out your SSH public key; cardno should be the YubiKey’s serial number:
% ssh-add -L ssh-rsa <...> cardno:_________ % -
Use the above SSH public key in
~/.ssh/authorized_keyson your target machine or however you would normally use it. -
Verify everything works. SSH to a host, enter your YubiKey’s OpenPGP PIN when prompted, then tap the YubiKey. Try a slightly longer press if it doesn’t work the first time.