YubiKey Integration: Hardware-Bound Encryption

Status: planned. QNSQY does not use a YubiKey or other FIDO2 key to encrypt data yet. This post explains the planned design, and what to do today.

The Problem with Passwords

Passwords are the oldest form of digital authentication. They are also the weakest. Verizon's Data Breach Investigations Reports have repeatedly found stolen, weak, or reused credentials behind the majority of hacking-related breaches (the 2017 DBIR put it above 80%; the 2024 edition attributes 68% of breaches to the human element). Passwords fail because they are "something you know," and things you know can be extracted from you in many ways:

• Phishing: An attacker sends you a fake login page. You type your password, and they capture it. It is one of the most common ways accounts are compromised.
• Keyloggers: Malware running on your computer records every keystroke. When you type your encryption password, the keylogger captures it and sends it to the attacker.
• Shoulder surfing: Someone watches you type your password. In an office, a coffee shop, or on a plane, this is easier than most people realize.
• Database breaches: You reuse the same password across services (most people do). One of those services gets hacked, and the attacker now has your password for everything.
• Social engineering: An attacker calls you pretending to be IT support and asks for your password. It works more often than you would think.
• Brute force: If your password is short or common, an attacker can simply try every possibility. Modern GPUs can test billions of guesses per second against fast hashes such as MD5.

When it comes to data encryption, the consequences of a stolen password are total. If someone gets your QNSQY password, they can decrypt every file you encrypted with that password, from anywhere in the world, at any time. They do not need access to your computer. They just need the encrypted file (which might be sitting on a cloud backup, a USB drive, or a shared server) and your password.

QNSQY's Argon2id password hashing makes brute-force attacks extremely difficult (each guess requires 128-512 MB of RAM and significant CPU time), but it cannot protect against a password that was phished, keylogged, or socially engineered. Once the attacker has the actual password, Argon2id does not help.

This is where hardware security keys change the equation.

What Is a Hardware Security Key?

A hardware security key is a small physical device, usually the size of a USB thumb drive, that contains a cryptographic chip. The most well-known brand is YubiKey, made by Yubico, but many manufacturers produce compatible devices.

The key stores a secret (a private cryptographic key) inside a tamper-resistant chip. This secret never leaves the device. When an application needs to verify your identity, it sends a challenge to the key, and the key uses its internal secret to compute a response. The application can verify the response is correct without ever seeing the secret itself.

Think of it like a sealed envelope. You can ask someone to write a message, seal it in the envelope, and hand it to you. You can verify the message is correct by checking through a special window. But you can never open the envelope and see the pen inside. The pen (the private key) never leaves its sealed container (the hardware chip).

This is fundamentally different from a password:

• A password is "something you know" and can be copied, shared, intercepted, or guessed. Once an attacker knows it, they have it forever.
• A hardware key is "something you have" and is built so its secrets cannot be copied: the private key is generated inside a tamper-resistant chip and is designed never to leave it, even when someone else holds the device. To use it, you must physically possess the key and physically touch it.

What Is FIDO2?

FIDO2 is an open authentication standard developed by the FIDO Alliance, a consortium that includes Google, Microsoft, Apple, Yubico, and dozens of other companies. It was designed from the ground up to be phishing-resistant.

FIDO2 consists of two components:

• WebAuthn (Web Authentication API): The browser/application-side protocol, standardized as a W3C Recommendation.
• CTAP2 (Client to Authenticator Protocol): The protocol between your computer and the physical key, standardized by the FIDO Alliance.

When you register a FIDO2 key with an application, the key generates a unique public/private key pair for that specific application. The private key stays on the device. The public key is given to the application. During authentication, the application sends a random challenge, the key signs it with the private key, and the application verifies the signature with the public key.

Why is this phishing-resistant? Because the key pair is bound to the specific application's identity (its origin). If a phishing site pretends to be your bank, the key will not respond because the phishing site has a different origin than the real bank. The key simply refuses to authenticate. This happens at the hardware level; you do not need to spot the fake URL yourself.

NIST SP 800-63B-4 (Digital Identity Guidelines) sets three authentication assurance levels. The highest, AAL3, requires a cryptographic authenticator with a non-exportable private key that provides phishing resistance, which is what FIDO2 security keys are built to provide.

How QNSQY Will Use Hardware Keys (Planned)

Planned, not in QNSQY yet. Once built, hardware key authentication (planned for the Business plan) will change the encryption workflow from single-factor to two-factor:

