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.
- FreeBSD ssh with piv smartcard slot on Yubikey (pkcs11 via
libykcs11.so) - FreeBSD ssh with fido support on Yubikey
- FreeBSD Firefox/Chromium with fido + webauthn support on Yubikey
- FreeBSD local console and gdm authentication using pam on Yubikey
- FreeBSD official YubiKey tools
- FreeBSD 13.2 Testing (Aug 2023)
- FreeBSD stable/13 Testing (Aug 2023) with OpenSSH_9.3p2
- FreeBSD stable/14 Testing (Oct 2023) with OpenSSH_9.5p1, OpenSSL 3.0.11, and libfido2 1.13
| Slot Number | Slot Name | Default Touch policy | Default PIN Policy | Notes |
|---|---|---|---|---|
| 9a | PIV Authentication | never | Cached (once) | System login slot |
| 9c | Digital Signature | never | Required (always) | Document/object signing |
| 9d | Key Management | never | Cached (once) | Encrypting Emails/objects/files |
| 9e | Card Authentication | never | Not Required (never) | Physical Access |
| 82-95 | Retired Key Management | never | key/cert slots in Y4/Y5 only, originally designed to backup old 9d encryption keys for archival | |
| f9 | Attestation | never | Not a standard slot, used for Attestation of other keys only. Requires f/w 4.3+ | |
| 9b | Managment | never | always | Not a standard slot, Used for master management key |
9a,9c,9d,9e,82-95can all be used by OpenSSH pkcs11 support (and most other PIV consumers)- More pin/touch info here: https://docs.yubico.com/yesdk/users-manual/application-piv/pin-touch-policies.html
- More detailed slot info here: https://docs.yubico.com/yesdk/users-manual/application-piv/slots.html
Read the excellent documentation here: https://developers.yubico.com/PIV/Guides/SSH_with_PIV_and_PKCS11.html.
- If you need to do initial configuration or generate piv keys/certs follow these steps (save your PIV pin and puk somewhere safe). If you have already customized pin/puk, you can skip this step. Example below is the default pin/puk after piv applet reset, do not use the defaults for the new values for obvious reasons.
yubico-piv-toolcan be used with an alternate syntax for the same functions, butykmanis the more actively supported/recent admin toolchain. Note: yubico-piv-tool is required to install thelibykcs11.somodule
pkg install -g py3*-yubikey-manager
ykman piv access change-pin --pin 123456
ykman piv access change-puk --puk 12345678
- If you need to configure management key, and some piv-specific objects for better compatability. Use aes256 instead of default tdes for management (if f/w 5.4.0+), and save the management key on the yubikey protected by pin and touch. If you have f/w < 5.4.0, omit
-a aes256, as the only supported management key algorithm was tdes .
ykman piv access change-management-key --generate --protect --touch -a aes256
ykman piv objects generate chuid
ykman piv objects generate ccc
ykman piv info
- If not already done, generate actual private key, and certificate based on resultant public key. Example shows eccp384 algorithm, but rsa2048 can also work (if using older openssh without ecc support). Pin/Touch policy can be customized as desired, but different slots have different default values. Slot numbers are 9a/9c/9d/9e for the primary 4 slots. If you need more, you can also use slots 82-95. https://developers.yubico.com/PIV/Introduction/Certificate_slots.html, and https://docs.yubico.com/software/yubikey/tools/ykman/PIV_Commands.html#ykman-piv-keys-generate-options-slot-public-key Feel free to customize the subject line, and the valid-days as desired. Subject line can be any RFC 4514 string.
ykman piv keys generate -a eccp384 --pin-policy once --touch-policy cached 9a 9a_pub.pem
ykman piv certificates generate --valid-days 730 --subject "Y5C_9A" 9a 9a_pub.pem
- Install the FreeBSD yubikey pkcs11
YKCS11shared library
- using pkg utility, install Yubico utilities and shared library
/usr/local/lib/libykcs11.sofor full functionality (other pkcs11 libs can work as well, but untested for this writeup.) - Don't forget the ccid usb driver package, or pcsc-lite and libykcs11.so will not find your USB keys at all
- Detailed information about
YKCS11here: https://developers.yubico.com/yubico-piv-tool/YKCS11/ - There are cases where other utilities (like
scdaemonfrom gpg) can lock the USB port, try removing/re-inserting the Yubikey ifyubico-piv-tool -a statusdoes not find your device.
pkg install yubico-piv-tool pcsc-lite ccid
- Setup pcscd to startup on boot (changes /etc/rc.conf for you), and manually start now
service pcscd enable
service pcscd start
- Insert (or remove, then insert) Yubikey, and test ability to connect to USB device with yubico_piv tool This command should display your Yubikey version, serial number, configured slots, and pin tries left if successful.
yubico-piv-tool -a status
- Extract public key (ecc or rsa) and save to id_rsa.pub, and copy to destination user@host authorized_keys file. (change
user@hostto a real host you have ssh access to). Note: This command will export all piv keys stored on the YubiKey. The slot order should remain the same, thereby facilitating identification of the public key associated with your targeted private key.
umask 077
ssh-keygen -D /usr/local/lib/libykcs11.so > ~/.ssh/id_pkcs11.pub
ssh-copy-id -i ~/.ssh/id_pkcs11.pub user@host
- Test out connectivity using ssh (change
user@hostto a real host you have ssh access to)
ssh -v -I /usr/local/lib/libykcs11.so user@host
- Configure ssh for current user to automatically load pkcs11 library without long CLI (can also be global if you want via
/etc/ssh/ssh_config)
echo "PKCS11Provider /usr/local/lib/libykcs11.so" >>~/.ssh/config
- (optional) use with ssh-add and/or ssh-agent (will prompt for pin aka passphrase)
ssh-add -s /usr/local/lib/libykcs11.so
- (optional) limit which PKCS11 slot keys are being used (default is all keys until #PKCS11 URI support is added) This requires having a seperate Identity public key file for the specific key you want to allow). This support requires OpenSSH 8.3+ to work properly in all of the cases.
- Create a
~/.ssh/id_pkcs11_slot9a.pubfile with only thePublic key for PIV Authentication(Slot 9A) by editing with vi and removing non-desired keys.
cp ~/.ssh/id_pkcs11.pub ~/.ssh/id_pkcs11_slot9a.pub
vi ~/.ssh/id_pkcs11_slot9a.pub
- Create an
~/.ssh/configfile with theIdentitiesOnly yesstanza (customize as desired) See https://man.openbsd.org/ssh_config for more information on syntax and alternate options.
Host *
IdentitiesOnly yes
IdentityFile ~/.ssh/id_pkcs11_slot9a.pub
PKCS11Provider /usr/local/lib/libykcs11.so
You can also customize per-instantiation with the ssh -i <identity> -o IdentitiesOnly=yes <user@host> syntax as desired
ssh -i ~/.ssh/id_pkcs11_slot9a.pub -o IdentitiesOnly=yes -I /usr/local/lib/libykcs11.so user@host
Starting with OpenSSH 8.2p1+ release, there is native support for FIDO 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 recent BLUE security key variant and recent Yubikey 5 variants)
| FIDO Device | FIDO Device Version | Key Algorithms | [Non-]Resident | Notes |
|---|---|---|---|---|
| Yubikey Neo | f/w 3.4.9 | ecdsa-sk | Non-Resident | YSA-2018-01 in OATH, does not impact FIDO |
| Yubikey Neo | f/w 3.5.0 | ecdsa-sk | Non-Resident | |
| Yubikey 5 | f/w 5.1.1 | ecdsa-sk | Non-Resident | |
| Yubikey 5 | f/w 5.2.3+ | ed25519-sk ecdsa-sk | Both | |
| Yubikey 4 | f/w 4.3.1 | ecdsa-sk | Non-Resident | CVE-2017-15361 in rsa, but does not impact FIDO |
| Yubikey 4 | f/w 4.3.5 | ecdsa-sk | Non-Resident | |
| Yubikey FIDO U2F Security Key (BLUE) | f/w 3.0.0 | ecdsa-sk | Non-Resident | |
| Yubikey FIDO2 Security Key NFC (BLUE) | f/w 5.4.3 | ed25519-sk ecdsa-sk | Both | |
| Yubikey FIDO2 Bio | f/w 5.5.6 | ed25519-sk ecdsa-sk | Both | Requires enrolling Fingerprints with ykman fido fingerprints add ... |
| Solo 2 | f/w 20220822+ | ed25519-sk ecdsa-sk | Both | Update your firmware from solo |
- Check your OpenSSH client version and make sure it is new enough (recommend 8.9+)
ssh -V(If it is older than 8.9+, considerpkg install opensshand execute ssh-keygen from /usr/local/bin/ssh-keygen) - Install libfido2 shared library, u2f-devd rules, and askpass utility (OpenSSH FIDO runtime dependancies):
pkg install -g libfido2 OpenSSH-askpass u2f-devd py3*-fido2
- If you have not already, configure your user for u2f group privs, and your Yubikey token for a pin.
- Add local user to new u2f group to allow access to usb device mappings created by u2f-devd package.
pw group mod u2f -m user(replaceuserwith your actual username) Failure to add your user to the correctu2fgroup will result in that user not being able to access the USB device/YubiKey withfido2-tokenand other fido tools. Reboot or (restart devd and remove/re-insert yubikey and logout/login after permissions change).
service devd restart #Don't forget to remove and re-insert Yubikey after restart
- Auto-detect uhid/hidraw device assigned to attached Yubikey:
If no results are returned from
fido2-token -L, permissions or device mapping devd rules are incorrect. Turn up verbose mode, attempt with root account, etc.
fido2-token -L #Query for uhid/hidraw device. Requires user to have permissions to /dev/uhidXX or /dev/hidrawYY
- Add an initial pin to the FIDO app (You can skip this step if FIDO pin already set) on the Yubikey. (replace
/dev/uhid2with actual device returned fromfido2-token -Lcommand):
fido2-token -S /dev/uhid2
- Display supported protocol versions, extensions, and existing resident keys (replace
/dev/uhid2with actual device returned fromfido2-token -Lcommand):
fido2-token -I /dev/uhid2 #List supported protocols/extensions
fido2-token -L -r /dev/uhid2 #List existing resident keys
- Generate the
ed25519-skORecsda-skkey (resident or non-resident) on the Yubikey. ReplaceFIDO2_Y5Cwith your own friendly name as desired:- Resident ed25519-sk: (This will prompt touch, but not PIN during authentication, PIN only required for generation)
ssh-keygen -t ed25519-sk -O resident -O application=ssh:FIDO2_Y5C- Resident ecdsa-sk: (This will prompt for PIN and touch during generation and authentication)
ssh-keygen -t ecdsa-sk -O resident -O application=ssh:FIDO2_Y5C -O verify-required- Non-Resident ed25519-sk: (This will generate a non-resident/non-discoverable ed25519 key that can not be extracted onto a new machine with ssh-keygen -K) Note: Even with a non-resident key, only the key-handle is stored in the resultant
.ssh/id_ed25519_skfile, and you can not authenticate without the Yubikey/FIDO on-device private key material. Example below also disables the requirement for touch using optional-O no-touch-requiredparameter. See https://man.openbsd.org/ssh-keygen#FIDO_AUTHENTICATOR and https://man.openbsd.org/sshd.8#no-touch-required. Additional Note: no-touch-required also requires an equivalent change to prefix the stringno-touch-requiredto the ssh server users'authorized_keysentry to disable user-presence validation (uv). This can be done before running ssh-copy-id by modifying the resultantid_ed25519_sk.pubfile as shown below with a one-liner sed to prependno-touch requiredto the public key fileid_ed25519_sk.pub.
umask 077 ssh-keygen -t ed25519-sk -O no-touch-required sed -i '' s/^sk-/no-touch-required\ sk-/1 ~/.ssh/id_ed25519_sk.pub ssh-copy-id -i ~/.ssh/id_ed25519_sk <user@host>- Non-Resident ecdsa-sk: (This will generate a non-resident/non-discoverable ecdsa key that can not be extracted onto a new machine with ssh-keygen -K)
umask 077 ssh-keygen -t ecdsa-sk -O no-touch-required sed -i '' s/^sk-/no-touch-required\ sk-/1 ~/.ssh/id_ecdsa_sk.pub ssh-copy-id -i ~/.ssh/id_ecdsa_sk <user@host>
-C "FIDO2_Y5C"(or other string identifier) can be appended to thessh-keygencli arguments as desired to add a comment to give context to the owner/key. This will replace the defaultuser@domainsyntax in the resultant.pubkey files as well. This works with both Resident and Non-Resident key generation since it is just a comment.- 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 handle on a different host when the version is the same or newer (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. I have not seen any issues since upgrading to OpenSSH 9.0+ with recent releases of FreeBSD.
- Copy resultant public key to remote host as desired: (Change
user@hostto applicable remote host)
ssh-copy-id -i ~/.ssh/id_ed25519_sk user@host
- Optional Configuration
- Extract resident key on a new local box for use with FIDO/SSH:
cd ~/.ssh/ && ssh-keygen -K
or cd ~/.ssh/ && /usr/local/bin/ssh-keygen -K (if you are using from ports)
Note: If you enable the kernel driver for the new hidraw device, ssh-keygen may require an optional flag to manually specify the device entry. ssh-keygen -K -v -O device=/dev/hidraw3 is one example of the required syntax. Using the -v verbose flag will give you a better error message like debug1: ssh-sk-helper: sshsk_load_resident failed: device not found when it can not find the device (or lacks permissions) instead of the default Provider "internal" returned failure -4. Try using root, and manually specifying the device reported by fido2-token -L.
- Rename your private and public key files (as desired) to match ssh_config of
id_ed25519_sk[.pub] orid_ecdsa_sk[.pub] as extractingResident keyswith-Kattempts alternate naming by default to avoid collisions. - Control
touch-required,no-touch-required,verify-required,no-verify-requiredon a destination host- Default is
touch-required,no-verify-requiredunless otherwise configured. - Using
no-touch-requiredduringssh-keygenoption does not embed this directive in the resultant .pub file Bug ? which will result in an authentication failure if the public key is copied to a destination ssh host without prefixingno-touch-requiredto theauthorized_keysentry for the applicable key. Fix is to just addno-touch-requiredprefix on the public key file just after generation, but before copying to a destination host. (see above example cat/sed/cp) - OpenSSH supports per-key configuration in
~/.ssh/authorized_keysfiles, and global settings in/etc/ssh/sshd_config - See https://man.openbsd.org/sshd.8#AUTHORIZED_KEYS_FILE_FORMAT and https://man.openbsd.org/sshd_config#PubkeyAuthOptions for details.
- Default is
- Limit which keys are being used for ssh since there is a (default) maxium of 6 authentication attempts. If you have more than 5 keys on your combined list (Yubikey PIV + Yubikey FIDO + id_* keyfiles), you can auth fail before the latest key/password is attempted.
This support requires OpenSSH 8.3+ to work properly in all of the cases. Example below assumes
id_ed25519_skidentity file. Create an~/.ssh/configfile with theIdentitiesOnly yesstanza (customize as desired). - See https://man.openbsd.org/ssh_config#IdentityFile for more information on syntax and alternate options.
Host *
IdentitiesOnly yes
IdentityFile ~/.ssh/id_ed25519_sk
You can also customize per-instantiation with the ssh -i <identity> -o IdentitiesOnly=yes <user@host> syntax as desired. Don't forget about -v to debug what keys are being offered. Also, reminder that -o (lowercase) is used with ssh, and -O (uppercase) is used for options with ssh-keygen.
ssh -v -i ~/.ssh/id_ed_25519_sk -o IdentitiesOnly=yes user@host
- Note: You can install OpenSSH v9.3+ from pkg into the /usr/local/bin path if you are running an older base FreeBSD version and need the updated ssh-keygen to support. The relevant error message when calling ssh-keygen with disparate SSH_SK_VERSION_MAJOR variants is "invalid format" on windows and "unsupported xxxx" on FreeBSD. Note: Reminder to run
/usr/local/bin/ssh-keygenif you install from ports/pkg.
- (debugging) FIDO2 diagnostics using fido2-token
pkg install -g py3*-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) - Known issues/workarounds.
- ssh-sk-helper internal module hangs roughly 50% of the time. This issue was identified, and a kernel bugfix committed to -current, stable/12, and stable/13. You should not experience on 13.2+ See https://bugs.freebsd.org/bugzilla//show_bug.cgi?id=263995
- Usb port contention with gpg's
scdaemon. There is a workaround documented here: https://blog.apdu.fr/posts/2019/06/gnupg-and-pcsc-conflicts , and I use the following in my~/.gnupg/scdaemon.confwith modern gpg2:
pcsc-shared
disable-ccid
- You can debug by running
pcscd -f(foreground) and watching for errors. - Additional known issues around gpg2/pcsc port contention: drduh/YubiKey-Guide#277
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/
- Install libu2f-host, u2f-devd packages and firefox and/or chromium
pkg install libu2f-host u2f-devd firefox chromium - Add local user to new u2f group to allow access to usb device mappings created by u2f-devd package.
pw group mod u2f -m user(replaceuserwith your actual username,)
- Failure to add your user to the correct
u2fgroup will result in that user not being able to access the USB device/YubiKey
- (optional) Restart the devd service if you want to test before rebooting
service devd restart - Confirm Yubikey is detected and applicable permissions granted:
usbconfig show_ifdrvshould 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=ONis displayed for the master device (ugen3.10in this case.) - Make sure that
FIDOis displayed for the uhid device (may require reconfiguring your Yubikey with ykman) - Make sure that the device name (
uhid0in this case) has the correct group permissionsls -alF /dev/uhid0should result in something like:crw-rw-r-- 1 root u2f 0xc1 Aug 28 12:34 uhid0 - If the group
u2fis not setup, verify your u2f-devd rules/package configuration
- Startup X and launch Firefox or Chromium
- Go to a website 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
Overview: PAM (Pluggable Authentication Modules) are supported for various services on FreeBSD and Linux. There is an open source implementation of pam_pkcs11 that provides a glue layer to allow PAM to query a configured pkcs11 library and module to authenticate using a PCS#11 token (like a Yubkikey PIV card slot). I chose a simple demonstration configuration below to allow public keys that are already in place (e.g. openssh ~/.ssh/authorized_keys) to be the authority. This was convienient since I already using PIV keys to authenticate using SSH, now I can use the same public/private keys to control authentication on the local console and Xorg/GDM as well.
- Documentation from OpenSC: https://opensc.github.io/pam_pkcs11/doc/pam_pkcs11.html and https://github.com/OpenSC/pam_pkcs11
- Install supporting pam_pkcs11 and libykcs11.so modules from FreeBSD package manager:
pkg install yubico-piv-tool pam_pkcs11 ccid pcsc-litewill install the desired packages - Verify normal remote ssh works for a local (non-root) user authenticating using piv public/private SSH keys on your Yubikey. If this does not yet work, please follow the receipe above. Keep an active console (or two!) with root access live during testing so you can adjust/revert things without locking yourself out. You have been warned. Take backups/precautions as necessary.
- Configure pam_pkcs11 configuration files.
# Take a look at the example configuration to use different certificate/signature validations
mkdir /usr/local/etc/pam_pkcs11
cp /usr/local/share/doc/pam_pkcs11/pam_pkcs11.conf.example /usr/local/etc/pam_pkcs11/
cd /usr/local/etc/pam_pkcs11/
vi pam_pkcs11.conf
- Minimal
/usr/local/etc/pam_pkcs11/pam_pkcs11.confusing openssh-style authenication (copy/paste contents below should be fine)
pam_pkcs11 {
use_pkcs11_module = ykcs11;
debug = false;
pkcs11_module ykcs11 {
module = /usr/local/lib/libykcs11.so
description = "Yubico Yubikey PKCS#11 so module";
slot_description = "none";
cert_policy = signature;
token_type = "Smart card";
}
use_mappers = openssh;
# Search public keys from $HOME/.ssh/authorized_keys to match users
mapper openssh {
debug = false;
module = /usr/local/lib/pam_pkcs11/openssh_mapper.so;
}
}
- Configure /etc/pam.d/system configuration file. Take a backup first
cp /etc/pam.d/system /etc/pam.d/system.goodPrependauth sufficient /usr/local/lib/security/pam_pkcs11.soto the top of the configuration file - Test to ensure that you can authenticate any/all user(s) with valid authorized_keys file. If things do not work they way you would like, remove the yubikey, and the fallback authentications (password) in the pam system file should take effect. Note: Different keys slots (9a/9c/9d/9e) have different pin-policy and touch-policy defaults and settings. You can adjust as desired with Yubikey Manager, but only at private key generation time, not after a key has already been generated without deleting then re-creating keys. If you want to use slots other than 9a (slot 0 in pam_pkcs11.so parlance), you will have the most luck using the yubico
libykcs11.solibrary. Using other libraries for pkcs11 can work, but YMMV, and extended features can be limited. - (optional) Force smartcard-only authentication by changing
sufficienttorequired, then comment out the#auth required pam_unix.so no_warn try_first_pass nullokline to force smartcard authentication only. You will be unable to login with any account that lacks an appropriate ~/.ssh/authorized_keys file that maps to your local Yubikey authentication. This includes loss of access to the root account. Also recommend having at least two Yubikeys (one on person, one stored in safe) to prevent a lost/damaged key from preventing access. Please be careful, especially if using encrypted root filesystem! - Test using all normal acccess methods to ensure no unexpected behavior(s). If things go horribly wrong, boot into single-user mode and adjust /etc/pam.d/system back to the original state.
- Debugging: You can turn on the debug flags
debug = true;in/usr/local/etc/pam_pkcs11/pam_pkcs11.confto see lots more details on what is going on with both pkcs11 libraries, and with the openssh match backend as desired.
SSH Provides for a variety of supported scenarios for public/private key utilization, but it can be confusing to debug when you are using multiple.
- Background of the certificate/key protocol: https://cvsweb.openbsd.org/src/usr.bin/ssh/PROTOCOL.certkeys?annotate=HEAD
- Background of the FIDO (SK) protocol: https://cvsweb.openbsd.org/cgi-bin/cvsweb/src/usr.bin/ssh/PROTOCOL.u2f?annotate=1.26
- Use
ssh -v(verbose mode) to see details of what keys are being queried and used during connection - Use
ssh-keygen -vto see details of key extraction (PIV/FIDO) or creation (FIDO only) - Use the following command to list all FIDO resident credentials (auto-detect which device)
fido2-token -L -r `fido2-token -L | egrep -o -e '/dev/hidraw[0-9]+' -e '/dev/uhid[0-9]+'`
If you see the error message error in libcrypto next to the Load key line, or if you do not get prompted for a pin...
- Disconnect your yubikey from the device (unplug)
- Run ssh with verbose flag (e.g.
ssh -v user@host) - Check for the "flashing gold disk" on the physical yubikey. The slot may have been configured for presence detection/touch during original key generation.
ssh -v user@host
This will display verbose output indicating what indentity files(e.g. id_rsa, id_ecdsa, id_ed25519,id_ecdsa_sk, id_ed25519_sk), PKCS11 provider, keys, and key hashes will be used during that session. For OpenSSH sshd, the default MaxAuthTries is 6, so be careful of too many keys.
- See https://man.openbsd.org/sshd_config#MaxAuthTries for additional information on
sshdconfiguration If you have too many private keys, the number of authentication attempts may exceed the/etc/sshd_configallowed configuration. This can also be impacted by ssh-agent forwarding from another host. If you use ssh-agent for key storage, you can list the current active keys with
ssh-add -L #List public keys - capital L
ssh-add -l #List hash of public keys - lowercase l
When your Yubikey device does not show up properly in a virtualized OS, check: https://support.yubico.com/hc/en-us/articles/360013647640-Troubleshooting-Device-Passthrough-with-VMware-Workstation-and-VMware-Fusion then add to your ESXi VM advanced configuration (VM must be powered down), or .vmx file in Workstation. You can control the USB attach from the console client (recommend stand-alone VMWare Console 12.0+ for ESXi/VCenter). Do NOT use the Shared Smartcard or Shared Yubico options as they are not supported for these use cases.
usb.generic.allowHID = "TRUE"
usb.generic.allowLastHID = "TRUE"
You can determine what key signature types supported by any version of OpenSSH using:
ssh -Q key-sig
- Example output from FreeBSD 14 (stable/14) as of OpenSSH_9.3p2. Remember that both sides (client/server) must support a key-sig for it to be utilized. All of the sk-ssh*, and sk-ecdsa*, and webauthn-sk* types are "Security Key" or FIDO.
ssh-ed25519
[email protected]
[email protected]
[email protected]
ecdsa-sha2-nistp256
[email protected]
ecdsa-sha2-nistp384
[email protected]
ecdsa-sha2-nistp521
[email protected]
[email protected]
[email protected]
[email protected]
ssh-dss
[email protected]
ssh-rsa
[email protected]
rsa-sha2-256
[email protected]
rsa-sha2-512
[email protected]
- Python 3.9 version as of Aug 2022, 3.11 for newer variants.
pkg install -g py3*-yubikey-manager pcsc-lite ccid - Enable and Startup pcsc daemon
service pcscd enable && service pcscd start - Check status of Yubikey using ykman
ykman infoshould 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 ccidservice pcscd enable && service pcscd start - Use
pcscd --foreground --debugto look at internals of pcsc-lite. Additional reading: https://blog.apdu.fr/posts/2011/07/pcscd-debug-output/ - Check to see if it can find your Yubikey:
yubico-piv-tool -a list-readers - WIP
Enabling usbhid support via hidraw(4) for FreeBSD 13+ can be done by editing /boot/loader.conf. This provides modern hidraw support and legacy compat mode API support as well. Should avoid some of the USB port/device contention issues.
hidraw_load="YES"
hkbd_load="YES"
hw.usb.usbhid.enable="1"
- Requires patches to libfido (included in 14.0-RELEASE, and stable after 9/23/23) - libfido2 1.13 for automatic detection within base libfido using things like OpenSSH from base.
- Manual workaround for older OS code is to pass device entry explicitly
ssh-keygen -v -K -O device=/dev/hidraw1 - This example allows YubiKey Manager to access OTP HID in a non-exclusive way, so that the key will still function as a USB keyboard:
# cat >>/boot/loader.conf<<EOF
hidraw_load="YES"
hkbd_load="YES"
hw.usb.usbhid.enable="1"
hw.usb.quirk.0="0x1050 0x0010 0 0xffff UQ_KBD_IGNORE" # YKS_OTP
hw.usb.quirk.1="0x1050 0x0110 0 0xffff UQ_KBD_IGNORE" # NEO_OTP
hw.usb.quirk.2="0x1050 0x0111 0 0xffff UQ_KBD_IGNORE" # NEO_OTP_CCID
hw.usb.quirk.3="0x1050 0x0114 0 0xffff UQ_KBD_IGNORE" # NEO_OTP_FIDO
hw.usb.quirk.4="0x1050 0x0116 0 0xffff UQ_KBD_IGNORE" # NEO_OTP_FIDO_CCID
hw.usb.quirk.5="0x1050 0x0401 0 0xffff UQ_KBD_IGNORE" # YK4_OTP
hw.usb.quirk.6="0x1050 0x0403 0 0xffff UQ_KBD_IGNORE" # YK4_OTP_FIDO
hw.usb.quirk.7="0x1050 0x0405 0 0xffff UQ_KBD_IGNORE" # YK4_OTP_CCID
hw.usb.quirk.8="0x1050 0x0407 0 0xffff UQ_KBD_IGNORE" # YK4_OTP_FIDO_CCID
hw.usb.quirk.9="0x1050 0x0410 0 0xffff UQ_KBD_IGNORE" # YKP_OTP_FIDO
EOF
# reboot
pkg install -g py3*-fido2
You can choose to use the OpenSC /usr/local/lib/opensc-pkcs11.so PKCS11 shared library instead of the Yubikey variant /usr/local/lib/libykcs11.so for PIV operations.
- Install OpenSC package (as root):
pkg install opensc - Update user SSH config (as user):
echo "PKCS11Provider /usr/local/lib/opensc-pkcs11.so" >>~/.ssh/config
- Extract FIDO SK key using
ssh-keygen -Kdoes not retain originalno-touch-requiredflag https://bugzilla.mindrot.org/show_bug.cgi?id=3355 - OpenSSH does not suport #PKCS11 URI format for selecting specific keys/search criteria https://bugzilla.mindrot.org/show_bug.cgi?id=2817
- OpenSSH does not handle multiple FIDO key matching properly in all cases https://bugzilla.mindrot.org/show_bug.cgi?id=3366
- Enable specific biometric FIDO features https://bugzilla.mindrot.org/show_bug.cgi?id=3218
- Geli with Yubikey in Future ? https://wiki.freebsd.org/DevSummit/201706/GeliImprovements?highlight=%28yubikey%29
Would you be interested in formatting this in AsciiDoc (which is similar to MarkDown), and getting this into the official FreeBSD documentation?