How to configure FreeBSD and applicable applications to work with Yubikey for authentication. This serves as my work-in-progress documentation of the configuration knobs needed to make this work properly. All tests were performed with an upto date FreeBSD 13.1 x64 installation as of Aug 2022.

• FreeBSD ssh with piv smartcard slot on Yubikey (pkcs11 via libykcs11.so)
• FreeBSD ssh with fido2 support on Yubikey
• FreeBSD Firefox with fido2 + webauthn support on Yubikey
• FreeBSD local console and sshd authentication using pam on Yubikey
• FreeBSD official YubiKey tools

These functions can co-exist without stomping on each other's usb usage (unlike gpg from my last test)

Example below assumes that you have a piv key already generated in a yubikey slot the way you want. If you need to generate a new one, read the excellent documentation here: https://developers.yubico.com/PIV/Guides/SSH_with_PIV_and_PKCS11.html

1. Install the FreeBSD yubikey pkcs11 driver

• using pkg utility for full functionality (other pkcs11 libs can work as well)
• Don't forget the ccid usb driver package, or pcsc-lite and libykcs11.so will not find your USB keys at all pkg install yubico-piv-tool pcsc-lite ccid
• Setup pcscd to startup on boot (changes /etc/rc.conf for you) service pcscd enable

2. Manually start the daemon if you don't want to reboot service pcscd start
3. Test out connectivity using ssh (change user@host to a real host you have ssh access to) ssh -v -I /usr/local/lib/libykcs11.so user@host
4. Configure ssh for current user to automatically load pkcs11 library without long CLI (can also be global if you want) echo "PKCS11Provider /usr/local/lib/libykcs11.so" >>~/.ssh/config
5. (optional) use with ssh-add and/or ssh-agent (will prompt for pin aka passphrase) ssh-add -s /usr/local/lib/libykcs11.so
6. Export public keys for use with ~/.ssh/authorized_keys files on remote hosts for users ssh-add -L or ssh-keygen -D /usr/local/lib/libykcs11.so

Starting with OpenSSH 8.2p1+ release, there is native support for FIDO2 authenticators (like Yubikey) for authentication using some new key formats. Background information here: https://developers.yubico.com/SSH/Securing_SSH_with_FIDO2.html and https://www.openssh.com/txt/release-8.2. Resident keys are best supported on the latest OpenSSH. All key types should require a PIN to be configured on the token.

• New Terms: Resident credentials are called “discoverable credentials” in CTAP 2.1.
• Yubikey firmware version 5.2.3 or newer is required for ed25519-sk key types (and is supported by both BLUE security key variant and latest Yubikey 5 variant in both USB-A and USB-C variants) If you are using a version less than 5.2.3 and get any key type to work end-to-end, please add a comment to this gist, I may add a "compatibility table" in the future.

1. Check your OpenSSH client version and make sure it is new enough (recommend 8.9+) ssh -V (If it is older than 8.9+, consider pkg install openssh and execute ssh-keygen from /usr/local/bin/ssh-keygen)
2. Install libfido2 shared library and askpass utility (OpenSSH FIDO runtime dependancies): pkg install libfido2 OpenSSH-askpass py39-fido2
3. If you have not already, configure your Yubikey token for a pin. fido2-token -L to attempt autodetection of Yubikey usb hid device name for use in other fido2-token commands.(replace /dev/uhid0 with actual device): fido2-token -S /dev/uhid0
4. Generate the ed25519-sk OR ecsda-sk key (resident or non-resident) on the Yubikey. Replace FIDO2_Y5C with your own friendly name as desired:

• Resident ed25519-sk: ssh-keygen -t ed25519-sk -O resident -O application=ssh:FIDO2_Y5C -O verify-required (This will prompt for PIN and touch)
• Resident ecdsa-sk: ssh-keygen -t ecdsa-sk -O resident -O application=ssh:FIDO2_Y5C -O verify-required (This will prompt for PIN and touch)
• Non-Resident ed25519-sk: ssh-keygen -t ed25519-sk (This will generate a non-resident/non-discoverable key that can not be extracted onto a new machine with ssh-keygen -K)
• Non-Resident ecdsa-sk: ssh-keygen -t ecdsa-sk (This will generate a non-resident/non-discoverable key that can not be extracted onto a new machine with ssh-keygen -K)
• -C "FIDO2_Y5C:$user@$host verify-required" can be appended to the ssh-keygen cli arguments as desired to add a comment to give context to the owner/key and to optionally enforce verify-required when used with ssh-copy-id into remote authorized_keys files.
• Note: This will generate the private key with a specific SSH_SK_VERSION_MAJOR embedded, and you may only be able to extract the private key on a different host when the version is the same (or when OpenSSH SSH_SK_VERSION_MAJOR is stable) Moving the public key around to different versions should not be an issue. YMMV. Windows ssh-keygen 8.9 and FreeBSD ssh-keygen 9.0 seem to be compatible. The purposeful changes to the middleware interface/version happened at OpenSSH version 8.4 and 8.9.

