yubikey and ssh authentication

Problem: We want to authenticate to remote machines using SSH keys that are not stored on the client (local or remote) machine.

Why? Attackers can copy your private keys if the keys are kept on disk on the client. Although private keys are protected with a passphrase, if the keys are copied, attackers only need to acquire the passphrase (via bruteforce or keylogging).

Solution: Store the private key onto a hardware token. The private key cannot be copied from the token, and attackers need to steal your physical token in order to use it (ignoring any computer hardware compromise).

The YubiKey can’t store SSH keys, but can store GPG keys. We can then utilize OpenPGP key pairs to operate as SSH key pairs, and gpg-agent to cache the passphrase (in lieu of ssh-agent). We do this by specifically creating an authentication subkey and loading that subkey into the YubiKey.

Please send any comments, bugs, or fixes to calvin@isi.edu.

2018-12-22 My good friend Raymond Cheng has an updated guide: Signing Git Commits and SSH Authentication with Yubikey.

2016-03-16 some minor updates.

2015-10-27 Thanks to Dan M. for general feedback and improvements.

2015-09-29 Thanks to Tyler B. for the feedback on gpg-agent.

2015-06-29 Thanks to Eric E. for the question on signed SSH keys.


Install and configure software

  1. GNU/Linux: install gnupg2, gpg-agent, and YubiKey NEO Manager. Mac OS X: install GPG Suite (Beta) and YubiKey NEO Manager.

    OS X and GPG

    Getting GPG to work with OS X can be a frustrating exercise. It's recommended to use GPG Suite, but you can also install it using Homebrew, MacPorts, or from source. You will have to figure out the best configuration for yourself.

    GnuPG 2.x

    We need GnuPG 2.x (gpg2) as opposed to 1.x as recommended by Yubico. 2.x supports the OpenPGP card 2.0 specification and uses scdaemon when interacting with a smart card.

  2. All OS: Run the YubiKey NEO Manager, enable “CCID”. (The NEO supports running all modes at the same time, but is not discussed here).
    GNU/Linux: additionally, make the YubiKey accessible to the user (TODO)

  3. Modify ~/.gnupg/gpg.conf to set your preferences. An example configuration:

    use-agent
    personal-cipher-preferences AES256 AES192 AES CAST5
    personal-digest-preferences SHA512 SHA384 SHA256 SHA224
    cert-digest-algo SHA512
    default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
    

    OpenPGP Best Practices

    When using GPG to create and manage OpenPGP/GPG keys, it's in your best interest to configure it properly and understand why each configuration setting is applied.

    Read the OpenPGP Best Practices guide for more information.

Generate PGP Keys

Generate your PGP keys in a secure environment. Use a LiveCD or LiveUSB distribution of your favorite Linux, and generate the keys directly onto a USB flash drive. The Tails distribution is a good choice.

Although creating the text backups in the tutorial is optional, it’s recommended that you store these backups in a safe place. An encrypted USB drive or CD stored in a safe or safety deposit box are good locations (you can even print them out).

Master Key and Subkeys

Your PGP key consists of a master key and one or many subkeys. The master key will be used to certify (or sign) your subkeys. The subkeys can be configured for one or multiple actions: encrypt, authenticate, or sign. (A signing subkey means to sign data, as opposed to other keys).

Passphrase

