Implementation of FIDO2 hmac-secret extension in KeePassXC

[ashleysommer]

Currently, Hardware Security Key support in KeePassXC is implemented on a device-specific basis, and only supports devices that expose a HMAC Challenge-Response feature. As a result, only some higher-end Yubikey models, and OnlyKey devices are supported (and an open Pull Request for NitroKey3 challenge-response support).

FIDO2 is a device-agnostic protocol implemented by a wide-range of hardware security keys from many different vendors. FIDO2 is most commonly used as part of the WebAuthN web authentication protocol, but it does have other use cases. There is an official FIDO2 extension called "hmac-secret", that allows supporting devices to produce a HMAC based on an input (the "salt"), in much the same way the HMAC Challenge-Response feature works, but without the need for application Resident Keys saved the device.

Implementing support for FIDO2 "hmac-secret" will have the immediate effect of adding support for a wide range of hardware security keys, including:

• Yubikey's more affordable "Secruity Key" FIDO2 series
• Token2 T2F2
• Trezor Model T
• Ledger Nano X (with updated Firmware)
• Hypersecu Hyperfido PRO FIDO2
• Feitian ePass K9 USB
• GoTrust Idem Key
• TrustKey T110, and TrustKey G310H
• and likely many others.

A Github issue for Adding support for FIDO2 "hmac-secret" extension in KeePassXC has been open since September 2019.
In that thread there has been much discussion about the use of FIDO2, many users indicating their support for the feature and further discussion focusing on the road blocks, particularly the use of FIDO2 on Windows 10 and Windows 11.

Since the release of Libfido v1.12 and the latest update of Windows 11, those limitations are resolved and the roadblocks are behind us. I don't see anything else standing in the way of a cross-platform implementation of FIDO2 "hmac-secret" support in KeePassXC.

Three days ago a user placed a financial reward bounty on the thread, to be awarded when the implementation is completed and merged into KeePassXC. This has renewed interest in the topic and spurred further discussion in the github issue thread.

I personally have experience in implementing FIDO2, particularly the "hmac-secret" extension in Python using the python-fido2 module, and have recently implemented a standalone proof of concept in c++ using libfido. I have offered to complete the implementation of the feature in KeePassXC and attempt to claim the bounty, however there are specifics that need to be discussed for how the new implementation will best fit into the KeePassXC codebase and co-exist with the existing Yubikey and OnlyKey device-specific code. That is the purpose of this discussion thread.

[droidmonkey]

Bottom line it must work, from the ui front, exactly how the yubikey implementation works. Otherwise have at it. I am still not convinced many hardware tokens implement the hmac-secret.

From a later post:

The list of supported extensions is provided in the authenticatorGetInfo response. In CTAP2.1 support for the hmac-secret extension is mandatory.

[ashleysommer]

Through reading technical documentation, trawling support forums, reading technical reviews, and emailing service contacts, I have confirmed that each of those models listed above do implement the hmac-secret extension. That is more than half of the FIDO2 devices I checked, and more than enough to justify the work to get it supported in KeePassXC.

Having said that, only testing with physical devices in hand will confirm support for certain.

[BryanJacobs]

If you're talking about hardware support, I have a library that would enable use on most Javacards (the majority of Smartcards out there): https://github.com/BryanJacobs/FIDO2Applet/ .

It fully supports the hmac-secret extension when the authenticator has a PIN set. So in addition to whatever hardware works natively, you also get any hardware designed to run Javacard applets.

libfido2 is a good thing to use if you want lots of people able to use their various devices with keepassxc.

[ashleysommer]

For full transparency, I have been approached by a representative from Trezor, who is sending me a Trezor Model T free of charge for testing purposes.

Aside from that, I have a Yubikey "Security Key Series", that does not have Challenge-Response but does have FIDO2 hmac-secret, that I have been testing with, and I am talking with Hypersecu to possibly get a Hyperfido PRO for testing, because their 'hmac-secret' support is unconfirmed and untested as yet.

[eminhuseynov]

Hi. I can organize to send a Token2 device for your experiments. Sent you an email

[ashleysommer]

