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.

[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

[My1]

Interesting that your devices do not list algorithms. I am planning to default to ES256 algorithm in this implementation in KeePassXC, it should be universally supported on all FIDO2 devices, but it would be good to see what algorithms others have available.

I dont think you need to care about the algo at all really as you dont really need to verify the signatures of the FIDO Devices anyway as they are pretty much useless. the only thing we care about is HMAC-secret which is a completely blackbox thing anyway, you give it a value and it spits out another.

[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.

[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?

[My1]

while this is true, we have precedent with TOTP. this started as a plugin in KeePass and pretty much all apps (including KeePassXC) agreed to just run with it, using the same custom fields in the same way to stay compatible with each other.

you sure it was TOTP and not HOTP? because TOTP is practically impossible to use for decryption as the otp rotates with time.

[michaelblyons]

@My1 They were talking there about saving TOTP credentials in the database, not about decrypting the database. The question was whether a decryption mechanism that isn't already part of the standard would be adopted, and the TOTP plugin was used as an example.

[My1]

oh okay, sorry I wasnt expecting moving the topic even for a comparison to a thing inside the database, I didnt even know it was originally a plugin, lol

[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.

[tmo1]

I was interested in FIDO2 hmac-secret KeePassXC database unlocking, and since there has been no (public?) progress on this in nearly a year, I implemented my own solution as a standalone tool. Actually, the code began as a KeePassXC specific tool but quickly evolved into a general purpose tool.

I present FidoVault: A tool to control access to secrets via symmetric encryption and decryption using hardware FIDO2 keys. See its README, but briefly, once a FidoVault is configured with one or more FIDO2 keys, it can be used to unlock KeePassXC databases like this:

$ fidovault.py -v <vaultname> | keepassxc --pw-stdin /path/to/database.kdbx

or:

$ fidovault.py -v <vaultname> | xargs qdbus org.keepassxc.KeePassXC.MainWindow /keepassxc org.keepassxc.KeePassXC.MainWindow.openDatabase /path/to/database.kdbx

Feedback welcome (and thanks much to the KeePassXC developers for this great software).

[droidmonkey]

Cool! Progress is here: #10311

[glyph]

That is neat! I built a similar tool — https://github.com/glyph/tokenring — but I never thought to hook it up to keepassxc.

Now that I'm thinking about a full unlock of a generalized password vault, rather than the "selective access to a few API keys" use-case, I am now considering some gaps in the threat model that I should perhaps document :). (In short, if you use your fido2 token this way, you should really make sure to set a PIN on it, because the touch sensor isn't a biometric.)

[tmo1]

Cool! Progress is here: #10311

Thanks!

(In short, if you use your fido2 token this way, you should really make sure to set a PIN on it, because the touch sensor isn't a biometric.)

I don't have a PIN set, but generally use my token as a second factor along with a passphrase.

[My1]

i think prior to 5.7 they only had CTAP2.0 and now it's the latest 2.1

not quite, iirc 5.3.7 or something added CTAP2.1, which was pretty massive as Yubikey prior to like 5.7 only stored 25 resident which is kinda counter intuitive when you cannot delete any of them without nuking the whole damn thing and need to set up all accounts again. what is this, a CDRW?

[p1gp1g]

when you cannot delete any of them without nuking the whole damn thing and need to set up all accounts again

what do you mean ? It is possible to delete a single key

[My1]

when you cannot delete any of them without nuking the whole damn thing and need to set up all accounts again

what do you mean ? It is possible to delete a single key

It is on ctap2.1 keys (yubikeys with fw of about 5.3.7.

The original ctap2.0 standard didn't have an operation to. Delete individual ones.

[tanriol]

According to Yubico support, listing and deleting individual resident keys is possible with 5.2+ firmware. At least some of these keys have version strings of U2F_V2, FIDO_2_0, FIDO_2_1_PRE.

[My1]

Then it was 5.2, sry but the specific version doesn't matter when you have a yubi5 that's older than that (i have one)

[hex-m]

Not sure if I understand the differences, but there is also WebAuthn PRF (which uses hmac-secret internally). This was implemented in age-encryption: https://words.filippo.io/passkey-encryption/