1. Registration (one-time setup): You plug in your YubiKey and register it with QNSQY. This generates a unique FIDO2 credential on the key, tied to QNSQY's application identity. You touch the key to confirm. QNSQY stores the public key portion; the private key stays on the YubiKey.
2. Encryption: When you encrypt a file, QNSQY sends a cryptographic challenge to your YubiKey. You touch the key to authorize the response. The key's response is combined with your password through HKDF (HMAC-based Key Derivation Function) to produce the final encryption key. This means the encryption key depends on both your password AND the YubiKey's secret. Neither alone produces the correct key.
3. Decryption: To decrypt, you need your password AND your YubiKey must be physically present and touched. QNSQY sends the same challenge, the key produces the same response (it is deterministic), and combined with the correct password, it regenerates the decryption key.

The critical security property: even if an attacker has your password, they cannot decrypt your files without physical possession of your specific YubiKey. And even if someone steals your YubiKey, they cannot decrypt your files without also knowing your password. Both factors must be present simultaneously.

Current Status and Setup

Native FIDO2 support as an encryption factor is planned, not available yet. QNSQY cannot use a key kept on a YubiKey's PIV applet today: PIV holds RSA and elliptic-curve keys, while QNSQY's ML-KEM private keys are files that QNSQY reads from disk.

What to Do Today

# Generate an encryption keypair; give the private key a strong passphrase when asked
qnsqy keygen-enc -o mykey -n "My Key"

# Encrypt to the public key
qnsqy encrypt -i secret.txt --recipient mykey.pub

# Decrypt with the private key file (it asks for the key's passphrase)
qnsqy decrypt -i secret.txt.qs --key mykey

Keep the private key file on encrypted storage, with a backup in a separate place. A YubiKey can still protect what surrounds QNSQY, such as your computer login and your password manager.

GUI Approach (planned feature, not shipping today)

1. Go to Settings, then Security, then YubiKey
2. Insert your YubiKey and click "Register"
3. Touch the key when the YubiKey blinks (this confirms physical presence)
4. Enable "Require YubiKey for encryption"

Once registered, any encryption or decryption operation in the GUI will prompt you to touch your YubiKey before proceeding.

Which Keys Could Work

This feature is planned and its design is not final, so no key is supported yet. To protect a file, a hardware key must supply part of the secret that unlocks it. A key that is only asked for a touch is not enough, because someone with the file and the password could use other software that skips the touch.

Keys can supply such a secret through FIDO2's hmac-secret extension (CTAP 2) or YubiKey's HMAC-SHA1 challenge-response; a key with neither could not protect files this way. We will publish the list of supported keys when the feature ships.

Many keys also support a PIN, which adds a layer of its own: someone who steals the key cannot use it without also knowing the PIN.

What Happens If You Lose Your Key

This is the most important section of this article. Read it carefully.

In the planned design, if you lose your YubiKey and have no backup, files encrypted with that key are permanently inaccessible. There would be no recovery mechanism, no master key, no backdoor and no customer support override: the secret inside the key is gone, and without it the file key cannot be rebuilt. That is the point of a hardware factor, and the reason to plan for loss before you rely on one.

To protect yourself against key loss:

• Always register a backup key. The plan is to let you register more than one key. Buy two keys of the same model and register both. Store the backup in a physically separate, secure location.
• Use a safety deposit box for the backup key. A fireproof home safe is also acceptable. The backup should survive the same scenarios that might destroy your primary key (house fire, theft, flood).
• Use M-of-N threshold encryption (Business tier). Split the decryption capability among multiple people. For example, 3-of-5 threshold encryption means any three of five designated people can cooperate to decrypt, so losing one or two keys does not cause data loss.
• Keep a record of which files were encrypted with which key. If you have some files encrypted with password-only and others with YubiKey-bound encryption, knowing which is which prevents confusion during a recovery scenario.

The rule of thumb: treat your backup YubiKey with the same seriousness as a backup of your hard drive. If you would not be comfortable losing all your encrypted data, you need a backup key.

How the Cryptography Works (Simplified)

In the planned design, when QNSQY uses a YubiKey for encryption, the final encryption key is derived from two independent sources combined through HKDF-SHA3-256:

1. Your password, processed through Argon2id to produce a password-derived key. This is the same process used in password-only encryption.
2. The YubiKey's HMAC-SHA1 challenge-response. QNSQY sends a random challenge to the key's HMAC-SHA1 slot. The key computes HMAC-SHA1 of the challenge using its internal secret. The result is a 20-byte value that depends on the key's secret, which never leaves the hardware.

These two values are combined through HKDF (HMAC-based Key Derivation Function, specified in RFC 5869) to produce the final AES-256-GCM encryption key. The math ensures that knowing only one of the two inputs reveals nothing about the final key. You need both.

