Skip to content

Instantly share code, notes, and snippets.

@stephen-fox

stephen-fox/yubikey-macos-notes.md

Last active November 22, 2021 20:03
Show Gist options
  • Save stephen-fox/092f0c6f562f7e966a0a21260beed645 to your computer and use it in GitHub Desktop.
Save stephen-fox/092f0c6f562f7e966a0a21260beed645 to your computer and use it in GitHub Desktop.
Download ZIP
macOS yubikey notes (focused on Go development)
Raw
yubikey-macos-notes.md

yubikey w/ ssh on macOS notes

Trade offs

  • FIDO2 (AKA, "security key" / "sk") key:
    • You really need physical presence (need to tap the yubikey - no prompts)
    • Odd workflow even with ssh-agent for Go due to lack of tap prompt
    • Need to update OpenSSH on macOS to at least 8.2 on Big Sur, and servers
    • OpenSSH added FIDO2 support recently (8.2, early 2020 - see ssh -V)
  • PIV (Personal Identity Verification) key:
    • Do not need physical presence (no need to tap the yubikey)
    • Need to enter the yubikey's PIN to use the private key
    • Can change PIN / PUK, which needs to be entered when loading into agent
    • Works out-of-the-box with older OpenSSH on macOS (including ssh-agent)
  • All of these things require installing additional software (someday, FIDO2 support will be relatively ubiquitous as newer versions of OpenSSH proliferate across computers)

FIDO2

  • OpenSSH needs to be >= 8.2 on client and server (PITA on macOS)
  • GitHub supports it
  • go get still requires pressing the yubikey (no text prompt)
  • Still generates private key on disk - somehow additional private key data is stored on the yubikey. Unclear how this works, but it means the SSH server needs to know how to do this
  • Does not require any yubikey software - just OpenSSH (and whatever FIDO2 library it depends on)

PIV

  • Need to install yubico-piv-tool (open source, by yubico). This includes libykcs11.dylib, which is ssh-agent needs to interact with the yubikey
  • Can more or less follow yubico's guide (see below and references)
  • In order to use the builtin ssh-agent, you need to copy libykcs11.dylib into /usr/local/lib because both ssh-agent and ssh-add require libykcs11 to be in an allow-listed directory path (see "man ssh-agent", "-P" argument)
  • The yubikey instructions say to import the certificate with: -a import-certificate, it's not strictly necessary to do so however the read-certificate action will not work without it
  • Retrieve public key in authorized_keys format with: ssh-keygen -D /path/to/libykcs11.dylb -e. It sometimes(?) prints out a helpful comment (the last item in each line). You want the one with the comment: "Public key for PIV Authentication" (the first one in my list)
  • Change PIN and PUK using CLI with -a change-pin and -a change-puk
  • Private key is stored on the yubikey in its entirety

References

- github blog on "security keys": https://github.blog/2021-05-10-security-keys-supported-ssh-git-operations/
- piv: https://developers.yubico.com/PIV/Guides/SSH_with_PIV_and_PKCS11.html
- default pin: https://support.yubico.com/hc/en-us/articles/4402836718866-Understanding-YubiKey-PINs
- ssh-agent allow list: https://somm15.github.io/yubikey/macos/ssh/2018/11/20/welcome-to-jekyll.html
- local ssh-agent: https://gist.github.com/vancluever/de1c3985c8f9e2a3c4bdc42a057e075e
- macOS ssh-agent weirdness: https://www.packetmischief.ca/2016/09/06/ssh-agent-on-os-x/
- GitHub issue w/ misc. info that led me to a few of the above links: https://github.com/Yubico/yubico-piv-tool/issues/158
- PKCS11 provider config: https://github.com/jamesog/yubikey-ssh
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment