YubiKey

What It Is

A YubiKey is a small USB (or NFC-equipped) hardware security device made by Yubico. It contains a secure element -- a tamper-resistant chip that stores cryptographic keys and performs operations internally. Private keys never leave the device. You plug it in, touch it when prompted, and it proves you're physically present.

YubiKeys are primarily designed for user authentication (logging into websites, SSH, VPNs). FortrOS uses them for two specific machine-related purposes: enrollment credentials and disaster recovery.

How It Works

Multiple Protocols, One Device

A single YubiKey supports several protocols simultaneously:

Protocol	Use Case	Type
FIDO2/WebAuthn	Passwordless web login	Asymmetric (public key)
FIDO U2F	Two-factor web authentication	Asymmetric
PIV (Smart Card)	X.509 certificates, code signing	Asymmetric
OpenPGP	Email encryption, git commit signing	Asymmetric
HMAC-SHA1	Challenge-response (slot-based)	Symmetric
OTP	One-time passwords	Symmetric

HMAC-SHA1 Challenge-Response

The YubiKey has two configurable slots (Slot 1 = short press, Slot 2 = long press). Each slot can be configured for HMAC-SHA1 challenge-response:

The host sends a challenge (up to 64 bytes)
The YubiKey computes HMAC-SHA1(secret, challenge) using a 20-byte secret stored in the slot
The YubiKey returns the 20-byte response

The secret is programmed once during configuration and cannot be read back. Even with physical access to the YubiKey, you can get responses but not the secret itself. This mode is used by KeePassXC for database unlock, by LUKS for disk encryption key derivation, and by FortrOS for enrollment credentials.

Ed25519 Key Storage

YubiKey 5 series (firmware 5.2.3+) supports Ed25519 keys via:

FIDO2 resident credentials (discoverable keys)
OpenPGP applet (signing with Ed25519, encryption with X25519)
PIV applet (firmware 5.7+)

Keys can be generated on-device or imported. Once stored, private keys cannot be exported. Operations (signing, decryption) happen on the YubiKey's secure element.

Touch Policy

YubiKeys can require a physical touch for each cryptographic operation. This prevents malware from silently using the key -- a human must physically touch the device. Touch policies can be set per-key:

Always: Touch required for every operation (default for FIDO2)
Cached: Touch required once, cached for 15 seconds
Never: No touch required (suitable for daemon/automated use)

For machine enrollment, FortrOS uses the HMAC-SHA1 slot which requires physical presence to activate (you touch the YubiKey to generate the response). For disaster recovery, a PIV key with "never" touch policy could allow automated recovery, but this is an org policy decision.

Security Considerations

Physical device = physical security. The YubiKey IS the credential. Losing it means losing access (for anything solely authenticated by that key). FortrOS mitigates this for disaster recovery by supporting multiple admin YubiKeys per org -- losing one doesn't lock out the org.

Not designed for unattended use. YubiKeys are optimized for human interaction (touch to approve). Using them for automated machine processes (daemon signing, continuous auth) requires careful touch policy configuration and isn't their primary design target. For continuous machine identity, a TPM is more appropriate.

Supply chain trust. You trust Yubico to manufacture devices without backdoors. Yubico publishes its supply chain practices and has undergone third-party audits, but the secure element's firmware is proprietary.

How FortrOS Uses It

Enrollment Credential

When a new machine joins the org, an admin physically presents a YubiKey to establish initial trust:

The provisioner sends a challenge to the YubiKey (via the machine being enrolled)
The admin touches the YubiKey
The YubiKey computes HMAC-SHA1(org_secret, challenge) and returns the response
The provisioner verifies the response against its known org_secret
Enrollment proceeds -- the machine gets its TPM-stored credentials

The YubiKey proves: someone with the org's physical enrollment key authorized this machine to join. After enrollment, the YubiKey is removed and the machine authenticates via TPM on all subsequent boots.

Disaster Recovery (Admin YubiKeys)

Admin YubiKeys are enrolled in LUKS as additional keyslots for /persist:

Normal boot: LUKS is unlocked via the org-derived key (from preboot_secret)
Org unreachable: Admin inserts YubiKey, LUKS is unlocked via the YubiKey keyslot
First nodes up with YubiKeys become the org (gossip is peer-to-peer, cached org state on /persist)

Multiple admin YubiKeys can be enrolled (LUKS2 supports up to 32 keyslots). Adding/removing YubiKey keyslots is an org-level operation propagated via gossip.

Alternatives

TPM-only enrollment: Skip the YubiKey, use TPM attestation to prove the machine has genuine hardware. Less human involvement but weaker authorization -- any machine with a genuine TPM could claim to be authorized. FortrOS may add this as an option for large-scale data center provisioning where physical key presentation isn't practical.

Smart Cards and CAC: Smart cards (including military CAC/PIV cards) provide the same cryptographic operations as YubiKeys but in a card form factor with a separate reader. FortrOS supports smart cards as a peer option alongside YubiKeys -- not a fallback, a first-class alternative. Government and military orgs that require CAC + PIN use smart cards instead of (or alongside) YubiKeys. See the Smart Cards and CAC hardware page.

Software tokens (TOTP apps): Generate one-time codes without hardware. No physical presence guarantee -- malware on the admin's phone could extract the TOTP secret. Not suitable for high-trust operations like org enrollment.