If you forget your passphrase, your PGP key cannot be used and any data encrypted using that key will be lost forever!

  1. Generate a new master key:

    $ gpg2 --expert --gen-key
    gpg (GnuPG/MacGPG2) 2.0.26; Copyright (C) 2013 Free Software Foundation, Inc.
    This is free software: you are free to change and redistribute it.
    There is NO WARRANTY, to the extent permitted by law.
    
    Please select what kind of key you want:
       (1) RSA and RSA (default)
       (2) DSA and Elgamal
       (3) DSA (sign only)
       (4) RSA (sign only)
       (7) DSA (set your own capabilities)
       (8) RSA (set your own capabilities)
    Your selection? 8
    
    Possible actions for a RSA key: Sign Certify Encrypt Authenticate
    Current allowed actions: Sign Certify Encrypt
    
       (S) Toggle the sign capability
       (E) Toggle the encrypt capability
       (A) Toggle the authenticate capability
       (Q) Finished
    
    Your selection? s
    
    Possible actions for a RSA key: Sign Certify Encrypt Authenticate
    Current allowed actions: Certify Encrypt
    
       (S) Toggle the sign capability
       (E) Toggle the encrypt capability
       (A) Toggle the authenticate capability
       (Q) Finished
    
    Your selection? e
    
    Possible actions for a RSA key: Sign Certify Encrypt Authenticate
    Current allowed actions: Certify
    
       (S) Toggle the sign capability
       (E) Toggle the encrypt capability
       (A) Toggle the authenticate capability
       (Q) Finished
    
    Your selection? q
    RSA keys may be between 1024 and 8192 bits long.
    What keysize do you want? (2048) 4096
    Requested keysize is 4096 bits
    Please specify how long the key should be valid.
             0 = key does not expire
          <n>  = key expires in n days
          <n>w = key expires in n weeks
          <n>m = key expires in n months
          <n>y = key expires in n years
    Key is valid for? (0) 2y
    Key expires at Sat Mar  4 20:42:38 2017 PST
    Is this correct? (y/N) y
    
    GnuPG needs to construct a user ID to identify your key.
    
    Real name: john doe
    Email address: johndoe@localhost
    Comment:
    You selected this USER-ID:
        "john doe <johndoe@localhost>"
    
    Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
    You need a Passphrase to protect your secret key.
    
    We need to generate a lot of random bytes. It is a good idea to perform
    some other action (type on the keyboard, move the mouse, utilize the
    disks) during the prime generation; this gives the random number
    generator a better chance to gain enough entropy.
    gpg: key 0x07D1E784D2ED9B73 marked as ultimately trusted
    public and secret key created and signed.
    
    gpg: checking the trustdb
    gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
    gpg: depth: 0  valid:   4  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 4u
    gpg: next trustdb check due at 2017-03-04
    pub   4096R/0x07D1E784D2ED9B73 2015-03-06 [expires: 2017-03-05]
          Key fingerprint = EE50 A92F 7A25 E286 5AF3  A8D4 07D1 E784 D2ED 9B73
    uid                 [ultimate] john doe <johndoe@localhost>
    
  2. Create a text backup of the master key:

    $ gpg2 -a --export-secret-keys 07D1E784D2ED9B73 > masterkeys.txt
    
  3. Generate the revocation certificate for the master key:

    $ gpg2 --gen-revoke 07D1E784D2ED9B73 > 07D1E784D2ED9B73-revoke-cert.asc
    sec  4096R/0x07D1E784D2ED9B73 2015-03-06 john doe <johndoe@localhost>
    
    Create a revocation certificate for this key? (y/N) y
    Please select the reason for the revocation:
      0 = No reason specified
      1 = Key has been compromised
      2 = Key is superseded
      3 = Key is no longer used
      Q = Cancel
    (Probably you want to select 1 here)
    Your decision? 3
    Enter an optional description; end it with an empty line:
    >
    Reason for revocation: Key is no longer used
    (No description given)
    Is this okay? (y/N) y
    
    You need a passphrase to unlock the secret key for
    user: "john doe <johndoe@localhost>"
    4096-bit RSA key, ID 0x07D1E784D2ED9B73, created 2015-03-06
    
    ASCII armored output forced.
    Revocation certificate created.
    
    Please move it to a medium which you can hide away; if Mallory gets
    access to this certificate he can use it to make your key unusable.
    It is smart to print this certificate and store it away, just in case
    your media become unreadable.  But have some caution:  The print system of
    your machine might store the data and make it available to others!
    
  4. Generate the authentication subkey:

    Subkey Size and YubiKey

    The NEO limits subkey size to 2048 bits or less. Thus, we recommend that the size of your subkeys to be used with the NEO are 2048 bits.

    $ gpg2 --expert --edit-key 07D1E784D2ED9B73
    gpg (GnuPG/MacGPG2) 2.0.26; Copyright (C) 2013 Free Software Foundation, Inc.
    This is free software: you are free to change and redistribute it.
    There is NO WARRANTY, to the extent permitted by law.
    
    Secret key is available.
    
    pub  4096R/0x07D1E784D2ED9B73  created: 2015-03-06  expires: 2017-03-05  usage: C
                                   trust: ultimate      validity: ultimate
    [ultimate] (1). john doe <johndoe@localhost>
    
    gpg> addkey
    Key is protected.
    
    You need a passphrase to unlock the secret key for
    user: "john doe <johndoe@localhost>"
    4096-bit RSA key, ID 0x07D1E784D2ED9B73, created 2015-03-06
    
    Please select what kind of key you want:
       (3) DSA (sign only)
       (4) RSA (sign only)
       (5) Elgamal (encrypt only)
       (6) RSA (encrypt only)
       (7) DSA (set your own capabilities)
       (8) RSA (set your own capabilities)
    Your selection? 8
    
    Possible actions for a RSA key: Sign Encrypt Authenticate
    Current allowed actions: Sign Encrypt
    
       (S) Toggle the sign capability
       (E) Toggle the encrypt capability
       (A) Toggle the authenticate capability
       (Q) Finished
    
    Your selection? s
    
    Possible actions for a RSA key: Sign Encrypt Authenticate
    Current allowed actions: Encrypt
    
       (S) Toggle the sign capability
       (E) Toggle the encrypt capability
       (A) Toggle the authenticate capability
       (Q) Finished
    
    Your selection? e
    
    Possible actions for a RSA key: Sign Encrypt Authenticate
    Current allowed actions:
    
       (S) Toggle the sign capability
       (E) Toggle the encrypt capability
       (A) Toggle the authenticate capability
       (Q) Finished
    
    Your selection? a
    
    Possible actions for a RSA key: Sign Encrypt Authenticate
    Current allowed actions: Authenticate
    
       (S) Toggle the sign capability
       (E) Toggle the encrypt capability
       (A) Toggle the authenticate capability
       (Q) Finished
    
    Your selection? q
    RSA keys may be between 1024 and 8192 bits long.
    What keysize do you want? (2048) 2048
    Requested keysize is 2048 bits
    Please specify how long the key should be valid.
             0 = key does not expire
          <n>  = key expires in n days
          <n>w = key expires in n weeks
          <n>m = key expires in n months
          <n>y = key expires in n years
    Key is valid for? (0) 2y
    Key expires at Sat Mar  4 20:47:50 2017 PST
    Is this correct? (y/N) y
    Really create? (y/N) y
    We need to generate a lot of random bytes. It is a good idea to perform
    some other action (type on the keyboard, move the mouse, utilize the
    disks) during the prime generation; this gives the random number
    generator a better chance to gain enough entropy.
    
    pub  4096R/0x07D1E784D2ED9B73  created: 2015-03-06  expires: 2017-03-05  usage: C
                                   trust: ultimate      validity: ultimate
    sub  2048R/0xAED9256FF8CEC558  created: 2015-03-06  expires: 2017-03-05  usage: A
    [ultimate] (1). john doe <johndoe@localhost>
    
    gpg> save
    
  5. Export your secret subkeys for backup.

    $ gpg2 -a --export-secret-subkeys 07D1E784D2ED9B73 > subkeys.txt
    

