HMAC Secret implementation guide

1,724 views
Skip to first unread message

James Walker

unread,
May 13, 2019, 4:22:39 PM5/13/19
to FIDO Dev (fido-dev)
Hi there,

I'm looking into creating a toy implementation of HMAC secret, defined as an extension to CTAP here, and was wondering if anyone knew of any existing implementations/guides I could use for reference? I think I'll end up using it in some sort of offline note manager, but the end app isn't a big concern, I just want to be able to derive a symmetric shared-secret.

I've spent a fair time researching and have yet to find anything better than the explanation in the spec, which unfortunately isn't enough help for my fairly limited skills.

Any help would be much appreciated :)

Emanuele Cesena

unread,
May 13, 2019, 4:35:33 PM5/13/19
to James Walker, FIDO Dev (fido-dev)
This is our PR: https://github.com/solokeys/solo/pull/149

Hope it helps!


--
You received this message because you are subscribed to the Google Groups "FIDO Dev (fido-dev)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to fido-dev+u...@fidoalliance.org.
To view this discussion on the web visit https://groups.google.com/a/fidoalliance.org/d/msgid/fido-dev/b5342824-cdec-4fd1-bb16-9ef892cd5ccf%40fidoalliance.org.

-- 
Emanuele Cesena <e...@solokeys.com>

Il corpo non ha ideali




Luke Walker

unread,
May 14, 2019, 2:32:25 AM5/14/19
to Emanuele Cesena, James Walker, FIDO Dev (fido-dev)
Hi James,

Yubico's libfido2 examples implement the hmac-secret.
- The 'cred' example has a -h option to enable the hmac-secret extension on a credential
- The 'assert' example has a -s option to request a hmac-secret from the authenticator (32 bytes for a single salt, 64 bytes for two salts). Use the -h option to store the secret in a file.

Happy coding!

To view this discussion on the web visit https://groups.google.com/a/fidoalliance.org/d/msgid/fido-dev/A0E12D49-7BAA-4460-8663-A0F947042B41%40gmail.com.


--

Luke Walker

Manager - Developer Program | Yubico

Phone: +1 206 880 3998


James Walker

unread,
May 14, 2019, 10:43:39 AM5/14/19
to FIDO Dev (fido-dev), emanuel...@gmail.com, max...@yahoo.co.uk
Hi Luke,

Thanks for your reply! I've installed the library and its dependencies (I think) but am unsure as to how to use the command line tools in the library - could you please describe a in a little bit more detail how to use cred and assert - apologies for the noob question but everyone's gotta start somewhere.

Thanks in advance!

On Tuesday, 14 May 2019 07:32:25 UTC+1, Luke wrote:
Hi James,

Yubico's libfido2 examples implement the hmac-secret.
- The 'cred' example has a -h option to enable the hmac-secret extension on a credential
- The 'assert' example has a -s option to request a hmac-secret from the authenticator (32 bytes for a single salt, 64 bytes for two salts). Use the -h option to store the secret in a file.

Happy coding!

On Mon, May 13, 2019 at 1:35 PM Emanuele Cesena <emanuel...@gmail.com> wrote:
This is our PR: https://github.com/solokeys/solo/pull/149

Hope it helps!
On May 13, 2019, at 1:22 PM, 'James Walker' via FIDO Dev (fido-dev) <fido...@fidoalliance.org> wrote:

Hi there,

I'm looking into creating a toy implementation of HMAC secret, defined as an extension to CTAP here, and was wondering if anyone knew of any existing implementations/guides I could use for reference? I think I'll end up using it in some sort of offline note manager, but the end app isn't a big concern, I just want to be able to derive a symmetric shared-secret.

I've spent a fair time researching and have yet to find anything better than the explanation in the spec, which unfortunately isn't enough help for my fairly limited skills.

Any help would be much appreciated :)

--
You received this message because you are subscribed to the Google Groups "FIDO Dev (fido-dev)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to fido...@fidoalliance.org.

-- 
Emanuele Cesena <e...@solokeys.com>

Il corpo non ha ideali




--
You received this message because you are subscribed to the Google Groups "FIDO Dev (fido-dev)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to fido...@fidoalliance.org.

Luke Walker

unread,
May 14, 2019, 3:43:40 PM5/14/19
to James Walker, FIDO Dev (fido-dev), Emanuele Cesena
Hi James,

Sure thing. The examples are command line executables which demonstrate how to use various capabilities of the library.  They need to be compiled into executables. Are you able to build libfido2 from source? 

Here are my instructions from about 9 months ago.

