YubiKey gpg/ssh: Great security but tricky install

After deploying security keys to their 50000 employees, Google took a look at their experience. Their 2 year study concluded that key-touch login was great: scalable, efficient to use, less prone to user error, accessible for impaired users, providing solid security at negligible cost. (See http://fc16.ifca.ai/preproceedings/25_Lang.pdf ).

“If it works for Google” … Just couldn’t wait to try my YubiKeys with gpg/ssh … Turned out to be slick and smooth to use - but with potential to be somewhat technical to install!

To be perfectly honest, the Google study concerned U2F AuthN (“Authentication”). But the results hold for gpg/ssh as well. (And the fact that I was using gpg instead of U2F also explained the challenges I experienced in getting things to work properly.)

As I did the research and testing for this article, I found innumerable blog articles on how to configure YubiKeys for gpg / ssh. People just had to put their experiences in writing. Most probably the authors were proud and happy that things had finally started working!

Lessons learned but no “recipes”

Better people than me have already given detailed, clear explanations of what to do and how to proceed. (Links to these useful references will be included below.)

This article will simply mention some “gotchas” and “lessons learned” along the way to gpg/ssh nirvana.

Begin at the beginning: Determine how / why YubiKeys will be used

Before plunging in installation details, let’s take a step back to ask basic questions:

• Why should I convert to YubiKey-based AuthN anyway?
• How do I intend to use these devices?
• What will be the main AuthN methods?
• Which OS / what host technologies will be involved?
• Where is the balance between security and usability for me?
• Which YubiKeys should I buy?

YubiKey choices

First some comments regarding the YubiKey purchase decision.

How many keys to buy?

The answer is simple: Two.

One backs up the other in case of loss / Murphy / theft / a toddler using the key as a screwdriver.

Which ones?

As mentioned in a previous article: there are 3 YubiKey flavours:

• 
  
• YubiKey Nano: Great for a personal PC / workstation with medium – heavy use (e.g. decrypting passwords, ssh logins, git pushes using ssh). This short key won’t break off as you continually touch the key to authenticate. For reasons to be outlined below, you can generally leave the key in the USB slot and touch away to your heart’s content.
• 
  
• YubiKey 4: Identical to the Nano but with the normal token form factor. Supports touch mode. In comparison to the Neo, the YubiKey 4: a) has stronger crypto (can be used for signing Docker commits), b) stores more TOTP credentials, c) Openpgp card firmware is more recent.
• 
  
• YubiKey Neo: Supports NFC for use with Android mobile phones. This key is part of the same family as the others. But the “Neo” is an older model with weaker crypto, and less room for storing TOTP credentials. The “Neo” only supports 2048-bit keys (compared with 4096-bit keys supported by the other two cards).

Most importantly, the Neo does *not* support touch mode. Once the Neo is plugged into the USB port, it interacts to provide codes.

See https://www.yubico.com/products/yubikey-hardware/ for the details.

Long story short:

Don’t buy the Neo unless a) you are convinced that you will really need Google Authenticator style TOTP codes from your smartphone, and b) you have a recent Android that actually supports NFC.

Applications

Next a word concerning applications in relation to YubiKey use.

Google Authenticator

IMHO Google Authenticator can be uninstalled from your smartphone.

Compared with the average insecure smartphone, TOTP credentials can be stored much more securely on a YubiKey. The little Yubico Authenticator application works well on a PC.

Things to note:

• Base32 please: The YubiKey only accepts a Base32 secret. In practice this is not a big deal since most major sites now give the Base32 code secret directly.

• Save the Base32 code in KeePass for backup: Don’t bother trying to scan the QR Code with the Yubico app. This doesn’t work most of the time. In any case, what you *really* should do is to save the Base32 TOTP key in KeePass or some other secure storage. This will provide a reliable backup: A new key can be programmed with the TOTP code anytime. In a pinch, Google Authenticator could be installed and used.

• Why not directly on the PC?: Instead of generating a TOTP code on a mobile phone and typing it manually it is quicker and better to use the Yubico PC GUI app. Once the YubiKey is inserted (and only then!), the app is enabled to generate TOTP codes.

With the YubiKey 4 touch mode, no code is actually generated until the key is touched. The app displays just the one TOTP code (which is no longer valid 30 seconds later). There is a nifty button to cut & paste the code into the web browser challenge field. No more typing!

Once AuthN is complete, the key can be removed. The empty app can be left open and you move on. If the key is left in the USB slot for some reason, in any case a physical intervention (“touch”) is required before any more codes are generated.

All in all – very nifty!

• All PCs synchronized securely: To use the codes on another PC, simply insert the YubiKey. Since the codes are stored on the key, they are securely transported from PC to PC. The PC’s are always in “sync”.

Linux or Windows?

These days there seems to be increasingly more reason to run linux (at least in a VM) on your workstation:

 <blatant and biased personal opinion>