Configure YubiKey

  1. Make sure your YubiKey is plugged in and check if gpg2 can read it:

    $ gpg2 --card-status
    Application ID ...: XXXXXX
    Version ..........: 2.0
    Manufacturer .....: Yubico
    Serial number ....: XXXXXX
    Name of cardholder: [not set]
    Language prefs ...: [not set]
    Sex ..............: unspecified
    URL of public key : [not set]
    Login data .......: [not set]
    Signature PIN ....: forced
    Key attributes ...: 2048R 2048R 2048R
    Max. PIN lengths .: 127 127 127
    PIN retry counter : 3 3 3
    Signature counter : 0
    Signature key ....: [none]
    Encryption key....: [none]
    Authentication key: [none]
    General key info..: [none]
    
  2. Change the PIN and Admin PIN from its defaults (123456 and 12345678, respectively):

    Admin PIN Lockout

    If you incorrectly enter your Admin PIN three (3) times, you will be locked out of your YubiKey and it will be useless.

    You can completely reset your Yubikey if locked out with ResetApplet.

    $ gpg2 --card-edit
    
    gpg/card> admin
    Admin commands are allowed
    
    gpg/card> passwd
    gpg: OpenPGP card no. XXXXXX detected
    
    1 - change PIN
    2 - unblock PIN
    3 - change Admin PIN
    4 - set the Reset Code
    Q - quit
    
    Your selection? 3
    PIN changed.
    ...
    Your selection? 1
    PIN changed.
    ...
    Your selection? q
    
    gpg/card> quit
    

