Meet Your YubiKey

Before we type a single command, let's understand what a YubiKey actually is and why you'd go through all this setup.

What's a YubiKey, Really?

Physically, it's a little USB dongle with a gold contact pad. But what's inside is more interesting: a secure element — a tiny computer with its own processor, memory, and cryptographic accelerator. It's designed so that the keys stored inside can never be extracted, even by someone with physical access to the device.

Why Bother?

Right now, your PGP private keys are files on your hard drive. If someone steals your laptop, they can copy those files and try to crack your passphrase offline with unlimited attempts.

With a YubiKey:

• Keys never touch your hard drive — they live inside the secure element.
• Physical possession is required — no YubiKey, no crypto.
• 3 wrong PIN attempts = lockout — brute force is defeated by the hardware.
• Optional touch policy — you can require a physical tap before every signature.

What You'll Learn in This Course

Each module builds on the last. By the end, you'll understand the entire chain — from key generation through daily usage and disaster recovery.

Let's See the Real Thing

When you plug in a real YubiKey and check it, this is what you'd see. Go ahead and click the button below.

Knowledge Check

Install the Software Stack

Before we can use a YubiKey for PGP, we need to install the software that talks to it. Think of it as building a communication chain from your computer down to the hardware.

The Communication Chain

If any link in this chain breaks, the YubiKey won't be detected. We'll install all of them now.

Step 1: Install the Packages

Open a terminal and run this command (click it to see what the output looks like):

Step 2: Start the Smartcard Service

Even after installing, the service needs to be running. This is one of the most common gotchas:

Step 3: Verify the YubiKey Is Detected

Plug in your YubiKey (or pretend to) and run:

Knowledge Check

Generate Your PGP Keys

Time to create your cryptographic identity. We'll generate a master key (which stays safely offline) and three subkeys (which will live on the YubiKey).

The Master / Subkey Architecture

Why this complexity? Simple: if a subkey is compromised, you revoke just that subkey and issue a new one — your identity (the master key fingerprint) stays the same. If the master key does the daily work and gets compromised, your entire identity is gone.

Step 1: Generate the Master Key

Here's what you'd answer during the interactive prompts:

Prompt	Your Answer	Why
Key type	(8) RSA (set your own capabilities)	We want a master key that can ONLY certify
Capabilities	Toggle Sign OFF, Encrypt OFF, leave Certify ON	Master key does one job: certify subkeys
Key size	4096	Strongest RSA commonly supported
Expiration	2y	Safety net — can extend later with master key
Name / Email	Your name and email	This is your public identity on the key
Passphrase	Strong passphrase (12+ chars)	Protects your master key backup

Step 2: Add Subkeys

Now we add three subkeys — one for each capability. We do this from inside the GPG key editor.

The three addkey commands you'll run (one at a time):

Step 3: Create a Revocation Certificate

This is your emergency parachute. If your master key is ever compromised, this cert lets you tell the world "this key is no longer mine." Do not skip this.

Knowledge Check

Prepare the YubiKey

Before we load keys onto the YubiKey, we need to configure its PINs and security policies. The YubiKey comes from the factory with default PINs that everyone knows — changing them is step one.

The Three Secrets

Secret	Default	What It Does	Used For
User PIN	123456	Unlocks the card for daily use	Signing, decrypting
PUK	12345678	Unblocks a locked User PIN	Recovery (3 wrong PINs → locked)
Admin PIN	12345678	Unlocks administrative operations	Key import, touch policy, reset

Step 1: Change the PINs

The PIN menu has four options:

#	Action	Do This First
1	Change User PIN	After Admin PIN — sets your daily unlock code
2	Unblock PIN	Only if PIN is locked (needs PUK)
3	Change Admin PIN	Do this FIRST — most sensitive
4	Set Reset Code	Optional backup unlock method

Step 2: Set the Key Size

The YubiKey defaults to RSA 2048-bit keys. To use the 4096-bit keys we generated, we need to tell the YubiKey to expect that size:

You'll be prompted three times — once for each key slot (SIG, DEC, AUT). For each, select:

1. 1 — RSA
2. 1 — 4096

Step 3: Set Touch Policy

This is one of the YubiKey's best features. You can require a physical tap on the YubiKey before it performs any crypto operation. Options:

Policy	Meaning	Best For
Off	No touch needed — PIN only	SSH auth (frequent, background)
On	Tap required for every operation	Signing (maximum security)
Cached	Tap once, app reuses for ~15 seconds	Batch decryption (balance)
Fixed	Like On, but can't be changed without factory reset	High-security / threat model
Cached-Fixed	Tap once, cached ~15s, policy is permanent	Use-once-per-session + permanent

Step 4: Factory Reset (If Needed)

If your YubiKey has been used before — or you got it second-hand — you might want a clean slate. This wipes everything from the OpenPGP applet:

Knowledge Check

Move Keys to the YubiKey

This is the critical step. We transfer the subkeys from your hard drive into the YubiKey's secure element. After this, the private key material exists only on the YubiKey. Your computer keeps "stubs" — pointers that say "this key is on card #XXXX."

Step 1: Check Your Key Structure

You should see one sec (master key) and three ssb entries (subkeys). No > symbols yet — that comes after we move them.