Technical Talk.
KeepassXC uses Botan for all its crypto functionality. And libfido relies on OpenSSL for crypto.
When adding a dependency on libfido for FIDO2 support, this also brings in a dependency on libcrypto (from OpenSSL). Is this okay?
We will have to check if there are any software licensing issues with that.

[michaelblyons]

From @droidmonkey's accidental double post:

We already include libcrypto and libssl libraries to support https in qt

[droidmonkey]

We already include libcrypto and libssl libraries to support https in qt

[ccoenen]

Is there an easy way to check a given hardware token for hmac-secret-support?

I have a SoloKey 1 and a SoloKey 2, is there some way to find out if they support hmac-secret? Their website is pretty light on information, but the firmware-repository of v1 suggests it should also have hmac-secret support. I could not verify it for v2, even though I looked at the indiegogo-page, repository and dev documentation and the trussed project.

[andrewkozlik]

Actually, I implemented credential management via trezorctl, i.e. out-of-band management, long before the CTAP 2.1 spec even appeared, precisely because I saw this problem.

[ashleysommer]

One last info dump here. This time from the Token2 T2F2 FIDO2.1 device:

proto: 0x02
major: 0x02
minor: 0x01
build: 0x00
caps: 0x05 (wink, cbor, msg)
version strings: U2F_V2, FIDO_2_0, FIDO_2_1, FIDO_2_1_PRE
extension strings: credBlob, credProtect, hmac-secret, largeBlobKey, minPinLength
transport strings: usb, nfc
algorithms: es256 (public-key)
aaguid: ab32f0c62239afbbc470d2ef4e254db7
options: rk, up, noplat, noalwaysUv, credMgmt, authnrCfg, noclientPin, largeBlobs, pinUvAuthToken, setMinPINLength, makeCredUvNotRqd, credentialMgmtPreview
certifications: FIDO 1
fwversion: 0x100
maxmsgsiz: 1536
maxcredcntlst: 8
maxcredlen: 96
maxlargeblob: 2048
maxrpids in minpinlen: 6
remaining rk(s): 50
minpinlen: 4
pin protocols: 2, 1
pin retries: undefined
pin change required: false
uv retries: undefined

Some notes:

• This is the first one I've tested that is Full FIDO 2.1 spec compliant and had FIDO Level 1 certification, though this is not particularly useful for this project, its good to test with anyway.
• It is also the first device I've tested that implements Pin Protocol 2, and uses 'pinUvAuthToken', that is a permission's based one-time-token-encrypted communication with the device, for sending PIN and HMAC-secret salt and response.
• In testing hmac-secret, I've found there is a logic bug in the Python-FIDO2 module when using this device, specifically related to the use of Protocol V2. Briefly; if the Assertion is requested with userVerification=True, and hmac-secret extension requested, the script asks the user for their PIN, the hmac-secret salt is encrypted with the shared key, and whole message is protected with the PinAuthTokenm, this works fine. But if Assertion is requested with userVerification=False (this is the default on the Token2) and hmac-secret extension is requested, the hmac-secret is still encrypted with the shared key, but the rest of the message is sent plain CBOR to the device (because no PIN was requested), this causes the device to fail with "PIN_AUTH_INVALID'. The same error does not occur when using PIN Protocol V1. I have created a bug report in Python FIDO2 for it.

[Supermath101]

YubiKey 5 Series does support the hmac-secret extension since firmware version 5.2.

Source: https://support.yubico.com/hc/en-us/articles/360016649319-YubiKey-5-2-3-Enhancements-to-FIDO-2-Support

Edit: here's the output of running fido2-token -I <device>:

proto: 0x02
major: 0x05
minor: 0x04
build: 0x03
caps: 0x05 (wink, cbor, msg)
version strings: U2F_V2, FIDO_2_0, FIDO_2_1_PRE
extension strings: credProtect, hmac-secret
transport strings: nfc, usb
algorithms: es256 (public-key), eddsa (public-key)
aaguid: 2fc0579f811347eab116bb5a8db9202a
options: rk, up, noplat, clientPin, credentialMgmtPreview
fwversion: 0x50403
maxmsgsiz: 1200
maxcredcntlst: 8
maxcredlen: 128
maxlargeblob: 0
minpinlen: 4
pin protocols: 2, 1
pin retries: 8
pin change required: false
uv retries: undefined

[Arbel-arad]

