This is a HOWTO for configuring a YubiKey NEO as an OpenPGP smartcard and use as an OpenSSH authentication token. The instructions are written for OS X, but should be nearly identical for Linux and *BSDs. The only dependencies are the YubiKey command-line utilities and GnuPG with native CCID support. If installing GnuPG from source, you'll also need libusb.

I've assembled these instructions from myriad different sources, including my own trial+error experiences. I abstain from citing them here because no particular source was uniquely useful. Rather, for any particular operation it was rather simple to find examples online. But nowhere could I find a document that fit all the pieces together.

The original HOWTO is located at


  1. Purchase YubiKey NEO
  2. Install X Code and Command Line Tools, if installing anything from source.
  3. Install YubiKey reader library libyubikey (aka yubico-c)
  4. Install YubiKey personalization utilities, ykinfo(1) and ykpersonalize(1)
  5. Install GnuPG with native CCID support.

YubiKey Setup

The YubiKey NEO has three different device modes.

  1. OTP HID-only device, mode 0x80. The key behaves like a regular YubiKey or YubiKey Nano when inserted. This is the factory setting.
  2. OpenPGP CCID-only device, mode 0x81. The key only operates as an OpenPGP CCID smartcard token when inserted. The button acts to enable/disable the reader.
  3. OTP HID+OpenPGP CCID, mode 0x82. The key is visible both as an HOTP HID device and OpenPGP CCID smartcard. The button functions as on a regular YubiKey.

Most people change the mode to 0x82, judging by various HOWTOs, FAQs, and Q&As.

  1. $ ykpersonalize -m82
  2. Remove and reinsert card to reboot.

Change the PIN

The PIN numbers can be changed after key generation, if desired.

  1. $ gpg --change-pin

Key Generation

Key generation is quite simple. So don't worry about going through the process multiple times at first, in case you want to change something.

  1. $ gpg --card-edit
    1. gpg/card> admin
    2. gpg/card> generate
      • The factory default PINs are 123456 (user) and 12345678 (admin)
      • Other than the PIN and expiration times, you'll be asked for three additional pieces of information which are ultimately appended together like "Joe Smith (Comment) <>".
        1. Real Name
        2. E-mail Address
        3. Comment
    3. gpg/card> quit

Multimachine Usage

For some inexplicable reason, GnuPG cannot extract the public key from a smartcard except during generation. That means that to use the key from another computer, you either have to copy the public key from the original computer's GnuPG keyring, or you need to set the URL attribute to a file which contains the PGP public key block. Otherwise, the token is effectively locked to a single computer, and unuseable if you happen to trash your keyring unless you regenerate a key.

Export Public Key

  1. $ gpg --card-status
  2. $ gpg --armor --export XXXXXXXX
  3. $ gpg --card-edit
    1. gpg/card> admin
    2. gpg/card> url
    3. Enter the URL from Step 2.
    4. Optionally, set the name, language, and other attributes.
    5. gpg/card> quit

Import Public Key

Presuming you've set the URL attribute on the card, and the URL is visible from your new machine, then

  1. $ gpg --card-status

If for some reason this fails (e.g. you didn't have network access when GnuPG attempted to fetch the key), you may need to fetch explicitly.

  1. $ gpg --card-edit
    1. gpg/card> fetch

OpenSSH Setup

GnuPG's gpg-agent has native support for the OpenSSH ssh-agent protocol, but it needs to be explicitly enabled.

  1. $ echo "enable-ssh-support" >> ~/.gnupg/gpg-agent.conf
  2. Start and restart gpg-agent.
  3. $ gpg --card-status
  4. $ gpgkey2ssh XXXXXXXX
  5. $ export SSH_AUTH_SOCK=~/.gnupg/S.gpg-agent.ssh
  6. $ ssh your@machine

Signed Revocation Failsafe



"Card not present"

Try the command again. GnuPG's quality of implementation leaves much to be desired when it comes to device detection and changes in status.

"Conditions of use not satisfied"

Try unblocking the PIN.

  1. $ gpg --change-pin

Somehow I got one of my cards into this state, and it manifested as an inability to authenticate SSH sessions or sign other keys. I didn't see this particular error message until I tried to sign another key (as opposed to authenticate OpenSSH sessions), and again when I tried to change the PIN in an attempt to debug the situation.

About Author

William Ahern <>


Last Updated: 2014-01-13T23:43:40