YubiKey setup

Put a CA key on a YubiKey for OSH - CA: change the factory PIN, generate the key in slot 9c, and trust it on your servers.

1. Before you start

OSH - CA signs with a key that lives in PIV slot 9c of a YubiKey. A new YubiKey has no key there, so OSH - CA shows SHA256:uninitialized until you create one.

You need a YubiKey 5 series and YubiKey Manager (ykman) on the computer that runs OSH - CA. Quit OSH - CA first: while it runs it holds the YubiKey and ykman cannot open it.

brew install ykman

macOS. On Windows and Linux, install YubiKey Manager from yubico.com.

ykman list --serials

Shows the serial number of every plugged-in YubiKey. With more than one plugged in, add --device <serial> to every command below so you change the right one.

2. Change the default PIN, PUK and management key

A new YubiKey ships with PIN 123456, PUK 12345678 and a well-known management key. Anyone who holds the YubiKey and knows those values can sign certificates for your servers or replace the CA key. Change all three before you use the YubiKey for real.

ykman piv access change-pin

Current PIN: 123456. Choose 6 to 8 characters.

ykman piv access change-puk

Current PUK: 12345678.

ykman piv access change-management-key --generate --protect

Creates a random management key and stores it on the YubiKey behind your PIN, so the PIN is all you need to remember.

Three wrong PINs block the PIN; the PUK unblocks it. Three wrong PUKs block the PIV application, and the only way back is a reset that erases the CA key. Never guess.

Changing these later does not touch the key in slot 9c: the CA key and its fingerprint stay the same.

3. Generate the CA key in slot 9c

Run this once. The key is created inside the YubiKey and never leaves it; the command only writes the public key to ca_pub.pem.

ykman piv keys generate --algorithm eccp256 --pin-policy once --touch-policy never 9c ca_pub.pem

OSH - CA accepts ECC P-256 or Ed25519 keys. Use eccp256 on any YubiKey 5; ed25519 works only from firmware 5.7.

Keep --algorithm: without it ykman creates an RSA key, which OSH - CA does not accept.

--pin-policy once: OSH - CA enters the PIN once after you unlock it and then signs every request. --touch-policy never: signing does not wait for someone to touch the YubiKey.

This replaces any key already in slot 9c. If servers already trust that key, they stop accepting certificates until you trust the new one (step 6).

4. Check the key

ykman piv keys info 9c

Look for algorithm ECCP256 (or ED25519), PIN policy ONCE and touch policy NEVER.

Yubico Authenticator may still say "No certificate loaded" for slot 9c. That is expected: OSH - CA reads the key, not a certificate.

5. Use the YubiKey in OSH - CA

Open OSH - CA, go to Settings → YubiKey, pick the YubiKey by its serial number and press Use this YubiKey, then enter the new PIN. The fingerprint under CA Key changes from SHA256:uninitialized to SHA256:… and the CA connects to the gateway.

6. Trust the CA on your servers step by step

In OSH - CA press Export Public Key and add that line to TrustedUserCAKeys on every server, as described in Trust the CA. Do this again whenever you generate a new CA key.

7. Troubleshooting

SHA256:uninitialized or "No CA key loaded": the YubiKey OSH - CA uses has no ECC P-256 or Ed25519 key in slot 9c. Check it with step 4, generate one with step 3, or pick the other YubiKey in Settings → YubiKey.

"Gateway down" at the same time: the gateway refuses a CA that has no key. Fix the key first; if the gateway still shows as down, check that it is running and reachable.

ykman cannot open the YubiKey: quit OSH - CA and try again.