Hardware Keys (YubiKey)

A hardware key is a small physical device — a YubiKey — that you tap against your iPhone or plug into your Mac to unlock your vault. Like a key file, it is an extra factor on top of your master password, but unlike a file it cannot be copied: the secret lives inside the key’s chip and never comes out. PanicVault uses the same challenge-response scheme as KeePassXC, so a vault protected by a YubiKey opens in both apps.

What a Hardware Key Does

When you unlock a hardware-key vault, PanicVault sends the key a challenge — a block of data taken from the vault file itself. The YubiKey computes an answer using an HMAC-SHA1 secret that only it holds, and sends the answer back. PanicVault mixes that answer into the vault’s encryption key alongside your master password, then discards it.

This means:

• The secret never leaves the key. PanicVault never sees it, never stores it, and never syncs it. It also never stores the key’s answer or its serial number.
• The vault file itself is unchanged. A hardware-key vault is a normal .kdbx file. Nothing inside it records that a YubiKey is required, which is also why PanicVault has to remember that fact for you.
• Both factors are needed. Someone who steals your vault file and learns your master password still cannot open it without your YubiKey. Someone who steals your YubiKey cannot open it without your master password.

Which YubiKeys and Devices Work

PanicVault supports YubiKey challenge-response over NFC on iPhone, and over USB on Mac.

• iPhone — NFC. A YubiKey with NFC and an HMAC-SHA1 challenge-response slot, such as the YubiKey 5 NFC or 5C NFC. You hold the key against the top of the phone.
• Mac — USB. Any USB YubiKey with an HMAC-SHA1 challenge-response slot. You plug it into a USB port.

Those two are the whole list. What does not work:

• iPad. iPad cannot read a YubiKey in PanicVault. Unlock the vault on an iPhone or a Mac instead.
• A YubiKey plugged into an iPhone or iPad over USB-C. The YubiKey answers challenge-response only over a USB channel that iOS does not make available to apps. This is a limitation of the key and of iOS, not something PanicVault can work around.
• Lightning keys, including the YubiKey 5Ci. Not supported, on any device.
• An external NFC reader plugged into a Mac. Not supported. On a Mac, use a USB YubiKey.
• The KeeChallenge plugin format used by KeePass 2 on Windows. See KeePass Compatibility.
• KDBX 3.x files. PanicVault is KDBX 4 only.
• More than one YubiKey per vault. A vault uses one key and one slot — but you can and should program a second, identical key as a backup.

Setting Up Your YubiKey

PanicVault does not program YubiKeys; it only talks to a key that is already set up. Use Yubico’s free YubiKey Manager on a Mac, Windows or Linux computer:

1. Open YubiKey Manager with your YubiKey plugged in
2. Go to the OTP application and choose a configuration slot — Slot 1 or Slot 2
3. Choose Challenge-response, then HMAC-SHA1
4. Generate or enter the 20-byte secret. If the tool asks whether the input is a fixed 64-byte challenge or variable length, choose variable length — that is the usual choice and the one KeePassXC users make
5. Decide whether the key should require a physical touch. Either setting works with PanicVault; requiring a touch means nothing can use the key without you present
6. Write the configuration to the slot

Which slot? Slot 1 usually ships pre-programmed with Yubico OTP, so slot 2 is the one most people use — and slot 2 is KeePassXC’s default. PanicVault also defaults to slot 2. Whichever you choose, remember it: you pick the slot on the lock screen.

Creating a Vault with a YubiKey

When you create a new vault, scroll to the Hardware Key (Optional) section:

1. Turn on Protect with a YubiKey
2. Choose Slot 1 or Slot 2 (slot 2 is the default)
3. PanicVault immediately sends a test challenge to your key, so you find out right away whether that slot really is set up for challenge-response. On iPhone, hold the key against the top of the phone; on Mac, plug it in. Touch the key if it asks
4. Read the warning about losing the key, and tick I have a backup YubiKey, or I accept that losing this key destroys the vault
5. Finish creating the vault as usual. You are asked for the key once more as the vault is written — two touches in all, because the answer has to be computed for the file that is actually created

From that point on, the vault needs your master password and your YubiKey. For the rest of the create-vault steps, see Getting Started.

Unlocking with a YubiKey

