YubiKey

Hardware security key operations for authentication, signing, and credential storage.

Device Information

Check connected YubiKey — firmware, serial, interfaces

ykman info

List connected YubiKeys

ykman list

FIDO2 / WebAuthn

List registered FIDO2 credentials

ykman fido credentials list

Set a FIDO2 PIN — required for resident keys

ykman fido access change-pin

Reset FIDO2 application — erases all FIDO2 credentials

ykman fido reset

PIV (Smart Card)

The PIV application stores X.509 certificates and private keys in slots. Used for SSH authentication, code signing, and client certificates.

List certificates stored in PIV slots

ykman piv info

Generate a key pair in slot 9a (authentication)

ykman piv keys generate --algorithm ECCP384 9a pubkey.pem

Generate a self-signed certificate for the slot

ykman piv certificates generate --subject "CN=evan@domusdigitalis.dev" 9a pubkey.pem

Import an existing certificate into a PIV slot

ykman piv certificates import 9a cert.pem

Import a private key into a PIV slot

ykman piv keys import 9a private.key

Export a certificate from a PIV slot

ykman piv certificates export 9a exported-cert.pem

PIV Slots

9a — Authentication (SSH, login)
9c — Digital Signature (code signing, document signing)
9d — Key Management (encryption, decryption)
9e — Card Authentication (physical access, contactless)

OATH (TOTP/HOTP)

The YubiKey stores TOTP secrets on-device. Codes are generated on the hardware, not in software.

List TOTP accounts stored on the YubiKey

ykman oath accounts list

Generate all current TOTP codes

ykman oath accounts code

Generate code for a specific account

ykman oath accounts code GitHub

Add a TOTP secret to the YubiKey

ykman oath accounts add -o TOTP GitHub:evan BASE32SECRET

Add from an otpauth URI

ykman oath accounts uri "otpauth://totp/GitHub:evan?secret=BASE32SECRET&issuer=GitHub"

Delete a TOTP account

ykman oath accounts delete "GitHub:evan"

OpenPGP

Check OpenPGP application status

ykman openpgp info

Move GPG subkeys to YubiKey — makes the YubiKey the only holder of the private key

gpg --edit-key evan@domusdigitalis.dev
# In the gpg prompt:
# key 1        (select subkey)
# keytocard     (move to YubiKey)
# Select slot: (1) Signature, (2) Encryption, (3) Authentication

After moving keys to the YubiKey, the local keyring has stubs. GPG operations require the YubiKey to be inserted.

Check GPG sees the YubiKey

gpg --card-status

SSH Authentication via PIV

Use the YubiKey PIV slot for SSH — via PKCS11

ssh -I /usr/lib/opensc-pkcs11.so user@remote-host

Add to ssh-agent via PKCS11

ssh-add -s /usr/lib/opensc-pkcs11.so

Extract SSH public key from PIV slot

ssh-keygen -D /usr/lib/opensc-pkcs11.so

SSH config for persistent PKCS11 use

Host *.inside.domusdigitalis.dev
    PKCS11Provider /usr/lib/opensc-pkcs11.so

PIN & PUK Management

Change PIV PIN

ykman piv access change-pin

Change PIV PUK — unlocks the PIN after lockout

ykman piv access change-puk

Change management key — protects administrative operations

ykman piv access change-management-key

Touch Policy

Require touch for each PIV operation — prevents silent key use

ykman piv keys generate --touch-policy always --algorithm ECCP384 9a pubkey.pem

Touch policies: default, always, cached (touch once, cache for 15 seconds), never.