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 & PrivacyInput Monitoring, and allow input monitoring for YubiKey Manager.
  3. Click ApplicationsOTP
    YubiKey Manager: OTP slot selection
    YubiKey Manager: OTP slot selection
  4. Choose the slot to configure. The first slot is reserved in some keys, so select Configuration Slot 2.
    YubiKey Manager: OTP credential type
    YubiKey Manager: OTP credential type
  5. Select Challenge-response credential type and click Next.
    YubiKey Manager: Challenge-response secret key
    YubiKey Manager: Challenge-response secret key
  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”.)

YubiKey Manager: Allow OTP via both interfaces
YubiKey Manager: Allow OTP via both interfaces

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:

How to configure a new database to use YubiKey How to configure a new database to use YubiKey
How to configure a new database to use YubiKey

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:
    Change Master Key button in KeePassium toolbar
  • Tap the hardware key button and select YubiKey Slot 2:
    How to change the existing master key to include YubiKey How to change the existing master key to include YubiKey
    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.

Using YubiKey with KeePassium for iOS Using YubiKey with KeePassium for iOS Using YubiKey with KeePassium for iOS
Using YubiKey with KeePassium for iOS

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

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 devices with the Lightning port are fully supported.
  • 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.
  • As a workaround, you can use YubiKey 5Ci (with Lightning port) via Apple’s USB-C to Lightning adapter. (It has to be made by Apple; unfortunately, cheap adapters don’t work properly.)

See also

Last Updated: 2023-10-27