Implement HMAC-Secret extension #5

BryanJacobs · 2022-09-03T15:30:56Z

This adds the ability for Android apps (not web pages) to use the
hwsecurity library to:

register credentials with the FIDO2 hmac-secret extension enabled
pass salts in to authenticators with getAssertion calls
retrieve decrypted results back from the authenticator

It also lays the basic groundwork for supporting PIN Protocol 2,
defined as a mandatory part of FIDO2 CTAP2.1.

Example usage for create:

        val extensionParams = listOf(
            ExtensionParameter.create(
                Common.HMAC_SECRET_EXTENSION,
                BooleanExtensionParameterValue.create(true)
            )
        )

        val registerRequest = PublicKeyCredentialCreationOptions.create(
            [...],
            extensionParams
        )

Example usage for getAssertion:

private fun showAuthenticateDialog(hmacSalt1: ByteArray, hmacSalt2: ByteArray?) {
        val extensionParams = if (hmacSalts == null) null else listOf(
            ExtensionParameter.create(
                Common.HMAC_SECRET_EXTENSION,
                HmacSecretExtensionParameterValue.create(
                    hmacSalt1,
                    hmacSalt2
                )
            )
        )

        val authenticateRequest = PublicKeyCredentialRequestOptions.create(
           [...],
            extensionParams
        )

[...]

    override fun onGetAssertionResponse(publicKeyCredential: PublicKeyCredential) {
        val res = publicKeyCredential.response() as AuthenticatorAssertionResponse
        
        val hmacSecretReply: ByteArray = res.hmacSecretData()
    }

This adds the ability for Android apps (not web pages) to use the hwsecurity library to: - register credentials with the FIDO2 hmac-secret extension enabled - pass salts in to authenticators with getAssertion calls - retrieve decrypted results back from the authenticator It also lays the basic groundwork for supporting PIN Protocol 2, defined as a mandatory part of FIDO2 CTAP2.1.

BryanJacobs · 2022-09-03T15:31:38Z

build.gradle

@@ -27,5 +27,5 @@ allprojects {

 ext {
    compileSdkVersion = 29
-    hwSdkVersionName = '4.4.0'
+    hwSdkVersionName = '4.5.0'


This change doesn't break any non-"internal" classes, per se, but it does add fields and features.

BryanJacobs · 2022-09-03T15:32:25Z

hwsecurity/fido2/src/main/java/de/cotech/hw/fido2/domain/ExtensionParameter.java

+import com.google.auto.value.AutoValue;
+
+@AutoValue
+public abstract class ExtensionParameter implements Parcelable {


This class (and change) lays the groundwork for supporting other extensions such as CredProtect, mandatory in CTAP2.1 and quite desirable for an application using resident keys.

BryanJacobs · 2022-09-03T15:33:17Z

hwsecurity/fido2/src/main/java/de/cotech/hw/fido2/domain/HmacSecretExtensionParameterValue.java

+    @SuppressWarnings("mutable")
+    public abstract byte[] salt2();
+
+    public static HmacSecretExtensionParameterValue create(byte[] salt1, @Nullable byte[] salt2) {


These are the unencrypted values so they must always be 32 bytes long - even when PIN Protocol 2 will add a 16-byte IV to the front, that happens around these values and not within them.

BryanJacobs · 2022-09-03T15:34:10Z

hwsecurity/fido2/src/main/java/de/cotech/hw/fido2/domain/create/AuthenticatorData.java

@@ -69,7 +70,7 @@ public abstract class AuthenticatorData {
    // extensions 	variable (if present) 	Extension-defined authenticator data. This is a CBOR [RFC7049] map with extension identifiers as keys, and authenticator extension outputs as values. See §9 WebAuthn Extensions for details.
    @Nullable
    @SuppressWarnings("mutable")
-    public abstract byte[] extensions();
+    public abstract Map extensions();


It's not useful to have the extensions type (never actually exposed in app-visible objects) be a byte array because some of its contents depend on authenticator state objects like the shared secret :-(.

BryanJacobs · 2022-09-03T15:34:54Z

hwsecurity/fido2/src/main/java/de/cotech/hw/fido2/internal/ctap2/Ctap2CborSerializer.java

+        // Handle parameters which require assertion-specific data here
+        Object value = extensionParameters.value();
+        if (value instanceof HmacSecretExtensionParameterValue) {
+            HmacSecretExtensionParameterValue param = (HmacSecretExtensionParameterValue) value;


Significant change here: serialize hmac-secret extension parameters to the CTAP2 CBOR request.

BryanJacobs · 2022-09-03T15:35:52Z

.../hw/fido2/internal/ctap2/commands/getAssertion/AuthenticatorGetAssertionResponseFactory.java

+                    throw new IOException("hmac-secret response is not a byte string");
+                }
+                byte[] hmacSecretBytes = ((ByteString) hmacSecretValue).getBytes();
+                decryptedHmacSecretValue = authenticatorGetAssertion.pinToken().decrypt(hmacSecretBytes);


Return side of the hmac-secret getAssertion flow, and the reason why I did all this wiring of the PinToken: the hmac-secret response value must be decrypted using the platform<->authenticator shared secret in order to be useful.

That's done here in the response factory.

BryanJacobs · 2022-09-03T15:37:22Z

hwsecurity/fido2/src/main/java/de/cotech/hw/fido2/internal/pinauth/PinProtocol.java

+
+import de.cotech.hw.fido2.internal.Fido2AppletConnection;
+
+public interface PinProtocol {


The changes here aren't, strictly speaking, necessary for hmac-secret support. But if you ever want to implement the vastly superior CTAP2.1 PIN Protocol 2, you're going to need changes like these to do so.

I've used the CTAP2.1 terminology for the PIN operations - authenticate, encrypt, decrypt - instead of the implementation-specific ones that were here before.

BryanJacobs commented Sep 3, 2022

View reviewed changes

ashleysommer mentioned this pull request Jun 9, 2023

Add support for hmac-secret FIDO2 extension Kunzisoft/KeePassDX#304

Open

AndyScherzinger mentioned this pull request Dec 8, 2023

Error when installing dev release 3.27.0 nextcloud/android#12253

Closed

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Implement HMAC-Secret extension #5

Implement HMAC-Secret extension #5

BryanJacobs commented Sep 3, 2022 •

edited

Loading

BryanJacobs Sep 3, 2022

BryanJacobs Sep 3, 2022

BryanJacobs Sep 3, 2022

BryanJacobs Sep 3, 2022

BryanJacobs Sep 3, 2022

BryanJacobs Sep 3, 2022

BryanJacobs Sep 3, 2022


		import de.cotech.hw.fido2.internal.Fido2AppletConnection;

		public interface PinProtocol {

Implement HMAC-Secret extension #5

Are you sure you want to change the base?

Implement HMAC-Secret extension #5

Conversation

BryanJacobs commented Sep 3, 2022 • edited Loading

BryanJacobs Sep 3, 2022

Choose a reason for hiding this comment

BryanJacobs Sep 3, 2022

Choose a reason for hiding this comment

BryanJacobs Sep 3, 2022

Choose a reason for hiding this comment

BryanJacobs Sep 3, 2022

Choose a reason for hiding this comment

BryanJacobs Sep 3, 2022

Choose a reason for hiding this comment

BryanJacobs Sep 3, 2022

Choose a reason for hiding this comment

BryanJacobs Sep 3, 2022

Choose a reason for hiding this comment

BryanJacobs commented Sep 3, 2022 •

edited

Loading