Skip to content

Instantly share code, notes, and snippets.

@ixdy ixdy/yubikey4-ssh-macos.md
Last active Mar 13, 2019

Embed
What would you like to do?
Setting up ssh public key authentication on macOS using a YubiKey 4

Setting up ssh public key authentication on macOS using a YubiKey 4

I largely followed Florin's blog post, but have a few notes to add regarding issues I encountered:

Basic setup notes

  1. I used a YubiKey 4, while the blog describes using a YubiKey NEO. I'm sure a YubiKey 5 would also work. I'm also running macOS 10.13.6.
  2. I installed GPGTools as recommended. However, as I'll note later, it seems that gpg-agent only automatically starts when gpg is used; for ssh, you'll need to ensure it's running.
  3. Before generating your keys, decide what key size you want to use. If you run the list command inside gpg --edit-card, look for the Key attributes line to see what is currently selected. On my YubiKey 4, it defaulted to 2048 bits for all keys:
Key attributes ...: rsa2048 rsa2048 rsa2048

These correspond to the signature key, encryption key, and authentication key. (I believe only the authentication key is used for ssh.)

Running the key-attr admin subcommand lets you change these:

gpg/card> key-attr
Changing card key attribute for: Signature key
Please select what kind of key you want:
   (1) RSA
   (2) ECC
Your selection? 1
What keysize do you want? (2048) 4096 
Changing card key attribute for: Encryption key
Please select what kind of key you want:
   (1) RSA
   (2) ECC
Your selection? 1
What keysize do you want? (2048) 4096 
Changing card key attribute for: Authentication key
Please select what kind of key you want:
   (1) RSA
   (2) ECC
Your selection? 1
What keysize do you want? (2048) 4096

gpg/card> list
...
Key attributes ...: rsa4096 rsa4096 rsa4096
...

(Note that the OpenPGP applet only works with RSA, not ECC, so don't choose that.)

  1. After generating keys, ssh-add -L may not initially show anything:
$ ssh-add -L
The agent has no identities.

This is because gpg-agent changed how it works a few years ago, removing some options such as write-env-file (per this comment, which Florin's instructions use.

To get gpg-agent and ssh-agent to work together, you can use a simplified /.gnupg/gpg-agent.conf:

pinentry-program /usr/local/MacGPG2/libexec/pinentry-mac.app/Contents/MacOS/pinentry-mac
enable-ssh-support
default-cache-ttl 60
max-cache-ttl 120

and then kill any running gpg-agent process so that it picks up the new configuration.

Since the .gpg-agent-info file is no longer created by gpg-agent, you must also change your .bash_profile to use the GPG agent ssh socket directly. I also added a line here to ensure that the gpg-agent is running:

export GPG_TTY="$(tty)"
export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket)
gpgconf --launch gpg-agent

(This is taken from @drduh's YubiKey guide.)

After updating this, launch a new shell, and ssh-add -L should now show you your public key, and you can follow the rest of the directions provided.

Requiring touch

I wanted to require a touch any time I tried to use my YubiKey for ssh authentication to prevent rogue processes from using the key while it's plugged in.

You can use the YubiKey Manager CLI to require this; I installed it via Homebrew.

After installed, use the ykman openpgp touch subcommand to configure the touch settings:

$ ykman openpgp touch aut on
$ ykman openpgp touch enc on
$ ykman openpgp touch sig on

(Again, you control the three keys separately.)

Problems with certain versions of the YubiKey 4

I attempted to add my SSH public key to my GitHub account and came across this perplexing error:

Key is weak. GitHub recommends using ssh-keygen to generate a RSA key of at least 2048 bits.

I'd initially used a 2048-bit RSA key, so using the key-attr subcommand I described above, I tried generating a 4096-bit key, but GitHub gave the same error message.

After some searching, I came across this issue. Basically, due to a security issue in certain versions of the YubiKey 4 (4.2.6-4.3.4), GitHub rejects keys generated on these YubiKeys as weak. There are basically two workarounds:

  1. Generate a keypair off of the card and then load it onto the YubiKey.
  2. Replace the YubiKey with a newer one. Thankfully, Yubico will replace your affected YubiKey 4 for free.

Even more details

@drduh's YubiKey Guide is a great reference, going into even more detail and best practices.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.