Yubico Forum

Thanks to William Ahern <william@25thandClement.com> for this how-to

Introduction

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 http://25thandClement.com/~william/YubiKey_NEO.md

Preparation

Purchase YubiKey NEO
Install X Code and Command Line Tools, if installing anything from source.
X Code can be installed from the App Store.
Command Line Tools are installed from X Code: X Code -> Preferences -> Downloads -> Components -> Command Line Tools.
Install YubiKey reader library libyubikey (aka yubico-c)
From source code
$ sudo mkdir /usr/local/yubi
$ sudo chown $(id -nru):$(id -nrg) /usr/local/yubi
$ mkdir /usr/local/yubi/src
$ cd /usr/local/yubi/src
$ ftp http://yubico-c.googlecode.com/files/li ... .10.tar.gz
$ tar -xzf libyubikey-1.10.tar.gz
$ cd libyubikey-1.10
$ ./configure --prefix=/usr/local/yubi
$ make && make install
Install YubiKey personalization utilities, ykinfo(1) and ykpersonalize(1)
From source code
$ cd /usr/local/yubi/src
$ ftp http://opensource.yubico.com/yubikey-pe ... 4.0.tar.gz
$ tar -xzf ykpers-1.14.0.tar.gz
$ cd ykpers-1.14.0
$ ./configure --prefix=/usr/local/yubi
$ make && make install
Install GnuPG with native CCID support.
GPG Tools: https://gpgtools.org/
To access the command-line utilities after installation
Open a new Terminal window; or
$ eval $(path_helper)
From source code
I got close but gave up after finding GPG Tools. Some tips:
You need both libusbx and libusb-compat to get native CCID support.
If installing GPG2: yes, you need to install all of those crazy libraries---libgpg-error, libgcrypt, libassuan, and libkbsa.
GPG2 expects the old libusb-compat API, not the updated API. libusb-compat requires libusb-1.0 (aka libusbx), so you must install both.
When compiling libusb-compat, you need to explicitly link against libusb-1.0 by passing LDFLAGS="-lusb-1.0" to configure, otherwise you'll get an error about not finding _libusb_init when running gpg.

YubiKey Setup

The YubiKey NEO has three different device modes.

OTP HID-only device, mode 0x80. The key behaves like a regular YubiKey or YubiKey Nano when inserted. This is the factory setting.
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.
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.

$ ykpersonalize -m82
May need to give full path: /usr/local/yubi/bin/ykpersonalize -m82
Remove and reinsert card to reboot.

Change the PIN

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

$ gpg --change-pin
The factory default PINs are 123456 (user) and 12345678 (admin).

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.

$ gpg --card-edit
gpg/card> admin
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) <jsmith@gmail.com>".
Real Name
E-mail Address
Comment
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

$ gpg --card-status
Make note of the 4-byte (8 hex character) Signature key identifier. The identifier is the last 4 bytes (8 hex characters) of the Signature key fingerprint.
$ gpg --armor --export XXXXXXXX
XXXXXXXX is the Signature key identifier from Step 1.
Copy the output as a regular text file to a publicly accessible web server. You can re-run this command as many times as necessary.
$ gpg --card-edit
gpg/card> admin
gpg/card> url
Enter the URL from Step 2.
Optionally, set the name, language, and other attributes.
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

$ gpg --card-status
As long as the URL attribute is configured properly, then GnuPG will fetch and import the public key automatically, and the token will be available for use.

OpenSSH Setup

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