hi, i want to add the results from my authentrend ATkey.pro keys:

proto: 0x02
major: 0x01
minor: 0x00
build: 0x01
caps: 0x05 (wink, cbor, msg)
version strings: U2F_V2, FIDO_2_0, FIDO_2_1, FIDO_2_1_PRE
extension strings: credBlob, credProtect, hmac-secret, largeBlobKey, minPinLength
transport strings: usb
algorithms: es256 (public-key), eddsa (public-key)
aaguid: e1a9618350164f24b55be3ae23614cc6
options: rk, up, uv, noplat, uvAcfg, credMgmt, authnrCfg, bioEnroll, clientPin, largeBlobs, uvBioEnroll, pinUvAuthToken, setMinPINLength, makeCredUvNotRqd, credentialMgmtPreview, userVerificationMgmtPreview, noMcGaPermissionsWithClientPin
fwversion: 0x271f
maxmsgsiz: 2048
maxcredcntlst: 20
maxcredlen: 98
maxlargeblob: 1024
maxrpids in minpinlen: 10
minpinlen: 4
pin protocols: 1, 2
pin retries: 8
pin change required: false
uv retries: 15
uv modality: 0x2 (fingerprint check)
sensor type: 1 (touch)
max samples: 12

with keys supporting fingerprint / internal pin unlock there are really no downsides to using it.
i already have keys enrolled for LUKS2 encrypted drives on my laptop as well and it has been working nicely.

[wy16W2pIilK1xgqN]

Here's my key, showing the result

OnlyKey 3.0.4 Firmware

root@debian:~# fido2-token -I /dev/hidraw2
proto: 0x02
major: 0x00
minor: 0x00
build: 0x00
caps: 0x05 (wink, cbor, msg)
version strings: U2F_V2, FIDO_2_0, FIDO_2_1_PRE
extension strings: credProtect, hmac-secret
aaguid: 79d699df01914b10b9035467e7ce8231
options: rk, up, noplat, credMgmt, clientPin
fwversion: 0x0
maxmsgsiz: 1200
maxcredcntlst: 20
maxcredlen: 256
maxlargeblob: 0
pin protocols: 1
pin retries: 8
pin change required: false
uv retries: undefined

[droidmonkey]

Given the hardware test results above, I am fully supportive of this effort.

[ashleysommer]

Does anyone know how I can get my hands on a TrustKey G310 for testing and development purposes? It is an outlier from others listed above, it is the only FIDO Level 2 certified device, and it is also Citrix certified for whatever that's worth. It has biometrics incorporated (fingerprint), and it is interesting because it uses very different chip platform and architecture (eWBM MS500) than the rest of those listed.

[droidmonkey]

Hit us up at team@keepassxc.org, we can PayPal funds or straight up buy you one and drop ship it. However it looks to be out of stock. It appears to have been replaced by the G320 https://www.trustkeysolutions.com/store/products/g320h/

[roycewilliams]

Does anyone know how I can get my hands on a TrustKey G310 for testing and development purposes?

Happy to loan anything needed from my museum/lab:

https://www.techsolvency.com/mfa/security-keys/

I think the TrustKey G310 is electrically identical to the eWBM FIDO2 (Goldengate 310), which I have.

[ashleysommer]

I think the TrustKey G310 is electrically identical to the eWBM FIDO2 (Goldengate 310)

Yep, I believe you are correct. The eWBM device looks to be the reference design, and the TrustKey is an implementation of that reference design.

That is a very impressive collection you have there, and it's probably more important than many realize to cache and safeguard a library of these devices, not only for testing new software against them but also for history and preservation purposes.

Thank you for the offer to loan any I need. With the two I already have, plus the three that being sent to me by others, I think those five should be enough to test this implementation, and then get a test build into the hands of others who can test it with their own devices.

[hex-m]

By now the list of FIDO Level 2 certified devices grew larger. The Austrian government ID requires that certification an maintains a list of devices.

Sorry, German only, but the only language specific word is "schwarz" which means "black". So only the (newer) black models of the Yubico Security Key NFC are certified.

[ashleysommer]

Next topic: Multiple Security Keys

