How to use YubiKey with KeePassium/KeePassXC

Initial setup

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

  1. On your computer, install the YubiKey Personalization Tool and launch it
  2. Switch to the Challenge-Response tab
  3. Insert your YubiKey, if you have not done that yet.
    (MacOS Catalina: If you see an “Unknown error occurred”, go to system preferences — Security & Privacy — Input Monitoring, and allow input monitoring for YubiKey Personalization Tool.)
  4. Set the programming options:
    • Select Configuration Slot 2
    • Configuration Protection — if you are not sure what this means, leave the default “YubiKey(s) unprotected - Keep it that way”
    • Require user input (button press) — 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).
    • Select Fixed 64 byte input
    • Secret Key (20 bytes Hex) — 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.
  5. Finally, press Write Configuration to program the YubiKey.
Screenshot: YubiKey configuration for the challenge-response mode.

Using YubiKey in KeePassium

Now you can add the YubiKey as a component of the master key (in addition to your password and/or key file). This will work anywhere in KeePassium, be it “Unlock Database”, “Create Database” or “Change Master Key” screen.

Press the small button that looks like USB YubiKey:

Screenshot: Using YubiKey with KeePassium for iOS
Using YubiKey with KeePassium for iOS

Select YubiKey Slot 2:

Screenshot: YubiKey selector in KeePassium for iOS
Select YubiKey slot

Now enter your password and/or choose the key file. The master key cannot be based only on YubiKey.

Once prompted, scan your YubiKey (touch it with the top side of your phone). That's it!

Screenshot: YubiKey scan prompt in KeePassium for iOS
YubiKey scan prompt

Compatibility

KeePassium's challenge-response implementation is compatible with KeePassXC and Keepass2Android), but not compatible with the KeeChallenge plugin of the “regular” KeePass.

Using YubiKey in AutoFill

Apple does not allow Password AutoFill extensions to communicate with hardware. Therefore, YubiKey-protected databases cannot be used in AutoFill. We are exploring a possible workaround.

Last Updated: 2020-01-30