Load PGP keys onto Yubikey

  1. Move the authentication subkey to your YubiKey:

    $ gpg2 --edit-key 07D1E784D2ED9B73
    gpg (GnuPG/MacGPG2) 2.0.26; Copyright (C) 2013 Free Software Foundation, Inc.
    This is free software: you are free to change and redistribute it.
    There is NO WARRANTY, to the extent permitted by law.
    
    Secret key is available.
    
    pub  4096R/0x07D1E784D2ED9B73  created: 2015-03-06  expires: 2017-03-05  usage: C
                                   trust: ultimate      validity: ultimate
    sub  2048R/0xAED9256FF8CEC558  created: 2015-03-06  expires: 2017-03-05  usage: A
    [ultimate] (1). john doe <johndoe@localhost>
    
    gpg> toggle
    
    sec  4096R/0x07D1E784D2ED9B73  created: 2015-03-06  expires: 2017-03-05
    ssb  2048R/0xAED9256FF8CEC558  created: 2015-03-06  expires: never
    (1)  john doe <johndoe@localhost>
    
    gpg> key 1
    
    sec  4096R/0x07D1E784D2ED9B73  created: 2015-03-06  expires: 2017-03-05
    ssb* 2048R/0xAED9256FF8CEC558  created: 2015-03-06  expires: never
    (1)  john doe <johndoe@localhost>
    
    gpg> keytocard
    Signature key ....: [none]
    Encryption key....: [none]
    Authentication key: [none]
    
    Please select where to store the key:
       (3) Authentication key
    Your selection? 3
    
    You need a passphrase to unlock the secret key for
    user: "john doe <johndoe@localhost>"
    2048-bit RSA key, ID 0xAED9256FF8CEC558, created 2015-03-06
    
    
    sec  4096R/0x07D1E784D2ED9B73  created: 2015-03-06  expires: 2017-03-05
    ssb* 2048R/0xAED9256FF8CEC558  created: 2015-03-06  expires: never
                         card-no: 0006 03366476
    (1)  john doe <johndoe@localhost>
    
    gpg> save
    
  2. Verify that the key is on the card:

    $ gpg2 --card-status
    Application ID ...: XXXXXX
    Version ..........: 2.0
    Manufacturer .....: Yubico
    Serial number ....: XXXXXX
    Name of cardholder: [not set]
    Language prefs ...: [not set]
    Sex ..............: unspecified
    URL of public key : [not set]
    Login data .......: [not set]
    Signature PIN ....: forced
    Key attributes ...: 2048R 2048R 2048R
    Max. PIN lengths .: 127 127 127
    PIN retry counter : 3 3 3
    Signature counter : 0
    Signature key ....: [none]
    Encryption key....: [none]
    Authentication key: 4FB8 96F3 32D7 BE1E C178  0CC5 AED9 256F F8CE C558
          created ....: 2015-03-06 04:49:15
    General key info..: pub  2048R/0xAED9256FF8CEC558 2015-03-06 john doe <johndoe@localhost>
    sec   4096R/0x07D1E784D2ED9B73  created: 2015-03-06  expires: 2017-03-05
    ssb>  2048R/0xAED9256FF8CEC558  created: 2015-03-06  expires: 2017-03-05
                          card-no: XXXX XXXXXX
    

