How to use YubiKey with KeePassium
Initial setup
The following steps will prepare your YubiKey for the challenge-response mode.
- On your computer, install the YubiKey Manager and launch it
- Insert your YubiKey, if you have not done that yet.
- If you see an “Unknown error occurred” on macOS, go to system preferences → Security & Privacy → Input Monitoring, and allow input monitoring for YubiKey Manager.
- Click Applications → OTP
YubiKey Manager: OTP slot selection - Choose the slot to configure. The first slot is reserved in some keys, so select Configuration Slot 2.
YubiKey Manager: OTP credential type - Select Challenge-response credential type and click Next.
YubiKey Manager: Challenge-response secret key - Set your HMAC-SHA1 challenge-response parameters:
- Secret key — press Generate to randomize this field. Make sure to copy and store the generated secret somewhere safe. If you ever lose your YubiKey, you will need that secret to access your database and to program the replacement YubiKey.
- Require touch — this prevents rogue apps from talking to your YubiKey without your permission. When KeePassium requests your YubiKey, you will need to touch the “Y” button on the NFC key (or touch the sides of the YubiKey 5Ci key).
- Press Finish to program the YubiKey.
As a final step, make sure that apps can talk to your YubiKey. Click Interfaces and make sure that OTP is checked for both USB and NFC interfaces. (Otherwise KeePassium might show something like “YubiKey select applet failed with code 0x6A82”.)
Using YubiKey with your database
Once your YubiKey is configured, you can add it as a component of the database master key, along with a password and key file (or instead of them).
Set up a new database
When creating a new database, tap the hardware key button and select YubiKey Slot 2:


Set up an existing database
To make YubiKey a required master key component for your existing database:
- Open the database with the current master key (password and/or key file)
- Tap the Change Master Key button at the bottom of the screen:
- Tap the hardware key button and select YubiKey Slot 2:
How to change the existing master key to include YubiKey - Tap Done to save changes.
- Once prompted, insert or scan your YubiKey (touch it with the top side of your phone).
- That’s it! Now the database can be decrypted only with your YubiKey.
Unlocking a database
To unlock a YubiKey-protected database, tap the hardware key button and select YubiKey Slot 2. If necessary, enter your password and/or choose the key file.



Once prompted, insert or scan your YubiKey (touch it with the top side of your phone). If all the master key components are correct, the database will open up.
Using YubiKey in AutoFill
Apple does not allow Password AutoFill extensions to communicate with hardware, such as YubiKeys.
However, there is a workaround:
- Open KeePassium settings → Data Protection
- Turn on the Remember Master Keys option
- Make sure that Database Timeout is something longer than “Immediately”
- Turn on the Cache Derived Encryption Keys option
- Unlock your database in KeePassium app. KeePassium will remember the decryption key of the database.
- Switch to AutoFill. It will open your database using the remembered key, without asking for YubiKey.
Once your database is edited on any other device, the decryption key would change. Simply unlock your database in the main KeePassium app again; this will update the decryption key for the AutoFill.
Compatibility
YubiKey models
Your YubiKey must support HMAC-SHA1 Challenge-Response mode. As of November 2021, compatible models are:
- YubiKey 5 NFC
- YubiKey 5C NFC
- YubiKey 5Ci (via Lightning port)
Incompatible models:
- YubiKey Security Key Series — no Challenge-Response functionality
- YubiKey Bio Series — no Challenge-Response functionality
- YubiKey 5 Nano, 5C, 5C Nano — they have only USB interface, but iOS devices cannot communicate with YubiKey via USB. You can these keys with KeePassXC, though.
Other apps
KeePassium’s challenge-response implementation is compatible with KeePassXC and Keepass2Android, but not compatible with the KeeChallenge plugin of the “regular” KeePass. Here’s why: Why you should avoid KeeChallenge for YubiKey support.
iPad limitations
- iPad devices do not have NFC hardware and thus won’t work with NFC keys.
- iPad Pro devices with USB-C port cannot use YubiKey in challenge-response mode. The reason is the limited support for USB accessories on iPadOS. However, you can use your YubiKey to type in a long master password.
- iPad devices with the Lightning port are fully supported.
See also
Last Updated: 2021-11-30