KeePass Security with YubiKey, OATH HOTP, and NDEF

KeePass is an awesome, free, and open source password manager. I first stumbled upon it back when I was an IT Operations Manager for a medium sized organization. My team used it as a secrets vault to share and safeguard various keys and passwords used for infrastructure components. I’ve been hooked ever since.

However, after picking up the YubiKey 5 NFC and writing about how to set it up as a OTP source and as a security key, I was curious if I could switch to a more secure authentication model. I have been using a combination of password and KeePass key file to protect the password database. Instead, I wanted to use a password combined with Open Authentication (OATH) HMAC-based One-time Password algorithm (HOTP) via the YubiKey. Ideally, this should be something I can do on my Windows desktop and Android phone!

I gotta manage my keys, y’all!

After sleuthing around a bit, I found that this is indeed possible. This post will outline the steps necessary to convert a KeePass database over to using an OATH HOTP configuration slot on the YubiKey, along with NFC Data Exchange Format (NDEF) to supply values when using NFC.

Note: I’m using Windows 10 and Android 10 (Q) in this post. I’m assuming similar functionality will work with KeePassXC for Linux and MacOS but have no way of validating this.

Contents

Requirements

You’re going to need the YubiKey Personalization Tool in order to make some configuration changes to your YubiKey. At the time of this post, the latest version is 3.1.25 (GUI) and 1.19.0 (CLI). I’m going to opt for the GUI tool for this walkthrough.

You’ll also need to make sure that KeePass 2.x is installed along with the OtpKeyProv plugin. Drop the contents of the plugin into the Plugins folder in your KeePass installation path. OtpKeyProv’s download zip includes a Read Me file that includes documentation and some interesting information on key size and security ratings.

Some good information can be found in the plugin's Read Me file. — Some good information can be found in the plugin’s Read Me file.

If you plan on using the Android version of KeePass, I suggest the Keepass2Android Password Safe app on the Google Play store. There’s also an app called KeePassDroid that I used for many years, but it does not seem to support the YubiKey.

YubiKey Setup for KeePass on Desktop

The first step is to setup your YubiKey to provide OATH HOTP values for your database along with generating a secret key.

Note: Make sure to make a backup of your KeePass database so that you have an easy way to revert any changes if the process fails due to human or machine error. ?

Fortunately, Yubico has a fantastic write-up entitled Using Your YubiKey with KeePass that you can follow. These steps worked perfect for me. Just like with the guide, I also used the second YubiKey configuration slot (3-second button press) for OATH HOTP so that my primary YubiKey configuration slot (immediate button press) could remain for OTP requests.

Modifying an Existing KeePass Database

If you are modifying an existing KeePass database, first unlock the database and then choose the Change Master Key option in the file menu. This will let you toggle to the new OATH HOTP provider and input your configuration values for the secret key, counter, number of OTPs, and look-ahead count. While this is mentioned in the guide, I added a screenshot of what it looks like to modify the database below.

Modifying an existing KeePass database to add an OATH HOTP provider.

Logging into the Database with OATH HOTP

The prompt for OTPs will appear after entering your password, making sure that OATH HOTP is selected, and then clicking OK. Since we’re using Configuration Slot 2, which requires a 3-second press, make sure to have your cursor set to the first OTP box and then hold the YubiKey golden ‘Y’ button down for 3 seconds. After the value is entered, release for a few seconds and then repeat until all values are entered before hitting OK.

Supplying a password and several OTPs will unlock the KeePass database.

There’s a few helpful options in the Options tab. I use the Auto-Tab feature to advance to the next OTP box as they are filled in.

KeePass offers some handy options to speed things up.

With this complete, save and then close the database. Try unlocking your database a few times to make sure you have the feel of the process down and aren’t hitting any issues with your database passwords.

YubiKey Setup for KeePass on Android

With the KeePass database now configured for OATH HOTP, setup can begin to make this available over Android. If you haven’t already, download the Keepass2Android Password Safe app from the Google Play store.

You’ll need to get the KeePass database over to your phone. For this, I lean on DropBox to sync the files over to my phone and back. However, there are several other options you can explore at your leisure.

The two files you’ll need to sync are:

The KeePass database file (.kdbx)
The OTP auxiliary file (.otp.xml)

A GitHub user by the name of jakseb (Sebastian Jakubiak) has posted a fantastic guide named How to use Keepass2Android with YubiKey NEO. You can use this guide to program the YubiKey 5 NFC as well with slight modification.

Important: The YubiKey NEO guide references using the YubiKey Personalization Tool for NDEF Programming using Configuration Slot 1. You should use Configuration Slot 2. This is where we have configured OATH HOTP in the previous section. If you forget to do this, you’ll see raw OTP codes being sent to the database, which will not work.

When loading the database and OTP auxiliary file from DropBox, you will be required to permit the Keepass2Android application to modify the files. Future database operations will require fewer setup steps and remembers where your OTP auxiliary file is stored. You can also leave QuickUnlock enabled to force KeePass to stay in memory and avoid having to sync your OTP counter.

Contrary to the details in the app, you do not need the YubiClip app for anything. The 8 digit codes should appear when the NFC connection is made between the Android device and the YubiKey 5 NFC.

Once the KeePass password is entered, tap the YubiKey 5 NFC to the back of the phone to enter each of the required OTP values.

Assuming you kept the default values and set the look-ahead to zero, there is a possibility of getting out of sync and losing access to the database. If this happens, open the database in Restore Mode and supply the secret key to get back in and request that KeePass generate another master key.

Thoughts

I certainly do appreciate all of the hard work that KeePass community has put in to add YubiKey to the ecosystem! My contribution is simply to put a few pieces together and try it out on newer hardware. I also find that the use of HOTPs to unlock the database isn’t all that cumbersome for the security value that it returns, which is nice.