• The “cloud” is Linux-“friendly” (except for Azure possibly).
• Docker containers, git, ssh / scp, the LAMP stack– even OS-neutral python and the MEAN stack- all have a strong affinity to Linux.
• Surfing the Net with a browser or opening an email on Windows – especially a corporate PC connected to a vulnerable, flat Active Directory – can quickly result in compromise.

</blatant and biased personal opinion>

As I worked through the testing, I found that YubiKeys, Gpg and Linux are made for each other. Windows is like an ugly cousin from the country looking in.

Pass the Unix password manager

All of which brings us to Pass the standard Unix password manager (cf https://www.passwordstore.org/ )

KeePass is a great password manager for personal passwords stored locally. But there is a downside to KeePass:

• Syncing KeePass across several computers can be challenging.
• Hacker tools have targeted KeePass e.g.

http://arstechnica.com/security/2015/11/hacking-tool-swipes-encrypted-credentials-from-password-manager/ 

https://github.com/adaptivethreat/KeeThief 

Pass in comparison mitigates much of this risk:

• Pass runs natively on Linux. (In fact I looked at Windows versions of Pass and moved on: clunky, buggy, and just not worth the extra insecurity)
• Pass is simple, elegant, minimal, and effective. (Think however of “command line” and “monolithic bash script”).
• Synchronization / complete password history is accomplished by using git to store encrypted passwords.
• (Best of all) Each password is encrypted as a distinct gpg2 digital blob. Passwords are decrypted only as they are needed.

When Pass is combined with YubiKey:

• The gpg secret encryption key is tucked away on the YubiKey and cannot be read.
• With touch mode, (a single) decryption will (only) occur if there is a physical touch of the YubiKey.

Very nice.

While testing Pass, I wrote a couple of simple (q&d!) tools:

1. Pass’ vanilla version does not clear the clipboard buffer from a VMWare Linux guest over to a Windows host. (At least not in my tests!)
2. 
   

This can be remedied by using xsel instead of xclip and forcibly clearing the clipboard buffer when a timer pops.

The script can be included in .bashrc

For a detailed explanation of X clipboard support, see https://wiki.ubuntu.com/ClipboardPersistence 

2. 
   
3. A second tool (Python) dumps out all the passwords in Pass’ store for out-of-band backup / secure storage. Note that if touch is enabled, you will have to touch the key for each password that is listed.

Both tools can be found here: https://github.com/lorgor/lgutil.git 

Typical Use case

Let’s illustrate the above with a simple example.

User requirements

• At work, “A” has a Windows workstation running a Linux VM. The workstation is on the corporate AD and is managed by the company Help Desk staff. (All 150 of the Help Desk personnel spread across maybe 5 timezones!)
• The work environment is a mix of Linux / Windows. However “A” is using ssh regularly.
• At home, “A” runs Windows for office work, but Linux for personal development work.
• “A” has used KeePass until now to keep all his passwords but wants a more robust password manager.
• “A” uses git a lot. At work because of the corporate proxy, he has to use https with git. At home, he can use straight ssh-based git access.

Given the above, “A” might want to buy a YubiKey Nano, and a YubiKey 4.

The keys could be used as follows:

YubiKey Nano could be left at work.

The Nano is more convenient to use than the YubiKey 4. As well, the Nano won’t break off in the USB slot with continual, repetitive touches.

• “Touch” mode means that a physical presence at the work PC is required to use the key.
• The card would also be protected with a PIN. After 3 tries (only!!!) the key will lock and can no longer be used.
• The Nano key can also be physically removed when the user is not present for extended periods.

The YubiKey 4 could be used for TOTP codes.

• Inserting the key in the USB activates the YubiKey Authenticator.
• Once a code is accessed, the YubiKey 4 is removed to make the codes disappear from the Authenticator app.
• If “touch” mode is active on the YubiKey 4 as well, then (only) one TOTP code will be generated at a time – and this only after physically touching the key.

The YubiKey Neo is *not* really a good choice for TOTP codes. If the Neo is left in the computer, then YubiKey Authenticator will continuously generate valid TOTP codes for all the TOTP credentials stored on the key. During this time the TOTP codes would be accessible by hostile activity in the PC.

YubiKey 4 for U2F Authentication as well

The same reasoning applies for U2F AuthN. Either the YubiKey 4 or the Nano can be used for U2F AuthN. If Touch mode is enabled, then AuthN will not occur until the key is physically touched.

Both keys could have the same Gpg keys

• The Nano would use the Gpg keys to do the heavy lifting at work: general ssh access, git / Docker signing, git access at work if ssh is used.
• 
  
• The YubiKey 4 could do double duty at home: Gpg keys / Totp codes / U2F AuthN. This avoids transporting the YubiKey Nano. Such a tiny device could easily be lost if it was moved around continually.

There is one “gotcha”. The gpg2 stub pointing to the smart card will point to *one* of the keys only. On Linux at least, if the other YubiKey (containing a copy of the same gpg keys) is inserted, gpg-agent will ask that the “correct” smartcard be inserted. (More on this later.)

Pass to supplement KeePass

• Since “A” runs Linux anyway, moving to Pass for the more sensitive passwords would be relatively easy.
• The resulting increase in security (assuming the VM is properly configured and well-isolated) would likely be significant (compared to running KeePass on a Windows AD-managed box).

No need to bother with Gpg on Windows

• In the above use case, there does not appear to be any real need to bother with the hassle of installing / running Gpg on Windows.

But … the Windows smart card support?

The YubiKey 4 family can also be used as a Windows smart card. This use case was not tested by the author. There will be no mention / discussion of this potentially important use case in this article.

Installation

The previous section discussed basic use of the YubiKeys in real life situations. This section continues with a look at the installation / configuration of the YubiKeys.

The basics

Although tempting, before jumping into installation / configuration, take a step back to look at the big picture.

Which YubiKey modes to use?

Yubico has the policy of keeping more or less full compatibility with older keys. Nothing is obsolete; everything is supported.

This is great for people owning keys. The downside is that the Yubico technology is complex. All the “crud” from the past is carried over.

The previous article in this series discussed YubiKey modes in detail.

For the sample use case discussed above, forget about the legacy “slot” modes. The new YubiKey 4 modes are the only ones needed: gpg smartcard, OATH-TOTP, and FIDO U2F. If there is a choice (obviously) avoid OATH-HOTP in favor of OATH-TOTP.

Yubico also offers simple modules for native OS AuthN (Linux, Windows). However, Duo offers a more functional, integrated solution for this. (cf https://duo.com/ )

Secret credentials cannot be read from the Yubikey

Do not forget that once a credential is written to the YubiKey, the credential can no longer be accessed. The YubiKey will do crypto operations using the credential. But the credential itself cannot be read back.

One implication of this is that to change a TOTP credential, it must be deleted and recreated.

Take backups of credentials– especially the gpg2 keyring – before moving the secret keys to the YubiKey. Obviously the backups should be stored in a safe place.

Three strikes and you are OUT baby!

The YubiKey gpg smartcard gives you three (and only three!) chances to enter the correct PIN. After that you have to reset the card using the Admin PIN. And if you next blow up the Admin PIN with 4 errors, then the card must be factory reset and reinitialized.

Not a lot of room to manoeuver.

In Linux for instance, if the card is removed (say from the Linux VM to use briefly on Windows) and then reinserted, the PIN has to be entered again. If you forget and start touching the card, the card will function as a keyboard to generate random garbage. Do this 3 times without thinking and bang! The PIN needs to be reset.

Ask me how I know … ☹

BTW here are some references that explain how to reset the OpenPGP smartcard applet on the YubiKey. When the procedure is completed, all keys will be deleted and configuration will be restored to default values. But U2F / TOTP credentials on the card will not be affected however.

https://developers.yubico.com/ykneo-openpgp/ResetApplet.html 

https://www.yubico.com/support/knowledge-base/categories/articles/reset-applet-yubikey/ 

And you *will* be configuring new PINs, won’t you????

If no PIN is set for the YubiKey, then anyone who obtains the physical key can use the default Admin PIN to gain full access to the key. Not good.

Use gpg2 not gpg!

The smartcard support is available with gpg2 (and not gpg). Also gpg2 supports 4096-bit key sizes (but gpg doesn’t).

If you even type gpg by error once, then gpg might start generating legacy gpg versions of gnupg keys. This can lead to confusing problems.

Use gpg2, not gpg.

One possibility is to define an alias to cause “gpg” to invoke “gpg2” (eg .bash_aliases).

Decide where the openpgp private key will be generated

The following recommendations are from Yubico (and are followed in most “recipes” I found):

Before you begin, decide if you want to generate the private key on the YubiKey device, or if you want to generate the private key off of the YubiKey and then move the subkeys to the YubiKey. For greater security, we recommend that you store your subkeys on the device (therefore, generate your private key off of the device). We also recommend that you personalize YubiKey by changing the PIN, setting the admin PIN, and so on, before you move the subkeys to the device.

Cf https://www.yubico.com/support/knowledge-base/categories/articles/use-yubikey-openpgp/ 

Some recipes

This section has some “recipes” for configuring YubiKeys for use with Openpgp / ssh.

Good 3rd-party references

Although written for a specific distribution, the archlinux wiki always has great, comprehensive articles. Their gnupg section is probably one of the best overall references available. The troubleshooting section in particular offers invaluable help:

https://wiki.archlinux.org/index.php/GnuPG 

Here is another one of the best overall references:

• http://wiki.bootc.net/en/latest/gnupg.html 
• http://www.bootc.net/archives/2013/06/09/my-perfect-gnupg-ssh-agent-setup/ 

Here are some other good 3rd-party references:

• https://www.jfry.me/articles/2015/gpg-smartcard/#linux
• https://www.sidorenko.io/blog/2014/11/04/yubikey-slash-openpgp-smartcards-for-newbies/ 
• https://spin.atomicobject.com/2014/02/09/gnupg-openpgp-smartcard/
• https://www.narf.ssji.net/~shtrom/wiki/tips/openpgpsmartcard

And more ssh-specific articles:

• https://incenp.org/notes/2014/gnupg-for-ssh-authentication.html
• http://superuser.com/questions/1046556/cant-add-ssh-keys-to-gnupg-agent-anymore 

Here is one of the original recipes that a lot of people refer to (including Yubico). It explains the rationale behind the choices:

• https://www.esev.com/blog/post/2015-01-pgp-ssh-key-on-yubikey-neo/ 

Yubico documentation

Finally some basic Yubico references:

https://developers.yubico.com/PGP/ - section “Configure the PGP features of a YubiKey”

https://developers.yubico.com/PGP/SSH_authentication/ 

https://www.yubico.com/support/knowledge-base/categories/articles/use-yubikey-openpgp/

And a Yubico blog article from 2012 with yet another recipe variation:

https://www.yubico.com/2012/12/yubikey-neo-openpgp/ 

gpg-agent

gpg-agent is vital for correct gpg2 operation in general (and smartcard support in particular).

This section looks at specific gpg-agent considerations.

gpg-agent must be running for proper gpg2 operation

From the gnupg website (https://www.gnupg.org/documentation/manuals/gnupg-devel/Invoking-GPG_002dAGENT.html ):

gpg-agent is a daemon to manage secret (private) keys independently from any protocol. It is used as a backend for gpg and gpgsm as well as for a couple of other utilities.

With gpg2, the secret keys are stored in gpg-agent (and not in the legacy gpg V1 secring.gpg). According to http://superuser.com/questions/1112673/gpg2-no-secret-key, this even applies to legacy gpg V1 secret keys (which are migrated by gpg-agent and tucked away in a file):

In GnuPG 2.1, secret keys are now stored independently – they're maintained by gpg-agent, which keeps them in ~/.gnupg/private-keys-v1.d/.

See the following from the gnupg website for the details: https://www.gnupg.org/faq/whats-new-in-2.1.html#nosecring 

The bottom line:

gpg-agent needs to be running for proper gpg2 operation.

Starting gpg-agent automatically

On recent Ubuntu versions (e.g. 16.04), gpg-agent will start automatically and will use the gpg-agent.conf configuration file. See /etc/X11/Xsession.d/90gpg-agent for the details.

gpg2 will automatically start gpg-agent if it is not running. However, this can be problematic for ssh support. (For the details, see https://www.gnupg.org/faq/whats-new-in-2.1.html#autostart )

gpg-agent configuration

From https://qtpass.org/ , here are some recommendations for  ~/.gnupg/gpg-agent.conf:

enable-ssh-support

write-env-file

use-standard-socket

default-cache-ttl 600

max-cache-ttl 7200

gpg-agent and ssh support

The following reference explains the importance of gpg-agent for ssh support: http://www.bootc.net/archives/2013/06/09/my-perfect-gnupg-ssh-agent-setup/:

“The hard part isn’t getting the agent to talk to the card or anything like that, but using the correct agent when you login to your session. On Linux you’ll generally either get the normal OpenSSH ssh-agent running, or maybe GNOME Keyring’s SSH agent, or some other agent from a variety of other packages; so we’ll need to work out how to disable those agents and use the GnuPG agent instead.”

gpg-agent’s ssh support will be activated if this is specified the gpg-agent’s configuration file (option “enable-ssh-support”).

On some Linux distributions, it might be necessary to set SSH_AUTH_SOCK in .bashrc. The following is from https://qtpass.org/:

# OpenPGP applet support for YubiKey NEO

if [ ! -f /tmp/gpg-agent.env ]; then

  killall gpg-agent;

  eval $(gpg-agent --daemon --enable-ssh-support > /tmp/gpg-agent.env);

fi

. /tmp/gpg-agent.env

Install notes

This section contains various notes on installation. Most of the following assumes that there is little need or desire to get gnupg smartcard support working on Windows.

50000’ view

It is easy to lose sight of the main goals when submerged in the technical details of the various recipes.

Here is a quick summary overview of a recommended approach:

Create the master key + sub-keys:

• Start with an empty gpg2 keyring on a known clean computer.
• Generate a new master key with 3 subkeys (“encrypt-only”, “sign-only”, “authenticate-only”).
• Backup the keyring, master public key, and master revocation certificate.
• Update the public keyservers with the new key / subkeys.

Configure the smartcard(s) and load the keys into the card(s):

• Configure the smartcard user / admin PINs and other data.
• Export the secret keys to the YubiKey.
• Restore the keyring, and rinse / repeat for a second YubiKey.

Configure a (mostly empty) production keyring pointing to the smartcard. Note that the production keyring does *not* have the master key’s secret.

• Create an empty gpg2 keyring for production use.
• Import the master public key.
• Create the secret key stubs using the smartcard that will be used with this keyring.
• Configure trust for the keyring.

Entropy generation

It is possible to short-circuit the gpg2 key generation process by providing low-quality entropy. This is done using rng-tools. See https://www.howtoforge.com/helping-the-random-number-generator-to-gain-enough-entropy-with-rng-tools-debian-lenny 

Especially on a quiet VM, the time savings can be considerable however.

The default PINs

YubiKey has the following default PINS.

The default “User PIN” code on the cards is 123456, and the “Admin PIN” is 12345678.

Cf https://www.yubico.com/2012/12/yubikey-neo-openpgp/ and http://wiki.bootc.net/en/latest/gnupg/generating-keys.html#setting-up-pc-sc-and-testing-your-reader 

Note that the YubiKey 4 (and 4 Nano) have PIN retry counters as follows: “3  0  3”. This is interpreted as follows:

• 3 retries for user PIN
• 0 retries for reset code (ie “disabled”)
• 3 retries for admin PIN.

Cf https://www.yubico.com/support/knowledge-base/categories/articles/reset-applet-yubikey/, https://developers.yubico.com/ykneo-openpgp/PinRetries.html

Configuring trust for the gpg2 keyring

If the above recommended procedure is followed, the trust needs to be configured for the production gpg2 keyring. Set the master key and the signing subkey to ultimate trust.

# configure trust

$ gpg --edit-key <<key id here>>

...

gpg> trust

...

  1 = I don't know or won't say

  2 = I do NOT trust

  3 = I trust marginally

  4 = I trust fully

  5 = I trust ultimately

  m = back to the main menu

Your decision? 5

Test (should ask for pin each time):

gpg2 -e -s -a my_test_file

gpg2 my_test_file.asc

Turn off the gnome-keyring daemon’s ssh support

gnome-keyring’s ssh support can interfere with gpg-agent function.

On Ubuntu 16.04 to turn this off, rename the following configuration file:

/etc/xdg/autostart/gnome-keyring-ssh.desktop

The “-ssh” must not be active.

For more information, see:

• https://wiki.archlinux.org/index.php/GNOME/Keyring 
• https://blog.josefsson.org/2015/01/02/openpgp-smartcards-and-gnome/ 
• http://www.bootc.net/archives/2013/06/09/my-perfect-gnupg-ssh-agent-setup/ 
• 
  

Configure “touch” support for the YubiKey 4

To activate the “touch” function on the YubiKey 4 / 4 Nano, a small Bash script needs to be downloaded and run. See https://developers.yubico.com/PGP/Card_edit.html (section “YubiKey 4 touch”) for the details. The script is here: https://gist.github.com/a-dma/797e4fa2ac4b5c9024cc.

The Bash script works well, and is simple to use:

usage: yubitouch {sig|aut|dec} {off|on|fix} [admin_pin]

Do not configure “touch” mode for authentication (“aut”). Otherwise the gpg key will not be automatically loaded into gpg-agent. This impacts use severely.

Test thoroughly that the smartcard can communicate properly

Before doing anything else, run through the following simple tests to ensure that all the smartcard support pieces are in place and working correctly:

gpg2 [--homedir my_gpgtmp/] --card-status

lgsec1@ubutest:~$ gpg-connect-agent [--homedir my_gpgtmp/] --hex "scd apdu 00 f1 00 00" /bye

D[0000]  04 03 01 90 00                                     .....          

OK

lgsec1@ubutest:~$ pcsc_scan -n

PC/SC device scanner

V 1.4.25 (c) 2001-2011, Ludovic Rousseau <ludovic.rousseau@free.fr>

Compiled with PC/SC lite version: 1.8.14

Using reader plug'n play mechanism

Scanning present readers...

0: Yubico Yubikey 4 OTP+U2F+CCID 00 00

Wed Oct  5 17:20:15 2016

Reader 0: Yubico Yubikey 4 OTP+U2F+CCID 00 00

  Card state: Card inserted,

  ATR: 3B F8 13 00 00 81 31 FE 15 59 75 62 69 6B 65 79 34 D4

Troubleshooting basic smartcard support

Running gpg2 with smartcard / ssh support involves a lot of moving parts.

During testing, most problems, including the infamous “card error” message were resolved by killing all running gpg-agent processes, and restarting a properly configured gpg-agent.

However, the following is a (partial) list of things to check in case of problems:

• gpg2 *must* be used. Always.
• pcscd should be running
• Only 1 copy of gpg-agent should be running. Note: To start gpg-agent manually:

gpg-agent [--homedir my_new_gpgtmp/] –daemon

• libsusb-compat has to be installed for scdaemon to have access to USB smartcard reader. There could be conflicts with OpenSC.
• pcsclite and ccid have to be installed for PSCD-Lite. This is the fallback driver if GngPG’s scdaemon fails to connect to the smartcard directly.
• There can be sudo permission problems with pinentry. The owner of tty must match user for which pinentry is running.
• If the smartcard is not detected, this can be due to permission problems: group scard with a new udev rule.
• When using 2 YubiKeys (eg Nano at work and YubiKey 4 at home / travelling) with pass, can get msg: “gpg: encryption failed: Unusable public key” To correct this, need to edit trust in gpg2 keyring. cf https://lists.gnupg.org/pipermail/gnupg-users/2006-March/028216.html 
• An article from November 2014 mentioned that U2F could cause problems due to a missing USB product ID on Ubuntu 14.04. cf https://lwn.net/Articles/618888/

See the following reference for more troubleshooting information:

cf https://wiki.archlinux.org/index.php/GnuPG  troubleshooting section)

Troubleshooting ssh support

If ssh authentication is not working but basic gpg2 function is, then try looking at the following:

• ssh authentication with smart card support requires gpg-agent
• ssh support must be configured in gpg-agent.conf.
• gpg-agent creates sockets . Be careful that the ssh auth socket is not inherited from parent and that no other processes have ssh-auth socket instead of gpg-agent.
• Check that environment variables are defined and point to gpg-agent: SSH_AUTH_SOCK and GPG_AGENT_INFO
• Is there only 1 gpg-agent running?
• Have you enabled touch on the YubiKey and forgot to touch it after entering the PIN?

VMWare configuration

A tweak is needed for YubiKeys to work in a VMWare environment. The following needs to be added to the appropriate .vmx file:

usb.generic.allowHID = "TRUE"

usb.generic.allowLastHID = "TRUE"

This is to convince VMWare to release the YubiKey USB keyboard from the base OS to the VM. The error message is "The host requires this device for input".

For more information see:

http://forum.yubico.com/viewtopic.php?f=4&t=653 

https://forum.yubico.com/viewtopic.php?f=16&t=629 

Note also that smart card sharing doesn’t seem to work properly. Another suggested changed for .vmx from https://github.com/dainnilsson/scripts/blob/master/base-install/gpg.sh :

usb.ccid.useSharedMode = "FALSE"

Tighten up the gpg options file

The default gpg.conf options should be tightened. After all, why go to the trouble and expense of YubiKeys unless the base gpg configuration is reasonably tight?

Options to look at:

• Specify a default keyserver.
• Remove version information / comments from public keys.
• Move to a relatively short expiration (eg 1 year).
• Set “preferences” and “defaults” to use of robust algorithms for digests / ciphers (e.g. turn off SHA1).

For more information see for instance https://github.com/jclement/dotfiles/blob/master/other/gpg.conf

Exporting the public key in ssh key format

Once gpg-agent’s ssh support is active, it is not immediately obvious how to obtain the ssh public key for authentication. The following simple command will export the corresponding ssh public key:

ssh-add -L

gpg2 also has a command-line option to export a public key in ssh format: “--export-ssh-key”.

Windows install notes

During testing, YubiKeys were configured and tested on Windows Win7 and Win10. (However it turned out that for my production use case, gpg2 never has to run on Windows.)

• To determine where gpg2 thinks its files should be located:

gpg2 –version

To configure gpg: gpgconf.exe.

• Add gpg-agent.exe to Start menu’s Startup directory. As with Linux, gpg-agent (and only 1 copy!) should start with the Windows logon.
• 
  
• Use SysInternalsSuite Task Manager replacement https://technet.microsoft.com/en-us/sysinternals/bb842062.aspx to ensure that only one gpg-agent is running.
• 
  
• As with Linux, if things stop working, kill gpg-agent and restart it.
• 
  
• Don’t forget to enable putty support in the gpg-agent.conf file.
• 
  
• The gpg-agent “putty” support conflicts with Pagent. Both cannot be running at the same time. 
• Legacy ssh keys apparently cannot be loaded into gpg-agent. That is, there is apparently no Windows equivalent for “ssh-add”. Cf https://lists.gnupg.org/pipermail/gnupg-users/2016-May/055932.html 

Here are some general references for WIndows install:

https://developers.yubico.com/PGP/SSH_authentication/Windows.html

https://www.jfry.me/articles/2015/gpg-smartcard/#windows 

See also: https://www.gpg4win.org/ 

Notes on Use

The preceding section discussed installation. This section continues with notes on using the Yubico technology.

The Yubico Authenticator

This small applet is used to generate OATH-TOTP codes. The previous article in this series discussed the Yubico Authenticator program at length.

Some additional things to note follow.

Better on Windows than Linux

Since the program is written in Python, it can be installed on Linux. But the Windows version is cleaner and better to use.

If a Linux install is absolutely necessary, then avoid the “pip” install. There are too many dependencies.

It is much easier to use the Yubico PPA (which seems to be reasonably well maintained).

When tested on Ubuntu:

• The Authenticator generates an Exception when it shuts down. This apparently is “normal”.
• 
  
• Also, to start the application, gpg-agent must be stopped first. Otherwise there will be a message that the Yubikey is allocated to another application.

So a small shell script is needed:

killall gpg-agent

yubioath gui

gpg-agent will restart automatically on 1st use.

The TOTP secret must be entered in Base32 format

Mention was made of saving the TOTP secrets in a separate credential storage such as Keepass or pass. This simplifies recovery.

Conversion from the format supplied by the web site to the Base32 format used by YubiKey can be somewhat tricky.

The previous article in this series mentioned that lowercase “Google-style” TOTP credentials can be converted with the following python code (cf http://stackoverflow.com/questions/34001567/google-authenticator-code-does-not-match-server-generated-code )

import base64

# Secret is lowercase with embedded blanks”

mystr = s.replace(" ","").upper()

base64.b32encode(mystr)

However recently Google (and a number of other websites) have switched to presenting base32-encoded credentials directly. The following was tested with Google account on 2016-12-29. The value of “mystr” shown worked correctly:

>>> import base64

>>> s = "ak7s ybup ck2x ocvp uq7f ixrx 5c3e z5ay"

>>> mystr = s.replace(" ","").upper()

>>> mystr

'AK7SYBUPCK2XOCVPUQ7FIXRX5C3EZ5AY'

When entering the credential in the Yubico Authenticator, use the default settings (i.e. Time-based, SHA1, 6 digits). For extra security specify “Require touch”.

For the rare cases where the secret is presented in hex format, the following could be useful:

import base64

my_bytes = bytearray.fromhex("8ec3521adf9393f09c6842ae0094e21"

base64.b32encode(my_bytes)

Result is:

'R3BVEGW7SOJ7BHDIIKXABFHCC4======'

To change a credential, it must be deleted

Remember that the YubiKey is write-only. Once the credential is stored, it cannot be changed or read. To change a credential, it must be deleted.

To delete a credential in the Yubico Authenticator, right-click the credential to delete.

Cut & paste a credential

When the Authenticator’s “clipboard” icon is clicked, the corresponding TOTP code is copied. You need to look closely to see any visual indication that this has in fact occurred. Generally, I take this “on faith” and move on.

gpg2 / YubiKey use notes

This section discusses issues arising when using gpg2 with YubiKeys.

Touch in time

When “touch” has been enabled, remember to touch the Yubikey after entering PIN.

In general, the YubiKey must be touched while the LED is still flashing. Otherwise the YubiKey will not perform the requested crypto operation.

Changing smart cards

Suppose that two YubiKeys are configured with the same set of gpg2 public / private keys. This could be because one key is used for work, and the other one at home.

Issues can arise with this configuration since a gpg2 keyring only associates one smartcard with a given set of public / private keys.

The following reference explains this in more detail (cf Quick GPG Smartcard Guide ):

When you use either keytocard command or perform key generation on the card, GnuPG places a "stub" in your keyring so that it knows the actual secret key material is located on the smartcard. It looks like you have the secret key on your computer but you actually don't, and you can't decrypt anything without the card. It's just a stub pointing to the smartcard …

So what if you deleted the secret keys anyway and lost the stubs? Just run $ gpg --card-status … in order to instantly re-associate and populate your keyring with the information from your smartcard. However, always keep in mind that you need the corresponding public key in your keyring to work with the smartcard on whatever computer you're using.

After you purposely delete the secret key stubs from your keyring (otherwise it will say the keys are already associated with another card), you can even put these same keys on a different smartcard … .

… Without all of the correct stubs, GnuPG won't prompt you to insert your other smartcard with a different serial number when you try to certify another key or alter attributes.

This article also has a good explanation: https://donncha.is/2014/07/problems-using-an-openpgp-smartcard-for-ssh-with-gpg-agent/ 

Long story short:

• The keyring has a stub for each key stored on a smartcard. The stub points to a specific smartcard (by serial #). Only that specific smartcard can be used for those keys.
• To change to another smartcard (with the same private keys), first the stubs must be deleted, and then the keys imported again (“gpg2 --card-status”). This creates new stubs pointing to the new YubiKey.

Archlinux tips

The following recommendations are from Archlinux cf https://wiki.archlinux.org/index.php/GnuPG.

Some of the following have already been mentioned:

• extend key life instead of revoking. only revoke if key compromised, lost, or passphrase forgotten.
• remove mstr subkey + other subkeys not needed. (cf special “!” to do this) Change subkey pwd. Then can export to less secure boxes.
• Can cache passphrase for whole session (cf article)
• pinentry reqd so cannot pipe in passphrase from STDIN. Need to enable “loopback” pinentry mode.
• Hide recipient IDS by throw-keyids to your configuration file.
• Always show long ID’s and fingerprints: To always show long key ID's add keyid-format 0xlong to your configuration file. To always show full fingerprints of keys, add with-fingerprint to your configuration file.

Conflict between openpgp and PIV

An article from 2015 mentioned the possibility of conflict between openpgp and PIV:

If you happen to use YubiKey NEO with OpenPGP using gpg-agent/scdaemon, you may get the following error message:

no slots

cannot read public key from pkcs11

The reason is that scdaemon exclusively locks the smartcard, so no other application can access it. You need to kill scdaemon, which can be done as follows:

gpg-connect-agent SCD KILLSCD SCD BYE /bye

cf https://blog.josefsson.org/2015/06/16/ssh-host-certificates-with-yubikey-neo/

Pass password manager and git

Note that Pass stores credentials as small gpg-encrypted digital blobs.

Pass has built-in support for git as the synchronization tool of choice.

Note however that git performance can suffer if binary files (in large quantities, or large in size) are stored in git.

https://robinwinslow.uk/2013/06/11/dont-ever-commit-binary-files-to-git/

http://blog.deveo.com/storing-large-binary-files-in-git-repositories/ 

Git signing

This section has a brief discussion concerning use of gpg2 for Git Signing.

Why sign git commits / tags?

Signing git commits / tags makes sense from a security perspective:

https://mikegerwitz.com/papers/git-horror-story 

http://w3guy.com/sign-git-commits-tags-gpg-github-verified/ 

Basic configuration

git signing was tested with GitHub. The following relies on https://help.github.com/articles/signing-commits-using-gpg/ 

To set all commits for a repository to be signed by default, in Git versions 2.0.0 and above:

git config commit.gpgsign true.

To set all commits in any local repository on your computer to be signed by default:

git config --global commit.gpgsign true

However, at time of writing, push signing is apparently not supported by GitHub. (2017-1-02)

http://stackoverflow.com/questions/27299355/why-does-git-need-signed-pushes 

So set:

git config --global push.gpgsign false

One needs to tell git which key to use. This should be the “signing” subkey.

https://help.github.com/articles/telling-git-about-your-gpg-key/ 

git config --global user.signingkey 3AA5C34371567BD2

And where gpg2 lives:

git config --global gpg.program /usr/bin/gpg2

To verify commit signing:

git log --show-signature

tags signing:

git tag -v v1.4.2.1

For more information:

https://www.yubico.com/why-yubico/for-individuals/how-to-sign-code-with-your-yubikey-neo/ 

https://developers.yubico.com/PGP/Git_signing.html 

https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work 

https://git-scm.com/docs/git-config 

Recommendations and Gotchas

• Using gpg2 –card-edit to turn off “forcesig” results in a more convivial experience:

“You can also toggle the forcesig flag to control whether you'd like to require a PIN to be entered every time you sign a message.”

• To provide full protection, everyone must sign all commits:

https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work#Everyone-Must-Sign 

• Verify that the git server being used will actually support gpg-signed commits / tags / pushes.

YubiKey documentation

To save you time poking around their website, here are some of the main YubiKey references:

• The full set of documentation: https://www.yubico.com/support/documentation/ 
• 
  
• The main basic manual:

https://www.yubico.com/wp-content/uploads/2015/03/YubiKeyManual_v3.4.pdf 

• The YubiKey Neo / Nano Manager User Guide: https://www.yubico.com/wp-content/uploads/2014/11/NEO-Manager-Quick-Start-Guide.pdf 

• Documentation for developers (with useful technical insights): https://developers.yubico.com/ 
• 
  
• The YubiKey Neo / Nano product sheet: https://www.yubico.com/wp-content/uploads/2016/02/Yubico_YubiKey4YubiKey4Nano_ProductSheet.pdf 

Here is the OpenPGP smartcard specification:

http://g10code.com/docs/openpgp-card-2.0.pdf 

Here are some references about U2F – the great protocol from Google that nobody wanted to use:

• Overview article: https://www.yubico.com/about/background/fido/ 
• 
  
• Documentation for developers: https://developers.yubico.com/U2F/Protocol_details/Overview.html 
• 
  
• An analysis of security robustness:

https://www.sstic.org/media/SSTIC2016/SSTIC-actes/a_first_glance_at_the_u2f_protocol/SSTIC2016-Article-a_first_glance_at_the_u2f_protocol-maury_bergem.pdf