How to use YubiKey with KeePassium

Initial setup

The following steps will prepare your YubiKey for the challenge-response mode.

1. On your computer, install the YubiKey Manager and launch it
2. 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.
3. Click Applications → OTP

   

4. Choose the slot to configure. The first slot is reserved in some keys, so select Configuration Slot 2.

   

5. Select Challenge-response credential type and click Next.

   

6. 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).
7. 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:

  

• 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.

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

• KeeChallenge for YubiKey, and why you should avoid it

Last Updated: 2021-11-30