5. Copy resultant public key to remote host as desired: (Change user@host to applicable remote host) ssh-copy-id -i ~/.ssh/id_ed25519_sk user@host
6. (optional) Extract resident key on a new local box for use with FIDO2/SSH: cd ~/.ssh/ && ssh-keygen -K or cd ~/.ssh/ && /usr/local/bin/ssh-keygen -K (if you are using from ports)

• Rename your private and public key files appropriately to match ssh_config of id_ed25519_sk[.pub]
• Note: You can install OpenSSH v9.0 from pkg into the /usr/local/bin path if you need the updated ssh-keygen to support. The relevant error message when calling ssh-keygen with disparate variants is "invalid format" on windows and "unsupported xxxx" on FreeBSD.

7. (debugging) FIDO2 diagnostics using fido2-token pkg install py39-fido2 (To install package) fido2-token -L (To list out current FIDO2 tokens and associated devicenames eg: /dev/uhid0) fido2-token -I /dev/uhid0 (To show current device configuration and capabilities) fido2-token -L -r /dev/uhid0 (To show currently configured resident credentials for FIDO eg: ssh:FIDO2_Y5C)

This assumes that the user already has a working Xorg/gnome/gdm/dbus configuraton on FreeBSD. If you need help with this part, start with the FreeBSD handbook here: https://docs.freebsd.org/en/books/handbook/x11/

1. Install libu2f-host, u2f-dev packages and firefox pkg install libu2f-host u2f-dev firefox
2. Add local user to new u2f group to allow access to usb device mappings created by u2f-dev package. pw group mod u2f -m user (replace user with your actual username,)

• Failure to add your user to the correct u2f group will result in that user not being able to access the USB device/YubiKey

3. (optional) Restart the devd service if you want to test before rebooting service devd restart
4. Confirm Yubikey is detected and applicable permissions granted:

• usbconfig show_ifdrv should result in something like this:

ugen3.10: <Yubico YubiKey OTP+FIDO+CCID> at usbus3, cfg=0 md=HOST spd=FULL (12Mbps) pwr=ON (30mA)
ugen3.10.0: ukbd0: <Yubico YubiKey OTP+FIDO+CCID, class 0/0, rev 2.00/5.27, addr 9>
ugen3.10.1: uhid0: <Yubico YubiKey OTP+FIDO+CCID, class 0/0, rev 2.00/5.27, addr 9>

• Make sure that pwr=ON is displayed for the master device (ugen3.10in this case.)
• Make sure that FIDO is displayed for the uhid device (may require reconfiguring your Yubikey with ykman)
• Make sure that the device name (uhid0 in this case) has the correct group permissions ls -alF /dev/uhid0 should result in something like: crw-rw-r-- 1 root u2f 0xc1 Aug 28 12:34 uhid0
• If the group u2f is not setup, verify your u2f-devd rules/package configuration

5. Startup X and launch Firefox
6. Go to a website using Firefox that has 2FA/Webauthn enabled (like github/gitlab/gmail)

• Firefox will display a little popup notification telling you that your browser is requesting Webauthn access
• Touch the Yubikey gold disk button when it starts blinking

• WIP

• Python 3.9 version as of Aug 2022 pkg install py39-yubikey-manager pcsc-lite ccid
• Enable and Startup pcsc daemon service pcscd enable && service pcscd start
• Check status of Yubikey using ykman ykman info should result in something like this:

Device type: YubiKey 5C NFC
Serial number: XXXXX
Firmware version: 5.2.7
Form factor: Keychain (USB-C)
Enabled USB interfaces: OTP, FIDO, CCID
NFC transport is enabled.
Configured capabilities are protected by a lock code.

Applications	USB          	NFC          
FIDO2       	Enabled      	Enabled      	
OTP         	Enabled      	Enabled      	
FIDO U2F    	Enabled      	Enabled      	
OATH        	Enabled      	Enabled      	
YubiHSM Auth	Not available	Not available	
OpenPGP     	Enabled      	Enabled      	
PIV         	Enabled      	Enabled      

• Requires ccid (bundle files for pcscd) and pcsc-lite packages and pcscd service running
• no need to edit devd rules
• Install packages: pkg install yubico-piv-tool ccid service pcscd enable && service pcscd start
• Use pcscd --foreground --debug to look at internals of pcsc-lite. Additional reading: https://ludovicrousseau.blogspot.com/2011/07/pcscd-debug-output.html
• Check to see if it can find your Yubikey: yubico-piv-tool -a list-readers
• WIP

pkg install py29-fido2