How to use Yubikey with SSH and macOS

yubikey.md

Guide to Setting Up and Using FIDO2 SSH Keys on macOS

About YubiKey and FIDO2

YubiKey is a hardware-authentication device that securely stores your SSH key. You need the physical device to login over SSH, which is protected with both touch (separate button on the device itself) and PIN code (need to be typed to unlock the SSH key).

FIDO2 (Fast Identity Online 2) is a set of standards for secure authentication that aims to replace password-based logins with more secure methods.

1. System Requirements

• macOS: Recent version (Big Sur or later).
• OpenSSH: Version 8.3p1 or higher (FIDO2 support). The recommended version is installed via Homebrew.
• Homebrew: Must be installed on macOS.
• FIDO2 Device: A YubiKey or any compatible FIDO2 device.

FIDO2 was disabled by Apple on the bundled version of OpenSSH in MacOS as of the last update to this page. Thus, OpenSSH variant from Homebrew must be installed.

---

2. Install OpenSSH and libfido2 via Homebrew

1. Update Homebrew:

   brew update

2. Install OpenSSH:

   brew install openssh

3. Install libfido2:

   brew install libfido2

4. Add Homebrew path to the environment, instructions for ZSH:

   echo 'export PATH="/opt/homebrew/opt/openssh/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc

5. Set YubiKey pin

If the PIN is not set before generating the private key, the SSH server may reject the key. Grab your Yubikey device id:

fido2-token -L

ioreg://4295015862: vendor=0x1e0d, product=0xf1d0 (NEOWAVE NEOWAVE Winkeo FIDO2)

Then run -S to set multiple digits pin for your device - longer the better. The YubiKey allows the PIN to be any ASCII character: numbers, letters (upper- and lower-case), and even non-alphanumeric characters such as !, %, or # (among others):

fido2-token -S ioreg://429501586

• More info on FIDO_ERR_PIN_NOT_SET errors
• Setting Yubikey PIN on macOS

---

3. Generate FIDO2 SSH Keys

1. Connect your Yubikey device to your computer.

2. Open Terminal and generate the SSH key:

   ssh-keygen -t ed25519-sk -O resident -O verify-required -C "YubiKey device" -f ~/.ssh/yubikey

   • -t ed25519-sk: Use the ed25519 algorithm with FIDO2 support.
   • -O resident: Store the key on the FIDO2 device.
   • -O verify-required: Require user verification (e.g., touch) for each use of the key.
   • -C "Your Comment": Add a comment to help identify the key.
   • For passphrase you can leave it empty (hit enter twice), as the key will be protected by pin

3. Enter your PIN and touch the device when prompted.

4. Keys will be saved in the ~/.ssh directory.

---

4. Connect to the Server Using the FIDO2 Key

1. Add the public key to server:

   • Open yubikey.pub and copy its content.
   • Log in to the server and edit the ~/.ssh/authorized_keys file.
   • Paste the public key content and save the file.

2. Update ssh config:

   vim ~/.ssh/config

   SSH config sample

   Host server_name
    HostName <IP Address>
    User <User_name>
    IdentityFile  ~/.ssh/yubikey
    ForwardAgent yes
   

3. Connect to server

   # Use -vv for additional debug logs
   ssh -vv server_name
   

4. Enter your PIN and touch the device when prompted.

---

5. Notes

• OpenSSH Version: Ensure you are using the Homebrew-installed OpenSSH version for FIDO2 support:

  which ssh

  The result should be:

  /opt/homebrew/bin/ssh
  

• FIDO2 Device: Ensure your device supports FIDO2 and is properly configured.

• File Permissions: Ensure the ~/.ssh directory and the authorized_keys file on the server have the correct permissions.

---

6. References

• Securing SSH with FIDO2