YubiKey: GPG keys and SSH authentication
Use a YubiKey as an OpenPGP card: PINs, SSH authentication through the GPG agent and troubleshooting on Windows.
Use a YubiKey as an OpenPGP smart card: check the card, manage the PINs, use the GPG key for SSH authentication and fix common GPG agent issues on Windows. KEYID stands for a key ID.
Check and configure the card
gpg --card-status
gpg --card-edit
gpg --card-status shows the keys stored on the YubiKey and the remaining PIN retries. gpg --card-edit opens the card editor (type admin for administration commands, then passwd to change the PINs).
Factory PINs of the OpenPGP application: 123456 for the user PIN and 12345678 for the admin PIN. Change them as soon as you start using the key.
To edit a key and its subkeys (for example to move a subkey to the card with keytocard):
gpg --expert --edit-key KEYID
SSH authentication with the GPG key
The GPG agent can act as an SSH agent and use the YubiKey authentication subkey.
- Enable SSH support in
gpg-agent.conf(~/.gnupg/gpg-agent.confon Linux):
On Windows, with PuTTY or a Pageant-compatible client, also add:enable-ssh-supportenable-putty-support - On Linux, point SSH to the GPG agent:
export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket) gpg-connect-agent updatestartuptty /bye - Export the public key in SSH format and add it to
~/.ssh/authorized_keyson the server:gpg --export-ssh-key KEYID - Check that the agent sees the key:
ssh-add -L
Restart the GPG agent on Windows
A path with spaces must be fully quoted, otherwise cmd answers 'C:\Program' is not recognized as an internal or external command:
"C:\Program Files (x86)\GNU\GnuPG\gpg-connect-agent.exe" /bye
Stop and start the agent again:
gpg-connect-agent killagent /bye
gpg-connect-agent /bye
After killagent, an ERR 67125247 End of file <GPG Agent> message is expected: the agent stopped before answering.
Sign and trust a key
gpg --edit-key KEYID
gpg> sign
gpg> trust
gpg> q
GnuPG asks for a confirmation, then for the passphrase. For trust, usually choose "full trust" (4) for a third-party key you have checked.
Verify a downloaded file with its detached signature:
gpg --verify KeePass-2.35-Setup.exe.asc KeePass-2.35-Setup.exe
Get a key ID in a script
gpg --list-keys --with-colons | awk -F: '/^pub/ {print $5}'
gpg --list-keys --with-colons | awk -F: '/^sub/ {print $5}'
The --with-colons format is stable and meant for scripts: field 5 holds the long ID of the key (or subkey). The old method that cuts 2048R/ABCD1234 out of the human-readable output no longer works with GnuPG 2.1 and later, which show the full fingerprint.
Unblock PIV with the PUK on Windows
For the PIV application (not OpenPGP): on Windows 7, enter the PUK in hexadecimal in the "Response" field (the factory PUK 12345678 becomes 3132333435363738). On Windows 8, Server 2012 and later, enter it as plain text in the PIN unblocking field.
Keyboard layout
In OTP mode, the YubiKey acts as a US QWERTY keyboard. On a computer with AZERTY or another layout, some generated characters may be wrong: see YubiKey and keyboard layouts.
References
- drduh/YubiKey-Guide: complete guide (offline key generation, subkeys, smart card).
- Yubico: using your YubiKey with OpenPGP
- GnuPG for SSH authentication
- SSH authentication with your PGP key
- PowerShell: encrypt files with GPG
Notes
- Never write down the PINs, OTP secrets or challenge-response keys of your YubiKey in a note: they make it possible to clone or reset it.
- Keep an offline backup of the master key: a key moved to the card with
keytocardno longer exists on disk.