Step 2: Move Each Subkey

Open the key editor and move subkeys one at a time. Each subkey gets its own slot on the YubiKey.

The ritual (repeat for each subkey):

1. key N — selects subkey N (you'll see an asterisk *)
2. keytocard — moves it to the YubiKey
3. Choose the slot (1=SIG, 2=ENC, 3=AUT)
4. Enter your master key passphrase, then the Admin PIN
5. key N — deselects it

Step 3: Verify the Move

Look for the > symbol after each ssb and the card-no: line. That's your confirmation: the private key is on the YubiKey, and your computer only holds stubs.

Step 4: Test Your Setup

Knowledge Check

Using Kleopatra Day-to-Day

Kleopatra is the graphical frontend for GPG. Once your YubiKey is set up, it gives you a visual interface for encryption, signing, and certificate management — all backed by the same keys on your YubiKey.

What Kleopatra Shows You

Launch it from your application menu or run kleopatra in a terminal. You'll see your key listed in the main window:

Encrypting a File

1. Right-click the file → Encrypt with OpenPGP (you need the recipient's public key imported)
2. Select the recipient from the list
3. Check "Encrypt for me too" so you can decrypt it later
4. Click Encrypt — a .gpg file is created

Decrypting a File

1. Right-click a .gpg or .pgp file → Decrypt with OpenPGP
2. The pinentry window asks for your YubiKey PIN
3. If touch is enabled, the YubiKey LED blinks — tap it
4. The decrypted file appears alongside the encrypted one

Signing a File

1. Right-click → Sign with OpenPGP
2. Choose signature type:
   • Detached — separate .sig file (best for software distribution)
   • Clearsign — text stays readable, signature wrapped around it
   • Combined — signature embedded in the file (binary)
3. Enter YubiKey PIN and tap

Verifying a Signature

1. Double-click a .sig or .asc file
2. Kleopatra shows:
   • ✅ Good signature — file is authentic
   • ❌ Bad signature — tampered
   • ⚠️ No known public key — you need the signer's public key

Importing Other People's Keys

To encrypt for someone, you need their public key:

• From a file: File → Import → select .asc
• From a keyserver: File → Lookup on Server → enter email
• Drag-and-drop: Drop the .asc onto Kleopatra's window

Knowledge Check

Unlock KeePass with Your YubiKey

This last piece uses a completely different YubiKey feature — not OpenPGP, but the OTP slot's HMAC-SHA1 challenge-response capability. It's like giving your KeePass database a second lock that only this specific YubiKey has the key to.

How Challenge-Response Works

KeePassXC stores a random challenge in the database header. To unlock, it sends that challenge to the YubiKey, which computes HMAC-SHA1 using the secret stored in slot 2. If the response is correct, the database decrypts. Without the physical YubiKey with that specific secret, the database cannot open.

Step 1: Program YubiKey Slot 2

This stores a random 20-byte secret in the YubiKey's OTP slot 2. The key detail: --generate creates the secret on the device itself — it never travels over USB.

Step 1b: Program Slot 1 as Backup (Optional but Smart)

If you have a second YubiKey or want to use slot 1 for redundancy, program it now. Slot 1 is the short-tap slot — a quick touch triggers it. This gives you two unlock paths on the same YubiKey, keeping one as a fallback.

Step 2: Link KeePassXC to the YubiKey

Assuming you have KeePassXC installed:

Step 3: Add YubiKey to a Database

New database:

1. KeePassXC → Database → New Database
2. Set a strong master password (this is still your primary credential)
3. Under Master Key, check YubiKey Challenge-Response
4. Click Detect — it should find your YubiKey
5. Save the database

Existing database:

1. Open your database (with your current password)
2. Database → Database Settings → Security → Master Key
3. Click Add additional protection → YubiKey Challenge-Response
4. Detect, save, and test by reopening

What Unlocking Looks Like

Here's a simulated KeePassXC unlock dialog. Click through the steps to see how a YubiKey-authenticated unlock works in real time.

The real KeePassXC dialog looks very similar: you enter your master password, it detects the YubiKey automatically, and you touch the gold contact to respond to the challenge. No PINs, no codes — just possession of the physical key.

Backup Strategy: You MUST Plan for Failure

The tradeoff for strong security: if you lose the only YubiKey with the secret, your database is gone forever. You need a plan.

Option 1: Backup YubiKey — Pre-Generate a Known Secret

The safest approach: generate the hex secret yourself before programming either YubiKey, then program both devices with the same key.

2. Program your primary YubiKey (slot 2): ykman otp chalresp 2 <hex>
3. Program slot 1 as a backup on the same device: ykman otp chalresp 1 <hex>
4. Program a second YubiKey with the same hex key: ykman otp chalresp 2 <hex>
5. Store the backup YubiKey somewhere safe (safe deposit box, locked drawer)

Option 2: Emergency Sheet (KeePassXC feature)

KeePassXC can generate a printable PDF with a one-time recovery code that bypasses the YubiKey requirement entirely. Click below to simulate:

Option 3: Print the hex secret for cold storage

Before programming, save the hex output from openssl rand -hex 20 and write it on paper. Store it somewhere fireproof. You can recreate the slot with ykman otp chalresp 2 <hex> on any YubiKey.

Knowledge Check