The HMAC-SHA1 approach works completely offline. There is no server communication, no certificate authority, and no internet connection required. The challenge-response happens directly between your computer and the YubiKey over USB. This makes it compatible with air-gapped workflows.

The challenge-response is also deterministic: the same challenge always produces the same response from the same key. This is essential for encryption, because you need to regenerate the exact same key during decryption. FIDO2's standard authentication flow uses nonces that change every time (good for login, bad for encryption), which is why the current draft uses the HMAC-SHA1 slot for the key derivation. FIDO2's hmac-secret extension, which also returns the same secret for the same input, is the option for keys without that slot.

Password-Only vs. YubiKey: A Comparison

Here is a concrete comparison of what an attacker needs under each mode:

Attack Scenario	Password-Only	Password + YubiKey
Attacker knows your password	Can decrypt	Cannot decrypt (no key)
Attacker steals your YubiKey	Not applicable	Cannot decrypt (no password)
Attacker has both password and key	Can decrypt	Can decrypt
Attacker brute-forces your password	Theoretically possible (Argon2id makes it very hard)	Impossible (even correct password is insufficient)
Database breach leaks your password	At risk	Safe (key is not in any database)
Phishing captures your password	At risk	Safe (the key's secret is still needed)

The YubiKey does not make weak passwords acceptable. It adds a second layer so that even if the password layer fails completely, the data remains protected. Use a strong password AND a hardware key for the best security.

Who Should Use Hardware Keys

Hardware key authentication is most valuable for:

• Organizations handling regulated data: HIPAA (healthcare), PCI DSS (payment cards), GDPR (EU personal data), and CMMC (defense contractors) all recommend or require multi-factor authentication for access to sensitive data.
• Executives and high-value targets: C-suite executives, board members, and other high-profile individuals are disproportionately targeted by spear-phishing. A hardware key neutralizes these attacks.
• Shared workstations: If multiple people use the same computer, a hardware key ensures that even if the computer is compromised, the attacker needs physical possession of a specific person's key to decrypt their files.
• Anyone encrypting data they absolutely cannot afford to have breached: Medical records, legal documents, financial records, trade secrets, journalism source material.

Practical Tips for Using Hardware Keys

Once hardware-key support ships, these tips will apply. The advice on PINs and labels holds for any security key today:

• Buy at least two keys. One primary, one backup. Register both with QNSQY at the same time. Store the backup in a different physical location than the primary. If your house burns down and both keys are in the same drawer, you have lost access to your data.
• Set a PIN on your key. FIDO2 keys support a PIN you choose (at least 4 characters). With a PIN set, a stolen key is useless without it. After too many wrong PINs the key blocks the PIN, and only a full reset, which erases its credentials, makes it usable again. This turns the key into its own two-factor device: the key itself is something you have, and the PIN is something you know.
• Label your keys. If you have multiple YubiKeys (personal, work, backup), put a physical label or colored sticker on each one. When QNSQY asks you to touch your key, you need to touch the right one.
• Keep a written record of which files are key-protected. If some files use password-only encryption and others use password-plus-YubiKey, you need to know which is which before attempting decryption.
• Do not leave your key plugged into your computer when not in use. The point of a hardware key is physical access control. If it is always plugged in, it provides no additional security over a password. Remove it after each encryption/decryption operation.

Hardware Keys and Air-Gapped Encryption

In the planned design, hardware keys would pair well with air-gapped workflows. The challenge-response happens entirely between your computer and the key over USB, with no server involved, so it would work on a machine with no internet connection.

The intended workflow: bring your YubiKey and a USB drive to the air-gapped machine. Plug in the YubiKey. Encrypt your files (which would require both your password and a touch of the key). Remove the YubiKey. Copy the encrypted files to the USB drive. The encrypted files can then be transported to networked systems, where they would stay safe even if those systems are compromised, because decryption would need the YubiKey that is back in your pocket.

Sources

1. FIDO Alliance FIDO2 Specifications - https://fidoalliance.org/specifications/
2. W3C Web Authentication (WebAuthn) Level 2 - https://www.w3.org/TR/webauthn-2/
3. NIST SP 800-63B: Digital Identity Guidelines, Authentication and Lifecycle Management - https://pages.nist.gov/800-63-4/sp800-63b.html
4. RFC 5869: HMAC-based Extract-and-Expand Key Derivation Function (HKDF) - https://www.rfc-editor.org/rfc/rfc5869
5. Yubico Developer Documentation: HMAC-SHA1 Challenge-Response - https://developers.yubico.com/yubico-pam/YubiKey_and_HMAC-SHA1_Challenge-Response.html

Related Articles

• Linux GUI Security: What Runs Today and What Is Planned
• Air-Gapped Encryption: Best Practices
• Getting Started with QNSQY CLI