$ echo "enable-ssh-support" >> ~/.gnupg/gpg-agent.conf
Start and restart gpg-agent.
GPG Tools will have added gpg-agent to your launchd configuration, so it should already be running. Kill it and launchd will restart it.
$ pkill gpg-agent
$ gpg --card-status
Make note of the 4-byte (8 hex character) Authentication identifier. The identifier is the last 4 bytes (8 hex characters) of the Authentication key fingerprint.
$ gpgkey2ssh XXXXXXXX
XXXXXXXX is the Authentication key identifier from Step 3.
Append the output to .ssh/authorized_keys on your remote machines. You can re-run this command as many times as necessary.
$ export SSH_AUTH_SOCK=~/.gnupg/S.gpg-agent.ssh
You don't necessarily need to stop OpenSSH's ssh-agent. What matters is that SSH_AUTH_SOCK points to GnuPG's ssh-agent socket at the time you invoke ssh.
You may or may not want to fiddle with setting SSH_AUTH_SOCK in ~/.profile or similar shell initialization file.
It's possible that your GnuPG installation places the ssh-agent socket elsewhere. To get the path:
$ gpg-connect-agent "getinfo ssh_socket_name" /bye
$ ssh your@machine
You probably want to verify somehow that you're authenticating with your smartcard and not a key under ~/.ssh.


Signed Revocation Failsafe

FIXME.

About Author

William Ahern <william@25thandClement.com>

Homepage: http://25thandClement.com/~william/

_________________
-Tom

This might be helpful for Windows users:
http://www.bootc.net/archives/2013/06/0 ... ent-setup/

Basically, with a little configuration to enable the flag, gpg-agent works as a pageant replacement, allowing ssh logins with any GPG key, including a GPG key stored on a yubikey or other OpenGPG card.

gpgkey2ssh won't seem to return a valid ssh public key for me (placing it on a remote server results in failed public key auth). Instead I used to list all of the keys in the agent which includes one with a comment of cardno:000000000001 which is the yubikey neo. The public key returned from ssh-add worked for me.

For those on MacOS using Homebrew you can:


and

On Mac / OS X, if you install GPGTools, sometimes /usr/local/bin/gpg remains pointing at the homebrew gpg. If that's the case, use gpg2 instead (also created in /usr/local/bin), or use the full path:



Similarly, use the full path for this utility:



Everything else remains the same.

_________________
Florin Andrei
http://florin.myip.org/

There appears to be a way to run ssh with the private key stored on the NEO, without creating the ~/.gnupg keyring. Just put the public key in authorized_keys on the remote machine. Then on the local machine plug the NEO into USB, and create and run this wrapper with all the options you'd normally pass to ssh:



The full howto is here:

https://blog.habets.se/2013/02/GPG-and- ... ubikey-NEO

Overall, it's as I've suspected - the keyring is not entirely needed for this purpose, since the key that you actually need is on the NEO. I wonder if things could be simplified even more, perhaps getting rid of the wrapper script too.

_________________
Florin Andrei
http://florin.myip.org/

Yeah, it's confirmed. You can run ssh with the Yubikey NEO on any machine and you don't need to setup a keyring there, or import anything. The easiest way to test it is this:

Plug the NEO into another system, where you've never used it before. All you need is to make sure you've installed gpg-agent, and some kind of SCDaemon - on OS X you get both if you do "brew install gnupg2" (gpg-agent is installed as a dependency). Then run:



That's it. I believe that should also work on Linux, as long as you have all the software you need (gpg-agent, the SC stuff) already installed. Just plug the NEO into the new system, and run ssh from within gpg-agent. It will connect to hostname and, assuming you've placed your public key there already, it will log in.

You could probably alias ssh to 'gpg-agent --enable-ssh-support --daemon ssh' and it should just work, I think. Or you could have gpg-agent run every time you log in, and then you just run ssh/scp/sftp as usual, and don't worry about anything - but that depends on the OS you're using. I already have a working procedure for OS X. I hope I'll be able to also try it on a couple Linux distros.

I'll post here again if/when I figure out a few more things.

_________________
Florin Andrei
http://florin.myip.org/