Once we move the master key from the local machine and onto offline storage, the master key will appear as sec# in the output of gpg2 --card-status; the # means that the corresponding private key is not present.

We are now ready to use our YubiKey for SSH authentication.

Configure gpg-agent and add your SSH keys

gpg-agent needs to be configured for SSH support. gpg-agent will take over the functionality of ssh-agent.

On OS X, gpg-agent will be launched automatically at startup if you installed GPG Suite.

TODO

Guidance for GNOME Keyring (Seahorse), or other Linux utilities.

  1. Modify ~/.gnupg/gpg-agent.conf:

    # if on Mac OS X and GPG Suite is installed
    # otherwise, look for `pinentry' on your system
    pinentry-program /usr/local/MacGPG2/libexec/pinentry-mac.app/Contents/MacOS/pinentry-mac
    
    # enables SSH support (ssh-agent)
    enable-ssh-support
    
    # writes environment information to ~/.gpg-agent-info
    write-env-file
    use-standard-socket
    
    # default cache timeout of 600 seconds
    default-cache-ttl 600
    max-cache-ttl 7200
    
  2. Append to your ~/.bashrc (or your favorite shell config):

    if [ -f "${HOME}/.gpg-agent-info" ]; then
      . "${HOME}/.gpg-agent-info"
      export GPG_AGENT_INFO
      export SSH_AUTH_SOCK
    fi
    export GPG_TTY=$(tty)
    
  3. If you’ve created your GPG keys on a separate machine (e.g., A) you’ll need to make sure that the machine you’ll be using the Yubikey on (e.g., B) has a copy of the generated public key.

    One way to do this is to upload your public key to a keyserver. Another way is to export the key as an ASCII file and import it manually.

    On machine A:

    $ gpg2 --armor --export AED9256FF8CEC558 > AED9256FF8CEC558.asc
    

    Then on machine B:

    $ gpg2 --import < AED9256FF8CEC558.asc
    
  4. Convert your authentication public subkey to an SSH key (specify the authentication subkey ID):

    $ gpgkey2ssh AED9256FF8CEC558
    ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ... COMMENT
    

    Copy the output into ~/.ssh/authorized_keys on the remote machine (e.g., example.com).

  5. You can also check if your YubiKey is working with ssh-add -L.

    $ ssh-add -L
    ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ... cardno:XXXXXXXXXXXX
    

Test the SSH connection

