Posts Tagged GPG
YubiKey GPG key for SSH authentication
Posted by MB in Uncategorized on September 7, 2017
In this post I’m going to go over the steps to configure your YubiKey for SSH authentication using a GPG key stored on the YubiKey itself.
This guide goes through the steps for setting this up on a Mac running OS X. Although the concepts of doing this under Linux and Windows are the same, the exact steps will be different.
Ensure your YubiKey has CCID mode enabled
Per Yubico’s site, this is usually enabled by default:
“Note that all YubiKey NEOs shipped after November 2015 come preconfigured with all modes enabled.” — yubico.com
If you’re using an older YubiKey and need to enable it, you’ll want to download the YubiKey NEO Manager from Yubico’s website and run it to ensure that your YubiKey has CCID mode enabled. The link to this tool and instructions to run it are here.
Once you’re certain that CCID mode is enabled, you can move ahead with the next section.
Install GPG
The remainder of the steps in this guide use the command line interface for GPG tools. If you don’t have either GPG Tools or GnuPG installed, install one of them. If you already have one installed, you can skip on to the next section.
GPG Tools provides a nice set of GUI tools and is recommend for most users, but if you’re not afraid of the command line and have Homebrew installed on your Mac, you can install GnuPG2 using Homebrew with the following command:
brew install gnupg2
Decide if you want to require touch
YubiKey will prompt for your PIN during SSH authentication. Starting with YubiKey version 4, YubiKey can also require a touch on the sensor during authentication. Enabling this will require a touch confirmation on the touch sensor for each and every SSH connection.
If you want to enable this, it is highly recommend that you install and use the Yubikey Manager CLI using the instructions from this page. Once installed, you can enable touch using the following command:
ykman openpgp touch aut <'on'|'off'|'fixed'>
If you want more information on these specific policies, please see this page under the heading “Yubikey 4 touch”. IMPORTANT NOTE: A link to a bash script to enable touch is found on that page. Because the behavior of that script requires providing your admin key on the command line, it should be considered insecure. I highly recommend using the ykman
tool instead whenever possible.
Unless you set ‘fixed’, (ON_FIXED), you can always come back and change this setting later. If you set fixed, you can’t change it until you put a new secret key onto the YubiKey.
Change the YubiKey PINs
Before continuing, it’s you should change the YubiKey PINs from their defaults if you have not already. The default PIN is 123456 and the default admin pin is 12345678.
To do this, start by running: gpg --card-edit
Once you have the card editor open, allow admin commands by running admin
Then, open the PIN change dialog with passwd
From here, set your PIN, Admin PIN, and reset code. Store these in a safe place.
Once you’ve set your PINs, you can further personalize the data on the card. Here’s the full list of commands available after running admin
:
gpg/card> help quit quit this menu admin show admin commands help show this help list list all available data name change card holder's name url change URL to retrieve key fetch fetch the key specified in the card URL login change the login name lang change the language preferences sex change card holder's sex cafpr change a CA fingerprint forcesig toggle the signature force PIN flag generate generate new keys passwd menu to change or unblock the PIN verify verify the PIN and list all data unblock unblock the PIN using a Reset Code
Generate and move a GPG key to the YubiKey
If you already have a set of GPG tools installed and your own key generated and available within those tools, good on you! Run the following commands to be sure:
gpg --list-keys
gpg --list-secret-keys
If your public and secret keys do show up as expected, there’s no need to generate another key. You simply need to move your existing key to the YubiKey.
IMPORTANT NOTE: If you want to make use of the ability to revoke your key in the future, then you must generate the revocation certificate before moving the key to your YubiKey. Once you move a key to your YubiKey, it is not possible to generate a revocation certificate unless you have a full backup of the secret key somewhere and are able to re-import it to your GPG keyring.
To move your secret key from your GPG keyring to your YubiKey, go to this page and start where it says “To import the key on your YubiKey”
If you need to generate a GPG key for SSH authentication, take a look at this guide and follow one of the two methods provided.
Once your key is generated and moved to the card, you’re all set to move on to the next section.
Making it all work locally
This part requires editing just a few files to make gpg-agent work as expected.
Really important note: Starting with GnuPG 2.1, the –write-env-file is obsolete. See the GnuPG 2.1 FAQ for more information. The following instructions have been updated with configuration information for versions both below and above GnuPG 2.1. A reader, Nick, confirms these instructions work for versions starting at 2.1, and eliminate the error message that appears regarding write-env-file being obsolete.
If any of the below configuration instructions do not work for you, I recommend that you reach out to the GnuPG mailing list for more help.
You can check your GPG version with:
gpg-agent --version
A precautionary note:
For GPG versions before 2.1, add the following to ~/.bash_profile
:
[ -f ~/.gpg-agent-info ] && source ~/.gpg-agent-info if [ -S "${GPG_AGENT_INFO%%:*}" ]; then export GPG_AGENT_INFO export SSH_AUTH_SOCK export SSH_AGENT_PID else eval $( gpg-agent --daemon --write-env-file ~/.gpg-agent-info ) fi
For GPG versions at or above 2.1, add the following to ~/.bash_profile
:
GPG_TTY=$(/usr/bin/tty) SSH_AUTH_SOCK="$HOME/.gnupg/S.gpg-agent.ssh" export GPG_TTY SSH_AUTH_SOCK gpgconf --launch gpg-agent
For GPG versions before 2.1, add the following to ~/.gnupg/gpg-agent.conf
:
enable-ssh-support write-env-file ~/.gpg-agent-info pinentry-program /usr/local/MacGPG2/libexec/pinentry-mac.app/Contents/MacOS/pinentry-mac
For GPG versions at or above 2.1, add the following to ~/.gnupg/gpg-agent.conf
:
enable-ssh-support ~/.gpg-agent-info pinentry-program /usr/local/MacGPG2/libexec/pinentry-mac.app/Contents/MacOS/pinentry-mac
Restart gpg-agent
:
sudo killall gpg-agent source ~/.bash_profile source ~/.gpg-agent-info
Get your SSH public key
Use the following command to get the SSH public key that corresponds to the key installed on your YubiKey:
ssh-add -L | grep cardno
This can be installed on any server that you want to use your YubiKey-stored key to access.