On the lock screen, just below the key file row, there is a YubiKey row:

• If PanicVault does not know that this vault uses a YubiKey, the row shows Optional on the right. Turn it on if the vault needs a key.
• If PanicVault knows the vault uses one, the row shows Required in the accent color and is on already.
• When the row is on, it expands to show a Slot 1 / Slot 2 picker. Pick the slot your key is programmed on.

On iPhone (NFC)

1. Type your master password
2. Make sure the YubiKey row is on and the right slot is selected
3. Tap Unlock
4. iOS shows its own NFC panel asking you to hold the top of your iPhone against your YubiKey. Hold the key flat against the top of the phone
5. When the prompt says Touch your YubiKey, touch the gold disc — and hold it there. The key has to stay against the phone for the whole exchange. Tapping and pulling away is the most common cause of a failed unlock

On Mac (USB)

1. Plug your YubiKey into a USB port
2. Type your master password, make sure the YubiKey row is on with the right slot, and click Unlock
3. PanicVault shows Touch your YubiKey; touch the gold disc

The very first time you use a YubiKey on a Mac, PanicVault shows an explanation and macOS then asks for the Input Monitoring permission. Your YubiKey talks to your Mac over the same USB channel a keyboard uses, so macOS asks for this permission before any app can read it. PanicVault only sends your vault’s challenge to the key and reads its answer — it never watches what you type.

If you decline, PanicVault cannot read the key over USB and says so, with a button that opens the right settings pane. You can grant it later in System Settings → Privacy & Security → Input Monitoring, and you can revoke it there at any time. Your iPhone is unaffected — the same vault still unlocks over NFC.

Adding or Removing a YubiKey on an Existing Vault

You can add a YubiKey to a vault that does not have one, move it to the other slot, or remove it — from the same screen where you change your master password:

1. Unlock the vault and tap the gear icon in the entry list toolbar to open Database Settings
2. In the Master Password section, tap Change Master Password
3. Use the hardware key row:
   • Add a YubiKey — pick the slot. PanicVault verifies the slot answers a test challenge before it commits anything
   • Change slot — move the vault to the other slot on the same key
   • Remove the YubiKey — the vault goes back to master password (plus key file, if it has one)
4. Confirm

PanicVault re-encrypts the whole vault once with the new combination and saves it. Adding a key or moving it to the other slot costs two touches: one to test the slot before anything is committed, and one as the change is saved, because the answer has to be recomputed for the newly written file. Keeping the key while you change only the password costs one. Removing a key costs no extra touch beyond the one that opened the vault. See Vault Settings for the rest of that screen.

Face ID / Touch ID and Hardware Keys

Face ID and Touch ID work on hardware-key vaults, exactly as they do on any other vault. There is a trade-off worth understanding, and PanicVault shows it to you once, the first time you enable biometric unlock on a vault that uses a YubiKey:

In plain terms: enabling biometrics trades some of the YubiKey’s protection for convenience on that one device. The key that biometrics unlocks is stored in the device Keychain, protected by the Secure Enclave, and is invalidated if the device’s enrolled fingerprints or faces change. Every other device still needs the physical key, and so does this one whenever biometric authentication fails or your master password is required again.

If you would rather keep the YubiKey mandatory everywhere, leave biometric unlock off in Security & Settings.

Syncing and Other Devices

A hardware-key vault syncs through iCloud Drive or Google Drive like any other vault. Only the .kdbx file syncs; nothing about your YubiKey does.

• One touch per unlock, none per save. PanicVault asks for the key once, when you unlock, and then does not ask again for the rest of the session — editing and saving entries costs no further touches. KeePassXC works differently: it asks for a touch on every save. The files stay fully interoperable either way.
• AutoFill needs no key. Once you have unlocked the vault in PanicVault, AutoFill on iPhone and Mac works on hardware-key vaults exactly as it does on any other vault. The AutoFill extension never opens the .kdbx file, so it never needs your YubiKey.
• If the vault changed elsewhere, for example because you saved it in KeePassXC on your desktop, PanicVault may need a fresh answer from your key before it can merge. It shows a banner rather than failing silently:

Tap Touch YubiKey on the banner and the sync completes. PanicVault never asks for a touch on its own in the background — a touch is only ever requested for something you started.

Troubleshooting