Introduction

This article covers two methods for using YubiKeys with the KeePass password manager: HMAC-SHA1 Challenge-Response and OATH-HOTP. HMAC-SHA1 is recommended over OATH-HOTP because of its ease-of-use, as well as its ability to be backed up (it is not possible to have a backup YubiKey when OATH-HOTP is used).

HMAC-SHA1 Challenge-Response (recommended)

Requirements

1. A YubiKey with configuration slot 2 available
2. YubiKey Manager
3. KeePass version 2 (version should be 2.xx)
4. KeeChallenge, the KeePass plugin that adds support for Challenge-Response

Setup

1. Install YubiKey Manager, if you have not already done so, and launch the program.
2. Click Applications > OTP.
3. Since KeeChallenge only supports use of configuration slot 2 (this slot comes empty from the factory), click Configure under the Long Touch (Slot 2).
4. Select Challenge-response and click Next.
5. Generate a secret key by clicking Generate, and copy it somewhere (this will be needed later for KeePass setup). If desired, check Require touch. Click Finish, and confirm if prompted.
6. 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.
7. If you already have an existing database, open it, then click File > Change Master Key. If you are creating a new database, initiate the process, then select your name and save location (you will be prompted to do this).
8. You should see the Create Composite Master Key window. Enter your master password, check Show expert options, check Key file / provider, and select Yubikey challenge-response from the list.
9. Click OK, and you should see a Secret Key Entry window appear.
10. Paste the secret key generated in step 5 into the window, check Variable Length Challenge?, and click OK. (Note: If you see the error "secret does not match yubikey," this option hasn't been selected.)
11. If you checked Require touch in step 5, 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).
12. 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.
13. You can use the secret key (from step 5) to program the same Challenge-Response credential into a backup YubiKey using YubiKey Manager, so consider doing this and/or saving it somewhere safe for the future.

OATH-HOTP

Requirements

1. A YubiKey with a spare configuration slot
2. KeePass version 2 (version should be 2.xx)
3. The YubiKey Personalization Tool
4. OtpKeyProv, the KeePass plugin that adds support for OATH-HOTP

Setup

1. Install the YubiKey Personalization Tool, if you have not already done so, and launch the program.
2. Click OATH-HOTP, then click Advanced.
3. Select the configuration slot that you want to program. These instructions assume you want to use the second configuration slot, which is, by default, empty.
4. Uncheck OATH Token Identifier.
5. Specify the HOTP Length. The longer the length is, the more secure it is. These instructions assume you want to use the 8 digits.
6. Click Generate to generate your secret key. You will need this key to program your KeePass database and to recover it if something goes wrong. Copy this key and keep it in a secure location.
7. Click Write Configuration. A message stating that your YubiKey has been successfully configured is displayed in the Results pane.
8. Click Settings.
9. Under Output Settings, disable the carriage return on the output by clicking the Enter button (it is enabled by default; it should change from blue to white/gray).
10. Click Update Settings, select the Configuration Slot you programmed your OATH-HOTP credential into (probably slot 2), click Update, and confirm to save your changes.
11. Install KeePass and OtpKeyProv, if you have not already done so. Install OtpKeyProv by copying the files in the zip folder into KeePass' installation folder. Run KeePass.
12. If you already have an existing database, open it, then click File > Change Master Key. If you are creating a new database, initiate the process, then select your name and save location (you will be prompted to do this).
13. You should see the Create Composite Master Key window. Enter your master password, check Show expert options, check Key file / provider, and select One-Time Passwords (OATH HOTP) from the list.
14. Click OK. A Configure OTP Lock window should appear. In it, configure the plug-in with the same parameters as you used to configure the YubiKey. Select the same HOTP length as you chose earlier and copy over the secret key. Leave the counter value untouched.
15. In the same window, configure your database protection settings. The look-ahead count refers to the number of events (like pressing the YubiKey’s button) that can be skipped before the token goes out of sync. A higher number of OTPs and a lower look-ahead count generally equate to increased security at a higher inconvenience. We strongly recommend a look-ahead count that is greater than 0; somewhere between 5-10 should work for most.
16. Congratulations, you've successfully configured your YubiKeys to protect your KeePass database with OATH HOTP! To test your login, lock your database and attempt to regain access to it. At the log in screen, enable Key File and select One-Time Passwords.
17. In the dialog box that is displayed, position the cursor at the start of each bar and emit 3 consecutive passcodes (one for each bar) by pressing the button on your YubiKey for three seconds.
18. If you are able to gain access to your database, then everything has been configured correctly. If not, use the recovery mode together with your secret key to gain access and try again. If the one-time passwords generated by your YubiKey are rejected, double-check your look-ahead count from step 15; this controls the database's tolerance for out-of-sync counters, which are the most common cause of this issue.