Create a New YubiKey Protected Database

Strongbox supports YubiKey protected databases (using the KeePassXC challenge-response mode). You can read more about how this whole process came together on Github here.

At the moment Strongbox supports YubiKey on Mac and iOS (NFC (iOS 13+) and the 5Ci over lightning).

There are 2 key steps to getting setup to use YubiKey.

  1. Program your YubiKey for HMAC-SHA1 challenge response
  2. Create a new YubiKey protected database on iOS.

We’ll cover them both below...

1) Program your YubiKey for HMAC-SHA1 Challenge Response

First you need to program your YubiKey using one of YubiKey's tools designed for this process. There are two available tools on YubiKey's website, the newer YubiKey Manager and the older YubiKey Personalization Tool. We'll cover both tools below...

1a) Program your YubiKey for HMAC-SHA1 Challenge Response using the YubiKey Manager

In this example we’ll use the YubiKey Manager tool on Mac, but the steps will be very similar on other platforms. The YubiKey Manager tool looks like this when you open it initially

YubiKey Manager Initial Screen
Click Applications > OTP now to see a screen that looks like this:

Applications \> OTP Screen
Applications > OTP Screen

You need to choose which slot on your YubiKey device you want to program for KeePass HMAC-SHA1 challenge response. This is entirely up to you (but careful not to overwrite any existing slot you are using elsewhere). Just remember which slot you chose as you will need to tell Strongbox in step 2 below and when unlocking your database.

YubiKey Manager Credential Type
Credential Type Screen

Select Challenge Response when asked what type of credential you want and click Next.

Challenge Response Screen

Challenge Response Configuration Screen

  1. Click ‘Generate’ to generate a new Secret Key or enter an existing Secret Key if you have one you want to use.
  2. Optionally you can check the 'Require Touch' checkbox if you want to require a physical touch before every save (this may be cumbersome).
  3. Click ‘Finish’.

Important: Store the Secret Key somewhere very safe (this can be used in an emergency by Strongbox to recover access to your database without the hardware key).

Your YubiKey is now ready to use with Strongbox in HMAC-SHA1 challenge response mode. Skip on to step 2 to learn how to create a YubiKey protected database in Strongbox.

1b) Program your YubiKey for HMAC-SHA1 Challenge Response using the YubiKey Personalization Tool

In this example we’ll use the YubiKey Personalization Tool on Mac, but the steps will be very similar on other platforms. The YubiKey Personalization Tool looks like this when you open it initially
image

Initial YubiKey Personalization Tool Screen

Click Challenge-Response Mode now to see a screen that looks like this:
image

YubiKey Challenge-Response Mode Screen

Select HMAC-SHA1 to move onto the configuration stage.
image

HMAC-SHA1 Configuration Screen

Now:

  1. Click to select ‘Configuration Slot 1’ or ‘Configuration Slot 2’ (careful not to overwrite any existing or in use slot)
  2. Click ‘Generate’ to generate a new Secret Key
  3. Click ‘Write Configuration’.

Important: Store the Secret Key somewhere very safe (this can be used in an emergency by Strongbox to recover access to your database without the hardware key).

Your YubiKey is now ready to use with Strongbox in HMAC-SHA1 challenge response mode. Read on to learn how to create a YubiKey protected database in Strongbox.

2) Create a new YubiKey protected database on iOS.

Once you have a YubiKey with HMAC-SHA1 available on one of it’s slots you can create a YubiKey protected database in Strongbox by:

  1. Tap the ‘+’ button in the top right
  2. Choose ‘New Database (Advanced)’
  3. Choose Storage Location (e.g. Local Device)
  4. The ‘Set Credentials’ screen will popup.
  5. Enter a Password (optional)
  6. Under the YubiKey section choose NFC or Lightning and whichever slot you programmed for HMACSHA1
  7. Tap ‘Create’
  8. You will be prompted to scan or insert your YubiKey now. Do so!

That’s it you’ve created your database. Now whenever you go to open that database you’ll be requested to scan or insert your YubiKey, and similarly when you Save it.

Now that you're setup, here are a couple of interesting and related articles you should consider reading:

How can I use YubiKey in AutoFill mode?

How do I recover from YubiKey device loss, what is a Virtual Hardware Key?

My Yubikey device is not working/visible/available on Strongbox on my Mac

Troubleshooting

This function is unsupported or configured for this key/slot

This can happen for a number of reasons, even if you have properly programmed your Key/Slot for HMACSHA1 Challenge Response. It could mean a faulty YubiKey device but first you should check the following setting using the "Yubikey Manager" tool. There is a setting to enable/disable specific functions for USB or NFC. OTP via NFC/USB should be enabled, so make sure to check this.