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). These instructions only need to be carried out once per device you wish to connect with. You do not need to do this on lab computers -- it is already done!


Windows

GPG4Win: gpg4win-4.3.1.exe (source: https://www.gpg4win.org)
gpg-agent.conf: gpg-agent.conf
  1. Install GPG4Win. You only need to install the main GnuPG component.
  2. Insert Yubikey.
  3. Open a command prompt (e.g. by searching for cmd.exe).
  4. Run gpg --version. Put the file gpg-agent.conf from above into the home directory listed.
  5. Run gpg-connect-agent KILLAGENT /bye.
  6. Run gpg --card-status. It should print information about your Yubikey.
  7. Thats it! You can now use your Yubikey for authentication with laboratory systems. If using puTTY, make sure "attempt authentication using pageant" is checked in the puTTY configuration

Windows 2000/XP/Vista/7 Note

GPG4Win: gpg4win-3.1.11.exe (source: https://www.gpg4win.org)
OpenSC: opensc-0.25.1-win32.msi (source: https://github.com/OpenSC/OpenSC/wiki)
OpenSC: opensc-0.25.1-win64.msi (source: https://github.com/OpenSC/OpenSC/wiki)

On older versions of windows 2000/XP/Vista/7, you may need to install the OpenSC driver. Download the OpenSC minidriver and install before installing GPG4Win. You may also need the older 3.1.11 version of GPG4Win here instead of the latest.


Windows Sleep/Resume Note

gpg-agent.bat: gpg-agent.bat

As of the time of writing, some windows versions have 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 (create a new task). Name it gpg-agent. 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. If WudfUsbccidDrv does not appear in the list, you need to reboot and remove and reinsert the Yubikey before adding the task.


Mac OS X (Up to 10.14)

MacGPG2: GPG_Suite-2019.2.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. That's it! Now you can use your hardware token to connect to servers via SSH/SCP/SFTP.

Mac OS X (10.15+)

MacGPG2: GPG_Suite-2023.3.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
  3. Edit ~/.bash_profile and add:
    export SSH_AUTH_SOCK=~/.gnupg/S.gpg-agent.ssh
  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. That's it! Now you can use your hardware token to connect to servers via SSH/SCP/SFTP.

Mac OS X Notes

The above does not allow using the hardware token with native OS X apps, due to change made by Apple in 10.11 and above 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.

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, and it will have already been added to all lab systems. For information on configuring a Yubikey, see Yubikey Configuration.


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.