Skip to content

Instantly share code, notes, and snippets.

@LaurentFough
Forked from ixdy/yubikey4-ssh-macos.md
Created April 2, 2022 20:36
Show Gist options
  • Save LaurentFough/ad6bc0dd719f75a9c17a86cb3245c22e to your computer and use it in GitHub Desktop.
Save LaurentFough/ad6bc0dd719f75a9c17a86cb3245c22e to your computer and use it in GitHub Desktop.
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