We can now test an SSH connection to the remote machine. We will be asked for the PIN to unlock the key; if successful, we will be able to SSH successfully.

  1. Use the -v verbose flag with ssh to see which key is being used:

    $ ssh -v example.com
    OpenSSH_6.7p1, OpenSSL 1.0.2 22 Jan 2015
    debug1: Connecting to example.com [127.0.0.1] port 22.
    debug1: Connection established.
    debug1: Enabling compatibility mode for protocol 2.0
    debug1: Local version string SSH-2.0-OpenSSH_6.7
    debug1: Remote protocol version 2.0, remote software version OpenSSH_6.4
    debug1: match: OpenSSH_6.4 pat OpenSSH* compat 0x04000000
    debug1: SSH2_MSG_KEXINIT sent
    debug1: SSH2_MSG_KEXINIT received
    debug1: kex: server->client aes128-ctr umac-64-etm@openssh.com none
    debug1: kex: client->server aes128-ctr umac-64-etm@openssh.com none
    debug1: sending SSH2_MSG_KEX_ECDH_INIT
    debug1: expecting SSH2_MSG_KEX_ECDH_REPLY
    debug1: Server host key: RSA xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx
    debug1: Host 'example.com' is known and matches the RSA host key.
    debug1: SSH2_MSG_NEWKEYS sent
    debug1: expecting SSH2_MSG_NEWKEYS
    debug1: SSH2_MSG_NEWKEYS received
    debug1: Roaming not allowed by server
    debug1: SSH2_MSG_SERVICE_REQUEST sent
    debug1: SSH2_MSG_SERVICE_ACCEPT received
    debug1: Authentications that can continue: publickey,gssapi-keyex,gssapi-with-mic
    debug1: Next authentication method: publickey
    # this is where we see our YubiKey is being used
    debug1: Offering RSA public key: cardno:XXXXXXXXXXXX
    debug1: Server accepts key: pkalg ssh-rsa blen 279
    debug1: Authentication succeeded (publickey).
    Authenticated to localhost ([127.0.0.1]:22).
    debug1: channel 0: new [client-session]
    debug1: Requesting no-more-sessions@openssh.com
    debug1: Entering interactive session.
    [user@localhost]~$
    

Troubleshooting

Some tips and solutions for when things don’t work out flawlessly.

Mac OS X: Could not open a connection…

When running ssh-add -L (in Step 5.4), you might get an error:

Could not open a connection to your authentication agent.

This is likely because ssh-agent is also running at the same time, and the environment variables have been properly set (i.e., ssh will look at env variables SSH_AGENT_PID and SSH_AGENT_SOCK).

After killing ssh-agent, run gpg-agent:

eval gpg-agent --daemon --enable-ssh-support

The right environment variables will be set for that particular shell, and you should be able to successfully SSH into your server.

Once this is working, we need to make sure gpg-agent runs at startup by creating a new .plist and placing it in the LaunchAgent directory. This guide covers creating the .plist.

2015-09-29 Thanks to Tyler B. for the feedback and troubleshooting.

Other Things

Miscellaneous things that have been or need to be figured out.

gpg2 and ~/.gnupg

gpg2 does some different things to ~/.gnupg compared to gpg.

In particular, what is stored in ~/.gnupg/private-keys-v1.d? Does it store the cached passphrases?

gpg-agent cache clearing

How do I manually clear the gpg-agent cache? The easiest way is to probably use gpg-connect-agent reloadagent /bye.

Even if you remove the YubiKey (the secret key supposedly never leaves it), the password is still cached (I think). One would want to destroy the cache when the screensaver starts, for example.

2016-03-15 Updated with relevant info.

gpg-agent forwarding

It’d be great if we could forward gpg-agent to remote machines. This would let you decrypt email on a remote machine, for example. Apparently it’s possible to do this with OpenSSH 6.7.

2016-03-15 We can do this now. See remote gpg-agent via ssh forwarding.

signed SSH keys

To prevent arbitrary keys being added to your authorized_keys, it’s possible to have your SSH Certificate Authority (CA) sign your keys and only accept signed SSH keys for authentication.

We don’t cover the signing process here, but since your exported SSH public key (generated from your GPG auth subkey) is an OpenSSH-compatible public key, there should be no issues here. Simply send your new SSH public key to be signed by the SSH CA.

Remember that it isn’t possible to take an existing SSH keypair (generated via ssh-keygen) and import the private key to your NEO. This might be an issue if you already have an existing signed SSH keypair that you would like to reuse.

The NEO only supports loading GPG keys into the dongle and what makes all of this work is that your GPG authentication subkey can be exported as an SSH public key.

2015-06-29 Thanks to Eric E. for the question.