- Configure Nitrokey for use with KeePassXC
- New Database
- Existing Database
After long wait, with KeePassXC version 2.7.6, we finally have Nitrokey 3 support! This means we can use a Nitrokey as an easy method for quickly unlocking a KeePassXC password database.
We can use a Nitrokey in combination with other security methods, in order to create a stronger lock. Alternatively, for convenience, you can use just the Nitrokey by itself. This would allow us to simply plug in the USB in order to unlock the password database.
You must be using KeePassXC version 2.7.6 or newer in order to use Nitrokey 3. We’re using a NitroKey 3A Mini, with firmware version 1.5.0 on Arch Linux.
If you don’t already have a NitroKey, you can get one at the link below.
Configure Nitrokey for use with KeePassXC
The first thing you need to do,
is add a challenge-response secret to your Nitrokey.
To do this, you need the
Next, you need to pick a password that is exactly 20 bytes long. This can be done by picking a twenty character password, and running the follow command:
$ nitropy nk3 secrets add-challenge-response 2 $(echo your-20-byte-secret | base32) Command line tool to interact with Nitrokey devices 0.4.39 Please touch the device if it blinks Done
This converts our 20-character secret to base32, and stores it in slot 2 of our Nitrokey.
Use the following command to check that the secrets were added correctly.
$ nitropy nk3 secrets list Command line tool to interact with Nitrokey devices 0.4.39 01. HmacSlot2 Hmac/Sha1
The last line shows there is a HMAC/SHA1 secret in slot 2. This is used for our KeePassXC challenge response.
You can store your 20-byte secret in your KeePassXC database itself, but it won’t help you if you lose/break your Nitrokey, since you won’t be able to unlock your database if you forget it. So make sure it’s something you won’t forget, or otherwise write it down and keep it somewhere safe.
We can now proceed with using it in KeePassXC.
Create a new database as normal. Once you get to the “Database Credentials” section, the window will look like the one below.
Add additional protection...
and scroll to the bottom to find the
The UI still only says YubiKey/OnlyKey, but NitroKey will work.
and make sure your NitroKey is listed.
If your key is not listed, see the troubleshooting section below.
Not recommended, but you can press the cancel button under the password input, in order to require only the hardware Nitrokey.
This will result in KeyPassXC confirming that you really want to proceed without a password.
Before adding passwords to your database, save it, lock it, and confirm you can open it again with your key.
If all goes well you’re free to fill up the database with all your passwords.
We recommend making a copy of your database. If something goes wrong and you lock yourself out, you’ll still have the old copy. Once you verify the you can unlock the new database with the new method, you can safely delete the old copy.
For enabling challenge-response on an existing KeePassXC database, you must first unlock the database using the current unlock method. The database must be unlocked before changing any of it’s security settings.
Database Security in the main menu,
to change security settings.
From here, follow the same steps as in New Database. After verifying you can unlock your database, you can delete the old copy without the Nitrokey security.
If you’re having issues getting this to work, the problem could be either a misconfigured key, or a problem with KeePassXC. Let’s look at some solutions, from the ground up.
If your Nitrokey is not detected by nitropy,
you may need to install the
libfido2 package and Nitrokey udev rules
(available on the Nitrokey website).
If you’re having problems with creating the secret on the key, try the following steps.
If you’re using any Python version (older or newer) than 3.9 or 3.10, you may get the following Python error while using nitropy:
Critical error: An unhandled exception occurred Exception encountered: AttributeError("module 'semver' has no attribute 'Version'")
If so, install/run nitropy with Python version 3.9 or 3.10, or create a python virtual environment, and running the commands again.
python3 -m venv nitrokey-venv cd nitrokey-venv ./bin/activate pip install pynitrokey
If KeePassXC doesn’t detect the key, try these methods.
On Arch Linux we needed the
pcscd service started
sudo systemctl start pcscd.service