Its not uncommon for WebAuthn-enabled websites to allow the user to enroll multiple hardware security keys, any of which can be used to unlock their account. For example, some people might have two keys, one at work and one at home, and they need to be able to use any one of those keys as 2FA when logging into their account. This is a documented and supported feature of the WebAuthn spec.

Some might have heard, Apple recently enabled WebAuthn-based 2FA to iCloud accounts. One quirk of the Apple implementation is they require you to have at least two different hardware security keys registered on your account before the feature is activated. This is because they know people are humans, people can lose hardware security keys just as easily as people can forget passwords. Getting locked out of iCloud because you lost your security key is probably a bad time, so a backup device is useful.

The current KeePassXC Yubikey Challenge-Response does not allow for the ability to enroll more than one key. One reason is because the security challenge is rotated every time the db is saved. The challenge can only rotated if the key is currently inserted, so you would need both keys inserted every time the db is saved.
But the more fundamental reason this cannot be implemented is the way KeePassXC uses the device's response in conjunction with the masterkey as input to the KDF to decrypt the DB. That is very good for security, but it means only exactly one key can ever be enrolled at one time.

Its definitely out of scope for the initial implementation, but I think it would be useful to think about how it could be possible to support more than one possible challenge response.

[BryanJacobs]

First off, please don't implement support for using a singular FIDO2 token as a second factor to unlock a KeePass database. If you do that, people are going to enrol their Yubikeys and similar hardware authenticators. Those hardware authenticators don't generally support any means of backing up the key material. So when they lose the authenticator, or it breaks, the users will be permanently locked out of their database. I think the minimal version of this feature needs to allow for 1-of-N authenticator unlocking.

Now, as said above, that's possible! It just requires the general technique of:

1. Generating a random blob to be appended to the master secret for unlocking the database
2. Encrypting the random blob using hmac-secret with an authenticator
3. Storing the encrypted blob in the outer header of the database

The author above says they want the exact same user flow but you can't leave the replace-your-second-factor flow the same because YOU WILL LOCK USERS OUT OF THEIR DATABASE IF YOU DO THAT. There needs to be changes to the screen where you manage second factors.

In other words there are three secrets in play here:

• "Master Secret Part", something appended to the master secret and necessary to unlock the DB
• "Wrapping Key", a key that encrypts the Master Secret Part into the header. There is one of these per FIDO2 authenticator attached, and is not stored in the DB. The Wrapping Key comes from the response an authenticator gives to an hmac-secret extension CTAP operation
• "Authenticator Key", the private key material inside the authenticator itself and used to generate hmac-secret responses.

But there are a few other data objects for a secure implementation:

• A challenge to send to the authenticator. The response to this challenge will be the Wrapping Key. The challenge itself is not secret.
• Salt (IV) used with the Wrapping Key to get the Master Secret Part. Not secret.
• The FIDO2 Credential ID. Not secret.

I would recommend implementing the feature by storing inside the header a value that's a serialized map, AdditionalFactorInfo. This does not require a breaking change to the database foramt, as the outer header already has an additional-items-map member. Inside AdditionalFactorInfo you would store:

• the factor type (yubikey-proprietary-otp, keyfile, fido2). This allows consolidating all the existing implementations and permitting any future ones cleanly
• factor-specific metadata. For a yubikey-proprietary-otp, the key serial. For a keyfile, the bare key file name. For a FIDO2 authenticator, you need the CredID from the authenticator when you enrolled
• challenge to send to the authenticator (for methods that have a challenge - keyfile does not)
• type of Wrapping Key used (note: this would be something like AES128,,not the FIDO2 key type. the Wrapping Key is used by keepass to decrypt the Master Secret Part, and the Wrapping Key is what you get out of the challenge resonse from the authenticator)
• cryptographic salt for deciphering the Master Secret Part. Very important; using the same authenticator twice shouldn't result in the same encrypted blob getting put into the header
• the Master Secret Part, encrypted using the response from the authenticator
• An integer ID for the Master Secret Part this authenticator contributes (to allow optional keyfile+fido2). All factors with the same value for this field are 1-of-N together. Unlocking the database requires one member from each group, and the IDs determine the order in which they're put together into the final master secret. I imagine a simple implementation would have a keyfile be master secret part 1, and any/all FIDO2 authenticators together be master secret part 2. If you want to be really clever you could put "password" as a method in here as master secret part 0, and then you can implement passwordless unlocking...

