Yubikey for SSH Authentication (Initial Configuration of a Yubikey)
GPG 2.0.22 or later is required to interface appropriately with the Yubikey. If not already installed, install GPG 2. Further, the Yubikey must
be configured with at least CCID mode enabled. This is true by default on Yubikey 4 and newer, and can be done on Yubikey NEO. If needed, use the ykpersonalize
or ykneomgr tool (links at end) to set the mode.
- Generate Keys on Device (or, alternately, a secure offline system, see below):
gpg --card-edit
admin
generate (This generates the keypairs (4096 bit recommended, if supported), and will take some time. Choose a PIN as well.)
quit
gpg --list-keys
gpg --output <keyname>_pub.gpg --armor --export <key-name> (for each key listed by previous command).
- Get the SSH-formatted public key. This is annoying, but most easily done by connecting to any linux system
using puTTY with agent forwarding enabled, and then running ssh-add -L, which will print a line starting with ssh-rsa and ending
with card...
- For each system you want to use the yubikey to authenticate with, add the SSH-formatted public key from the previous step
to the ~/.ssh/authorized_keys file on the system, as with any other keypair.
Alternate Key Generation Procedure
Rather than generate the keys on-device, keys can be generated on an off-line, hardware entropy source system and then transferred. On a linux system, do:
mkdir /mnt/ramdisk
mount -t ramfs -o size=10M ramfs /mnt/ramdisk
gpg-agent --daemon --enable-ssh-support --homedir=/mnt/ramdisk [make sure to copy and paste the SSH variables and export bits and run)
gpg --homedir /mnt/ramdisk --expert --gen-key
Select Number 8. Make sure only one of Sign,Encrypt,Authentication enabled. Choose length, name, and expire period
gpg --homedir=/mnt/ramdisk --edit-key <name>
toggle [shows secret keys]
keytocard, select slot corresponding to Sign,Encrypt,Authentication selected above
quit (yes save changes)
Repeat starting at the --gen-key step for the other two of Sign,Encrypt,Authentication.
gpg --homedir=/mnt/ramdisk --card-status (make sure all three keys are listed)
gpg --homedir=/mnt/ramdisk --output SignKey_pub.gpg --armor --export <sign-name>
gpg --homedir=/mnt/ramdisk --output EncryptKey_pub.gpg --armor --export <encrypt-name>
gpg --homedir=/mnt/ramdisk --output AuthKey_pub.gpg --armor --export <authenticate-name>
gpg-connect-agent "KILLAGENT" /bye
umount /mnt/ramdisk
Useful Tools
gpg-yubikey-reset.bat (Resets OpenPGP Yubikey; WARNING: any previous keys unrecoverable after running!)
Welcome to the collection of programs and patches that we are publically releasing
in the hope that others find them useful. They are provided WITHOUT ANY WARRANTY;
without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Copyrights remain with the owners
of the respective works.
