Yubikey for SSH Authentication

This page describes a robust approach for configuration and use of a Yubikey for SSH authentication. It is based on a variety of web sources. These instructions assume you have been given a preconfigured Yubikey (or have already configured it yourself). For information on configuring a Yubikey, see Yubikey Configuration. These instructions only need to be carried out once per device you wish to connect with.


Common Notes

As with all key-based authentication methods, for each server you want to connect to, add the SSH-formatted public key to the ~/.ssh/authorized_keys file on the server (as with any other keypair). If you are provided with a preconfigured Yubikey, you will be told where the public key can be accessed. On lab computers, you only need to download and import the public keys into gpg; all software is already installed.


Windows

GPG4Win: gpg4win-vanilla-2.3.0.exe (source: https://www.gpg4win.org)
OpenSC: opensc-0.15.0-win64.msi (source: https://github.com/OpenSC/OpenSC/wiki)
gpg-agent.conf: gpg-agent.conf
gpg-agent.bat: gpg-agent.bat
  1. Install OpenSC (at least the minidriver).
  2. Install GPG4Win (vanilla).
  3. Insert Yubikey.
  4. Open a command prompt (e.g. by running cmd.exe).
  5. Run gpg --version. Put the file gpg-agent.conf into the home directory listed.
  6. Run gpg --card-status to print information about the Yubikey.
  7. Download the file containing the public keys (URL specified in the card status listing).
  8. Import the public keys: gpg --import <file-you-downloaded-in-previous-step>
  9. REBOOT
  10. If using puTTY, make sure "attempt authentication using pageant" is checked in the puTTY configuration

That's it! Now you can use your hardware token to connect to servers via SSH. Note that if you previously used private key files with puTTY, you need to make sure to remove the reference to that file in the "Private key file for authentication" configuration box. Further, if you were using pageant to store private keys, you must make sure it no longer loads (gpg-agent replaces pageant).

  1. As of the time of writing, GPG4Win has issues using Yubikey after the system sleeps or any number of other events. Further, it is desirable to have gpg-agent start automatically when a Yubikey is inserted. To do so, download gpg-agent.bat. Then goto control panel -> administrative tools -> task scheduler and add a new task. Under triggers, make it on an event, from log system, source "WudfUsbccidDrv", event ID 105. Under actions, set it to run gpg-agent.bat. Under conditions, make sure all conditions are unchecked. NOTE: if WudfUsbccidDrv does not appear in the list, you need to reboot and remove and reinsert the Yubikey before adding the task.
  2. Finally, remove and reinsert the Yubikey. You should see a command prompt briefly appear as the gpg-agent restarts. You should then be able to login with it on any system to which you have added the SSH public key.

Mac OS X

MacGPG2: GPG_Suite-2015.09.dmg (source: https://gpgtools.org/)
  1. Install MacGPG2 from GPG_Suite (do a custom install, uncheck everything but MacGPG2).
  2. In a terminal window:
    mkdir ~/.gnupg (if this fails, not a problem)
    sudo mv ~/.gnupg/gpg-agent.conf ~/.gnupg/gpg-agent.conf.save (if this fails, not a problem)
    echo "enable-ssh-support" >> ~/.gnupg/gpg-agent.conf
    echo "write-env-file ${HOME}/.gpg-agent-info" >> ~/.gnupg/gpg-agent.conf
  3. Edit ~/.bash_profile and add:
    if [ -f "${HOME}/.gpg-agent-info" ]; then
    . "${HOME}/.gpg-agent-info"
    export GPG_AGENT_INFO
    export SSH_AUTH_SOCK
    fi
    export GPG_TTY=$(tty)
  4. If ~/.bash_login exists, add to the end of ~/.bash_profile:
    source ~/.bash_login
  5. If ~/.profile exists, add to the end of ~/.bash_profile:
    source ~/.profile
  6. Close all terminal windows, and then quit the terminal program
  7. REBOOT
  8. Insert Yubikey.
  9. In a terminal window:
    gpg --card-status (the details of your card should be shown)
    curl <URL-here> | gpg --import (replace <URL-here> with the public key url from the card-status command)
  10. Close the terminal window and reopen it.

That's it! Now you can use your hardware token to connect to servers via SSH. The above does not allow using the hardware token with native OS X apps, due to change made by Apple in 10.11 that precludes the use of OpenPGP keys for SSH authentication in native applications (complain to apple). Further, 10.10 has many bugs in the hardware token software provided by Apple (pcsc-lite). Make sure you have applied all Apple updates in order to have a usable version of the software on 10.10.


UNIX/Linux/BSD

Similar to OS X. You can also setup udev rules and disable gnome keyring to ensure the hardware token is used for ssh.

For example, for recent Ubuntu-based distributions, you can do the following:

  1. In a terminal window:
    sudo apt-get install gnupg2 scdaemon pcscd
    sudo apt-get remove libpam-gnome-keyring
    xfconf-query -c xfce4-session -p /startup/ssh-agent/enabled -n -t bool -s false
    mkdir ~/.gnupg (if this fails, not a problem)
    sudo mv ~/.gnupg/gpg-agent.conf ~/.gnupg/gpg-agent.conf.save (if this fails, not a problem)
    echo "enable-ssh-support" >> ~/.gnupg/gpg-agent.conf
    echo "write-env-file ${HOME}/.gpg-agent-info" >> ~/.gnupg/gpg-agent.conf
  2. Goto settings->session and startup->advanced->untick launch gnome services on startup (may be listed as ssh agent)
  3. Edit ~/.gpg-yubikey and add:
    if [ ! -f "${HOME}/.gpg-agent-info" ] && [ -S "${HOME}/.gnupg/S.gpg-agent" ] && [ -S "${HOME}/.gnupg/S.gpg-agent.ssh" ]; then
    echo "GPG_AGENT_INFO=${HOME}/.gnupg/S.gpg-agent" >> "${HOME}/.gpg-agent-info";
    echo "SSH_AUTH_SOCK=${HOME}/.gnupg/S.gpg-agent.ssh" >> "${HOME}/.gpg-agent-info";
    fi

    if [ -f "${HOME}/.gpg-agent-info" ]; then
    . "${HOME}/.gpg-agent-info"
    export GPG_AGENT_INFO
    export SSH_AUTH_SOCK
    export GPG_TTY=$(tty)
    gpg-connect-agent updatestartuptty /bye >& /dev/null
    fi
  4. Edit ~/.bash_profile and add:
    source ~/.gpg-yubikey
  5. If ~/.bash_login exists, add to the end of ~/.bash_profile:
    source ~/.bash_login
  6. If ~/.profile exists, add to the end of ~/.bash_profile:
    source ~/.profile
  7. Edit ~/.bashrc and add:
    source ~/.gpg-yubikey
  8. Do sudo nano /etc/udev/rules.d/99-yubikeys.rules and add (replace username with your username):
    ACTION=="add",SUBSYSTEM=="usb", ATTR{idVendor}=="1050", ATTR{idProduct}=="0404", OWNER="username"
  9. Do sudo nano /etc/X11/Xsession.options and comment out use-ssh-agent
  10. REBOOT
  11. Insert Yubikey.
  12. In a terminal window:
    gpg2 --card-status (the details of your card should be shown)
    curl <URL-here> | gpg2 --import (replace <URL-here> with the public key url from the card-status command)
  13. Close the terminal window and reopen it.

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.