I would advise using a constant, well-defined FIDO2 RPID that is shared across all implementations of this feature.

With regards to user flows, here are the operations you'd need:

• Unlocking the database flow: code reads the second-factor headers and if present, automatically shows the user what they need to provide to unlock the DB. If there is no header, let the user provide a second factor anyway (for existing databases that don't have the metadata yet)
• For fido2 credentials in the header, take the credential ID stored there, send it to any authenticators on the system. Provide the challenge from the header to the hmac-secret extension. When you get a response, use the response in combination with the stored salt (the response forms an AES key, the salt is the IV) to decrypt the Master Secret Part and append it to the master secret you use to unlock the DB
• When the DB is unlocked, automatically populate the header. For yubikey-proprietary use the database master seed as the challenge like today, so you can unlock the DB the same way using either the header or not. For keyfiles there is no challenge, so just record that the DB needs the keyfile. It might be possible to add a different "keyfile-challenge" method at some point, but why bother? All you get is the ability to do 1-of-keyfile-or-token opening, which is cool but not hugely useful.
• When the DB is unlocked, if the header contains 1-of-N, DO NOT ROTATE THE MASTER SECRET PART as you can't re-encrypt the other authenticators' versions of it. My advice would be to give up the idea of rotating the Master Secret Part, and instead just regenerate the challenge for each authenticator as it's used (in other words, re-encrypt the Master Secret Part in the header using a new challenge). You can do this without requiring the user to boop their key twice, because the FIDO2 standard allows sending two 128-bit challenges in one request. If you use AES128 for the Wrapping Key, you can get the current key and also the future key in one go! Try to unlock the DB using the decrypted Master Secret Part from response1, and if that works use response2 as the new Wrapping Key for that authenticator.
• When the user wants to remove an authenticator, removing it from the header sounds simple, but that won't actually perfectly revoke the authenticator's access because the Master Secret Part would stay the same! I recommend that the "remove authenticator" flow actually be "reset to use this one authenticator I'm providing now" or "remove all authenticators". If you reset to just one authenticator, you can recreate the Master Secret Part. In other words, the flow for revoking an authenticator is "remove all authenticators other than the one I just used to unlock the database". When this happens, delete all fido2 creds from the header, then follow the add-authenticator flow. Reminder: I recommend requiring the user add two authenticators unless they really really know what they're doing.
• When the user wants to add an authenticator, generate a new credential on the FIDO2 token, and create a new challenge. Store the credential ID, the challenge, a new salt, and the encrypted Master Secret Part in the header. If this is the first registered token, create a new Master Secret Part. If it's an additional authenticator, use the existing one.

I hope this is pretty clear. I think I've thought through the security design, the user experience flow, and also how we can migrate from the current state of each app having to independently implement each second factor to one in which the database file says which methods are required, in a backwards-compatible way. What do y'all think?

[ashleysommer]

@BryanJacobs Thanks for your detailed comments and suggestions, that is very valuable.

I have been playing around with some example implementations in Python to begin with (because I am not a C++ developer and Python is faster to iterate prototypes), and I have come to all of the same conclusions you have in regard to supporting multiple FIDO2 keys using an encrypted Intermediate Key, storing the ClientID (not a secret) and Challenge (not a secret) in the header, and even using an additional salt in conjunction with the device's response to encrypt the master key part. Though you have taken the thought process a lot further, with the idea of AdditionalFactorInfo encompassing existing Yubikey Challenge-response metadata and even Keyfiles.

NB, I think there is an issue with the UI/UX of comment threads in Github Discussions. It doesn't show the rest of the history of the conversation under a topic until you click "show previous replies". Under this topic we have discussed a lot of what you suggested, and I agree with a lot of what you have written (though I used different terminology, Intermediate Key rather than MasterKeyPart, DeviceKDFKey rather than WrappingKey, etc).

My main concern is that the unit of work I took on that was "implement hmac-secret support in KeepassXC" has evolved into a major exercise requiring refactoring of all additional factor types and fundamentally changing how KeepassXC creates and unlocks its database, and the user flow. This is much more work than a single volunteer can take on, and way out of scope of my initial planned implementation.

I wonder if this can be done in two steps.

• First, get FIDO2 hmac-secret devices available in KeePassXC as another security factor. Note, this will still use the 'cryptobox' approach, storing multiple ClientIDs in the header as discussed above and allow adding more than one FIDO2 device to unlock the database. We don't want anyone locked out. Existing yubikey challenge-response and keyfiles will be untouched.
• Second, as part of a bigger piece of work by the KeepassXC team and the community, refactor all forms of additional factor security into AdditionalFactorInfo as you suggested, this would be part of a major "2.8" or "3.0" release of KeepassXC. This would require collaborating with the KeepassDX team too, to ensure a consistent implementation.

[BryanJacobs]

@ashleysommer Fact: in order to implement FIDO2 tokens, you either have to use Discoverable Credentials, or you need to store the Credential ID in the unencrypted portion of the database. There isn't a third option.

I don't think it's a huge scope increase to just use a format like I've described above to implement storing the credential ID. The work of consolidating all the existing factors under its umbrella can come afterward, driven by whichever of the kdbx-consuming applications decides to do it first.

Why bother implementing some non-extensible storage of the credential ID when it's almost as easy to do it right the first time?

[ashleysommer]

in order to implement FIDO2 tokens, you either have to use Discoverable Credentials, or you need to store the Credential ID in the unencrypted portion of the database. There isn't a third option.

I agree, I wasn't looking for another option. Storing the Credential ID in the unencrypted header of the database has always been my plan from my very first prototype of this feature.

I don't think it's a huge scope increase to just use a format like I've described above to implement storing the credential ID.

You're right, whichever format/schema we use to store the details in the header results in the same amount of work, and implementing it in the extensible forward-looking manner you describe does make sense. This however requires commitment and support from the KeepassXC team. I am not a member of the team or a maintainer on this project, just a FIDO enthusiast wanting to help out. It is not up to me to make those decisions.

The work of consolidating all the existing factors under its umbrella can come afterward, driven by whichever of the kdbx-consuming applications decides to do it first.

This is what I was referring to as the scope increase, not the metadata schema.

[brokkoli71]

hey, I am curious if this idea turned into something. I have a similar wish for multiple ways of unlocking the database. Is there an ongoing process to implement it?

[Cyanogenbot]

@ashleysommer May I know where this project stranded, I'm curious about its progress :) I read that someone had been working on a Fido platform that could be used

[Supermath101]

From what I've read, the main blocker is #6229. That is a prerequisite to support more than one FIDO2 authenticator (YubiKey, NitroKey, etc.). I believe a single FIDO2 authenticator could be supported with the current spec, but there's little use in that, because you'd be locked out completely as soon as you loose the single FIDO2 authenticator.

[droidmonkey]

We can still implement a wrapped encryption key standard, if FIDO2 is used, with the custom header data. KDBX 5 would be the opportunity to officially migrate to a wrapped key standard instead of the current derived key standard.

[glyph]

Hi @ashleysommer , I just ran across this bug report and I think that describing this key as supporting hmac-secret:

• GoTrust Idem Key

might be inaccurate? At least, this bug report in python-fido2 has not received a response since I filed it: Yubico/python-fido2#183

[BryanJacobs]

I've raised https://github.com/libkeepass/pykeepass/pull/373/files#diff-676d339ebd6081511f5da6080cb3121a7e8f4f2f8ad606d4513a52862e185c53 to support multifactor authentication in pykeepass. I find it easy to protype things with Python code.

Assuming the spec is okay, I'll implement it here soon.

I've implemented a libfido2 compatibility layer in https://github.com/BryanJacobs/FIDOk/ so it can serve as a drop-in replacement. So I think I'll code to libfido2, even though that means more implementation work in keepassxc. Assuming the devs are okay with it I'll use a dlopen to avoid a hard dependency and let the user choose where the FIDO2 library lives. There's a lot of code in implementing a FIDO2 platform...

[BryanJacobs]

I've raised #10311 against this repository.

[BryanJacobs]

I've raised https://gitlab.com/kunzisoft/android-hardware-key-driver/-/merge_requests/12 to let Android devices do hmac-secret stuff with FOSS. After that's merged I'll implement compatible code in KeePassDX.