Introduction
This article covers configuring YubiKeys for use with the KeePass open source password manager. Yubico typically does not host or maintain setup instructions for third party products, however an exception has been made for this third party, open source software offering.
Requirements
- A YubiKey that provides an OTP application
- Yubico Authenticator for Desktop (required for setup only)
- KeePass version 2 (version should be 2.xx)
- KeeChallenge, the KeePass plugin that adds support for HMAC-SHA1 challenge-response
Setup
- Install Yubico Authenticator for Desktop and open the application
- Insert the YubiKey
- From the Home (
) page, click Slots (
)
- Select Slot 2 (Long touch). Slot 2 is recommended since this slot is empty by default. Slot 1 comes preconfigured with Yubico OTP.
- Select Challenge-response
- Click the circle on the far right (
) to generate a random secret key
- Copy and save this key (it will be required later in order to complete the KeePass setup)
- If desired, click Require touch
- Click Save. If the slot is configured, you will be prompted to overwrite the existing content in the slot.
- Install KeePass and KeeChallenge, if you have not already done so. KeeChallenge is installed by copying the contents of the .zip file into the KeePass installation folder. Run KeePass, or restart it if it was already running.
- If there is an existing database, open it, and then click File > Change Master Key. If creating a new database, initiate the process, and then select your name and save location (you will be prompted to do this)
- In the Create Composite Master Key window, enter your master password, check Show expert options, check Key file / provider, and then select Yubikey challenge-response from the list
- Click OK (you should see a Secret Key Entry window appear)
- Paste the secret key generated in step 5 into the window, check Variable Length Challenge?, and then click OK
Tip: If you see the error "secret does not match yubikey" you didn't select Variable Length Challenge? - click this option when trying again.
- If you checked Require touch in step 8, you will be prompted to touch your YubiKey (its LED should also flash on and off steadily). If you didn't, your database should open immediately (if you are setting up a new database, you will be prompted to fill in some additional information).
- Read the emergency sheet pop-up if it appears. Make sure to save changes either by clicking File > Save or by answering Save when exiting KeePass.
- You can use the secret key (from step 6) to program the same challenge-response credential into a backup YubiKey using Yubico Authenticator, so consider doing this and/or saving it somewhere safe for future use.