yubikey-keepassxc-setup.md

yubikey-keepassxc-setup.md

YubiKey Challenge-Response Setup for KeePassXC

Prerequisites

• YubiKey 5 series (e.g., YubiKey 5C NFC)
• ykman (YubiKey Manager CLI) installed
• KeePassXC installed
• Existing KeePassXC database

Step 1: Generate Secret

openssl rand -hex 20

Copy the 40-character hex output. Save it temporarily somewhere secure.

Step 2: Program First YubiKey

# Check current slot status
ykman otp info

# Delete slot 2 if already configured
ykman otp delete 2

# Program slot 2 with your secret (requires touch)
ykman otp chalresp --touch 2 <your-40-char-hex-secret>

# Verify slot is configured
ykman otp info

Step 3: Test First YubiKey

# Challenge must be hex-encoded ("test" = 74657374)
ykman otp calculate 2 74657374

Touch the YubiKey when it blinks. Should return a 40-char hex response.

Step 4: Program Additional YubiKeys

Repeat for each backup YubiKey:

# Unplug current YubiKey, plug in the next one
ykman otp delete 2
ykman otp chalresp --touch 2 <same-secret-as-step-2>

# Verify
ykman otp calculate 2 74657374

All YubiKeys should return the same response to the same challenge.

Step 5: Configure KeePassXC

1. Open your database
2. Go to Database → Database Security
3. Click Add Additional Protection...
4. Select Add Challenge-Response
5. Select your YubiKey and Slot 2
6. Click OK
7. Save the database (Ctrl+S)

Step 6: Test Unlock

1. Lock database (Ctrl+L)
2. Unlock with passphrase
3. Touch YubiKey when prompted
4. Repeat test with each backup YubiKey

Step 7: Secure the Secret

# Encrypt the secret with GPG
echo "<your-secret>" | gpg -e -r your@email.com > yubikey-hmac-secret.gpg

# Or store it offline (print, safety deposit box, etc.)

Delete any plaintext copies of the secret.

Mobile App Setup

Platform	App	Connection
Android	Keepass2Android	USB-C or NFC
iPad	Strongbox or KeePassium	USB-C only

Troubleshooting

"Failed to connect to YubiKey"

# Kill gpg-agent (often holds exclusive lock)
gpgconf --kill gpg-agent

# Ensure pcscd is running
sudo systemctl start pcscd

Verify YubiKey serial

ykman list --serials
ykman --device <SERIAL> otp info

Notes

• Slot 1 is often used for Yubico OTP (web auth) - don't overwrite
• GPG keys use a separate applet and are unaffected
• --touch requires physical touch for each unlock (recommended)
• Without the secret backed up, a lost YubiKey = lost database access