The original HOWTO recommends compiling and installing a lot of libraries and utilities, such as libyubikey, ykinfo, etc. This is only necessary on a system where you're changing the NEO's connection mode (from the default 'HID' mode which can only do OTP, to the 'HID + CCID with touch eject' mode required for OTP + smartcard). It's not necessary to do that on the system where you're creating/managing the keys on the token - all you need there is the gpg utility. It's not necessary on whatever system you're running the ssh client - all you need there is gpg-agent.

Even if you need to change the connection mode, you could use the Yubikey NEO Manager instead:

https://developers.yubico.com/yubikey-neo-manager/

It has binary packages for Win and Mac (not sure about Linux) that don't require any external libraries. (It may require libraries if you're building from source on Linux - see website.)

E.g., on a Mac, if you install the Manager, and GPG Tools, you have everything you need to configure the connection mode on the token, create/manage keys, and use the token with ssh. If you don't need to change the connection mode on the token, then you only need GPG Tools.

On Linux, if you just install gpg and gpg-agent (the packages are called gnupg and gnupg-agent on Ubuntu), you can do everything except change the connection mode on the token (which you likely only need to do once).

Bottom line - on a client system, where you just plug the token into USB and run ssh, you only need to make sure you have a working gpg-agent, that's it. Change the connection mode with Yubikey NEO Manager on Windows, or something, then move it to Linux and use gpg/gpg-agent for everything else. This should make the HOWTO a lot less scary for beginners.

_________________
Florin Andrei
http://florin.myip.org/

The HOWTO claims:



This is not entirely true. Indeed, gpg doesn't seem (?) to be able to extract the public SSH key from the token without the whole keyring, but the SSH utilities can. On any Unix derivative, plug the NEO into USB and run:



...and it will extract your public SSH key from the NEO token. For convenience, replace the "cardno:XXXXXXXXXXX" comment at the end of the key with your email address, or whatever identifies you.

Or, if you're on a system where gpg-agent is already running and is configured to cooperate with ssh, then simply run:



Again, replace the generic comment at the end with something more personal.

So, no need to worry about your public SSH key - it's on the NEO, and you can extract it from there whenever you want.

_________________
Florin Andrei
http://florin.myip.org/

I have this working happily under Ubuntu 14.04 with my old NEO, but gpg-agent freaks out when I try to grab my SSH key from my new U2F NEO. It's like there are multiple card readers, and it just gives up.

Old NEO:

$ gpg --card-status
gpg: detected reader `Yubico Yubikey NEO OTP+CCID (Љ) 00 00'

New NEO:

$ gpg --card-status
gpg: pcsc_list_readers failed: unknown PC/SC error code (0x8010002e)
gpg: card reader not available
gpg: OpenPGP card not available: general error

I'm sure if I turn off U2F mode things will hum along nicely. These two keys work flawlessly in Windows, by the way. Is there something I should be telling gpg-agent to get it working?

Thanks,

Agg

I'm having issues with this one.

I've got the OpenPGP app on the NEO, and set it in to mode 0x82. I've got a key on the card. I've exported the public key (and private key) and generated an entry for the authorized_keys files.

My SSH client is putty. I have my choice of GPA as a pgp agent with ssh compatibility, or Putty-SC's pagent replacement. Both seem to produce the same result - the key does not appear to work.

using ssh -dd, I get the following output:

debug1: userauth-request for user rik service ssh-connection method publickey [preauth]
debug1: attempt 1 failures 0 [preauth]
debug2: input_userauth_request: try method publickey [preauth]
debug1: test whether pkalg/pkblob are acceptable [preauth]
debug1: trying public key file /home/InquisitiveDonut/.ssh/authorized_keys
debug1: fd 4 clearing O_NONBLOCK
debug2: key not found
debug1: trying public key file /home/InquisitiveDonut/.ssh/authorized_keys2
debug1: Could not open authorized keys '/home/InquisitiveDonut/.ssh/authorized_keys2': No such file or directory
Failed publickey for rik from WWW.XXX.YYY.ZZZ port 51950 ssh2


I do not understand why the key is not found. Anyone experienced and solved this?