If you can already build from source then skip my VM. I created a vagrant virtualbox Ubuntu VM. I haven't used the VM since, so hopefully it and these instructions still work.
- Note: I opened the VirtualBox UI to attach my USB security key to the guest OS
- Login with the username/password: vagrant/vagrant

Get Started
1. Plug in your security key and run manifest to find the security key device
2. Run info <device> to confirm that the extension strings attribute shows that hmac-secret is supported


Create a credential

The next step is to generate a new public key credential on the security key. Running cred will create an asymmetric key pair on the YubiKey. The private key never leaves the hardware. Only public key is disclosed to the platform. Specify the ‘-k’ option to retrieve the public key. By default, new credentials are not created with the hmac-secret enabled. So we must to specify the ‘-h’ option to enable the feature. Create a resident credential by specifying the ‘-r’ option. If a PIN has been set on the security key, then specify the PIN with the ‘-P’ option.

  1. Run cred -r -h -k /tmp/pubkey <device> to create a new public key credential with the hmac-secret enabled. The security key will blink, tap to give user consent to perform the operation.

2. Run cat /tmp/pubkey to view the public key.

Create a salt

A salt is your half of the secret. In this example, we will use 32 bytes of pseudorandom data. The credential on the YubiKey has the other half of the secret. Optionally, you can pass in a second salt if you want to output two hmac-secrets (e.g. for rotating secrets). In that case you would pass in 64 bytes of data. The first sequence of 32 bytes are the first salt. The second sequence of 32 bytes are the second salt. In this example we are only going to generate one salt.

1. Run dd if=dev/urandom of=/tmp/salt bs=1 count=32 to generate the salt.
2. Run base64 /tmp/salt to view the salt.

Retrieve the shared symmetric secret

In order to retrieve the hmac-secret shared between the client and the security key you must first get an assertion for the corresponding credential that was generated earlier. The client verifies the obtained assertion using the public key. Specify the ‘-p’ option to request user presence. Specify the ‘-h’ option to output the shared symmetric secret. Specify the ‘-s’ option to input the salt. If a PIN has been set on the device, specify the PIN with the ‘-P’ option.

  1. Run ./assert -p -h /tmp/secret -s /tmp/salt /tmp/pubkey <device> to retrieve the hmac-secrets. The security key will blink, tap the key to give user consent to perform the operation.

2. Run base64 /tmp/secret to view the hmac-secret

Putting it all together

Use the hmac-secret to encrypt and decrypt a message.

  1. Use the secret to encrypt a message
    echo the quick brown fox jumps over the lazy dog | openssl enc -aes256 -a -e -kfile /tmp/secret > /tmp/token

  2. Run cat /tmp/token to view the encrypted data

  3. Run cat /tmp/token | openssl enc -aes256 -a -d -kfile /tmp/secret to decrypt the token

the quick brown fox jumps over the lazy dog


Note: Instead of saving the secret to a file like the above example, you could prompt the user to insert their key and get the secret at encryption and decryption time.



To unsubscribe from this group and stop receiving emails from it, send an email to fido-dev+u...@fidoalliance.org.
To view this discussion on the web visit https://groups.google.com/a/fidoalliance.org/d/msgid/fido-dev/8011922f-3305-48f1-8933-c1559ea6bade%40fidoalliance.org.

Kobus Grobler

unread,
May 15, 2019, 6:38:15 AM5/15/19
to FIDO Dev (fido-dev)
Hi Luke

Nice write up.

Just a general observation and question with regards to the FIDO2 hmac-secret extension and it's use case.
In it's essence, it provides a way of securely exchanging a hash of a secret (with salt) between the FIDO client and authenticator.

I know this is an example, but the exchanged secret should, from my point of view, rather not be used for encryption (at least not of long lived data). 
The reason I say this is that once it is exchanged the secret sits in the insecure memory of the FIDO client (from where it is passed on to possibly the RP).
Would be nice if there was a defined general purpose extension to encrypt data on the authenticator itself - but then I guess we move into the domain of the HSM and PKCS11 api.

The only use case I currently see is for verification of data ownership (like passwords etc...) by using the hash of the data as salt and matching the result with a previously exchanged hmac-secret.

So my question is who is actually using the hmac-secret extension and for what purpose?

Emanuele Cesena

unread,
May 15, 2019, 11:09:59 AM5/15/19
to Kobus Grobler, FIDO Dev (fido-dev)
To my knowledge the only application using it is windows hello.


--
Emanuele Cesena
emanuel...@gmail.com

Check out my new security key: https://solokeys.com
Reply all
Reply to author
Forward
0 new messages