FIDO2/WebAuthn Security Key Setup Guide
This guide will help you set up FIDO2/WebAuthn security keys (like YubiKeys) on GhostBSD. Security keys provide strong two-factor authentication for websites and services that support WebAuthn.
What You'll Need
- A FIDO2/WebAuthn compatible security key (YubiKey, etc.)
- Administrator (root) access on your GhostBSD system
- A web browser (Firefox or Chromium)
Step 1: Install Required Packages
Open a terminal and install the necessary packages:
sudo pkg install libu2f-host libfido2 u2f-devd
These packages provide:
libu2f-host: Library for communicating with U2F/FIDO deviceslibfido2: Modern FIDO2/WebAuthn library and toolsu2f-devd: Device management for security keys
Step 2: Configure USB HID Support
Load USB HID Module
Add the USB HID module to your system's kernel module list:
sudo sysrc kld_list+="usbhid"
This command safely adds usbhid to the existing kld_list without overwriting other modules.
Disable Legacy USB HID
Disable the legacy USB HID system in favor of the newer one:
sudo sysrc -f /boot/loader.conf hw.usb.usbhid.enable="0"
This disables the legacy USB HID system in favor of the newer one.
Step 3: Set Up User Permissions
Add your user account to the u2f group:
sudo pw group mod u2f -m yourusername
Replace yourusername with your actual username.
Important: You must reboot after making these changes for them to take effect.
Step 4: Reboot Your System
sudo reboot
Step 5: Test Your Security Key
After rebooting, plug in your security key and test it:
Find Your Security Key
fido2-token -L
You should see output like:
/dev/uhid3: vendor=0x1050, product=0x0407 (Yubico YubiKey OTP+FIDO+CCID)
Check Device Information
fido2-token -I /dev/uhid3
Replace /dev/uhid3 with whatever device path was shown in the previous command.
Step 6: Configure Your Browser
Firefox Configuration
- Open Firefox
- Type
about:config in the address bar and press Enter
- Click "Accept the Risk and Continue"
- Search for each setting and change the values:
|Setting|Value|
|---|---|
|security.webauth.u2f|true|
|security.webauth.webauthn|true|
|security.webauth.webauthn_enable_softtoken|true|
|security.webauth.webauthn_enable_usbtoken|true|
- Restart Firefox
Chromium Configuration
Chromium usually works with security keys without additional configuration on GhostBSD.
Step 7: Test WebAuthn
- Go to WebAuthn.io in your browser
- Click "Register" to test registration
- Enter your security key PIN when prompted
- Touch your security key when the browser requests it
- Try "Authenticate" to test login
Troubleshooting
Security Key Not Detected
If fido2-token -L doesn't show your key:
Try unplugging and reinserting the security key.
Check if you're in the correct groups:
groups
You should see u2f and operator in the output.
- Check device permissions:
ls -la /dev/uhid*
Look for a device with group u2f or different permissions.
PIN Locked Error
If you see "security key is locked" or "wrong pin entered too many times":
- Check PIN status:
fido2-token -I /dev/uhid3
Look for pin retries: 0 in the output.
- If PIN retries is 0, you need to reset the FIDO2 application:
fido2-token -R /dev/uhid3
Warning: This deletes all FIDO2 credentials on the key!
When the command runs, immediately touch and hold your security key for 3-5 seconds to confirm the reset.
Set a new PIN:
fido2-token -S /dev/uhid3
Enter your new PIN twice when prompted.
Browser Issues
Firefox doesn't work but Chromium does:
- Double-check the
about:config settings
- Try restarting Firefox completely
- Clear Firefox cache and cookies for the website
- Try in a private/incognito window
Neither browser works:
- Verify your user is in the
u2f group: groups
- Try with a different USB port
Setting Up a PIN (Recommended)
For security, set up a PIN on your security key:
fido2-token -S /dev/uhid3
Choose a PIN that's at least 4 characters long. You'll need to enter this PIN when using the key for authentication.
What's Next?
With your security key working, you can now:
- Enable two-factor authentication on websites that support WebAuthn/FIDO2
- Use SSH authentication with FIDO2 keys
- Set up system login with security keys (advanced)
Common Commands Reference
|Command|Purpose|
|---|---|
|fido2-token -L|List available FIDO2 devices|
|fido2-token -I /dev/uhidX|Show device information|
|fido2-token -S /dev/uhidX|Set initial PIN|
|fido2-token -C /dev/uhidX|Change existing PIN|
|fido2-token -R /dev/uhidX|Reset FIDO2 application (deletes credentials)|
|fido2-cred -L /dev/uhidX|List stored credentials|
Remember to replace /dev/uhidX with your actual device path (usually /dev/uhid3 for security keys).
Security Notes
- Always set a PIN on your security key for additional security
- Keep backup authentication methods enabled on important accounts
- The reset command (
fido2-token -R) permanently deletes all FIDO2 credentials
- Other functions on multi-purpose keys (like YubiKey OTP) are not affected by FIDO2 reset
