feat: add biometric key-use authorization (WAL-1183)

Author: szijpeter

gradle/libs.versions.toml

@@ -129,6 +129,7 @@ smiley4-schema-kenerator = "2.7.2"
 # a-sit-plus signum (mobile crypto)
 signum = "3.24.0"
 supreme = "0.15.0"
+androidx-biometric = "1.2.0-alpha05"
 
 [libraries]
 
@@ -365,6 +366,7 @@ kedis = { module = "io.github.domgew:kedis", version.ref = "kedis" }
 signum-indispensable = { module = "at.asitplus.signum:indispensable", version.ref = "signum" }
 signum-indispensable-josef = { module = "at.asitplus.signum:indispensable-josef", version.ref = "signum" }
 signum-supreme = { module = "at.asitplus.signum:supreme", version.ref = "supreme" }
+androidx-biometric = { module = "androidx.biometric:biometric", version.ref = "androidx-biometric" }
 
 ## dev.whyoleg cryptography (Ed25519/secp256k1 on mobile)
 cryptography-core = { module = "dev.whyoleg.cryptography:cryptography-core", version.ref = "whyoleg-cryptography" }

waltid-libraries/crypto/waltid-crypto/build.gradle.kts

@@ -65,6 +65,7 @@ kotlin {
                 named("androidMain") {
                     dependsOn(mobileMain)
                     dependencies {
+                        implementation(identityLibs.androidx.biometric)
                         implementation(identityLibs.kotlinx.coroutines.android)
                         implementation(identityLibs.cryptography.provider.jdk)
                     }

waltid-libraries/crypto/waltid-crypto/src/androidDeviceTest/AndroidManifest.xml

@@ -0,0 +1,7 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <application>
+        <activity
+            android:name="id.walt.crypto.BiometricTestActivity"
+            android:exported="false" />
+    </application>
+</manifest>

waltid-libraries/crypto/waltid-crypto/src/androidDeviceTest/kotlin/id/walt/crypto/BiometricProtectedKeyInteractiveTest.kt

@@ -0,0 +1,93 @@
+package id.walt.crypto
+
+import androidx.fragment.app.FragmentActivity
+import androidx.test.ext.junit.rules.ActivityScenarioRule
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import id.walt.crypto.keys.KeyUseAuthorizationFailure
+import id.walt.crypto.keys.KeyUseAuthorizationPolicy
+import id.walt.crypto.keys.KeyUseAuthorizationException
+import id.walt.crypto.keys.KeyType
+import kotlinx.coroutines.test.runTest
+import org.junit.After
+import org.junit.Ignore
+import org.junit.Rule
+import org.junit.Test
+import org.junit.runner.RunWith
+import kotlin.test.assertEquals
+import kotlin.test.assertFailsWith
+import kotlin.test.assertTrue
+
+/** Minimal host for Signum's BiometricPrompt CryptoObject flow. */
+class BiometricTestActivity : FragmentActivity()
+
+/**
+ * Interactive device coverage for the protected-key acceptance path.
+ *
+ * Run these tests manually on an emulator or device with a strong biometric enrolled. The operator
+ * must authenticate or cancel the operating-system prompt as described by each test; they are
+ * ignored in unattended CI so no test harness can silently substitute device credentials.
+ */
+@RunWith(AndroidJUnit4::class)
+class BiometricProtectedKeyInteractiveTest {
+
+    @get:Rule
+    val activityRule = ActivityScenarioRule(BiometricTestActivity::class.java)
+
+    private val aliases = mutableListOf<String>()
+
+    @After
+    fun cleanup() = runTest {
+        aliases.forEach { alias -> runCatching { AndroidKey.Platform.delete(alias) } }
+    }
+
+    @Ignore("Interactive: authenticate the strong-biometric prompt twice on an enrolled device")
+    @Test
+    fun protectedP256PromptsForEverySigningOperationAndVerifies() = runTest {
+        val activity = activityRule.scenario.withActivity()
+        val alias = "test-biometric-every-use-${System.currentTimeMillis()}".also(aliases::add)
+        val key = AndroidKey.Platform.create(
+            AndroidKey.Options(
+                kid = alias,
+                keyType = KeyType.secp256r1,
+                keyUseAuthorizationPolicy = KeyUseAuthorizationPolicy.BiometricCurrentSet,
+                interactionContext = activity,
+            )
+        )
+        val plaintext = "authorize every key use".encodeToByteArray()
+
+        val first = key.signRaw(plaintext)
+        val second = key.signRaw(plaintext)
+
+        assertTrue(first.isNotEmpty())
+        assertTrue(second.isNotEmpty())
+        assertTrue(key.verifyRaw(first, plaintext).isSuccess)
+        assertTrue(key.verifyRaw(second, plaintext).isSuccess)
+    }
+
+    @Ignore("Interactive: cancel the strong-biometric prompt on an enrolled device")
+    @Test
+    fun cancelledPromptProducesNoSignatureAndStableFailure() = runTest {
+        val activity = activityRule.scenario.withActivity()
+        val alias = "test-biometric-cancel-${System.currentTimeMillis()}".also(aliases::add)
+        val key = AndroidKey.Platform.create(
+            AndroidKey.Options(
+                kid = alias,
+                keyType = KeyType.secp256r1,
+                keyUseAuthorizationPolicy = KeyUseAuthorizationPolicy.BiometricCurrentSet,
+                interactionContext = activity,
+            )
+        )
+
+        val failure = assertFailsWith<KeyUseAuthorizationException> {
+            key.signRaw("must not be signed".encodeToByteArray())
+        }
+
+        assertEquals(KeyUseAuthorizationFailure.AuthorizationFailed, failure.failure)
+    }
+
+    private fun <A : FragmentActivity> androidx.test.core.app.ActivityScenario<A>.withActivity(): A {
+        lateinit var activity: A
+        onActivity { activity = it }
+        return activity
+    }
+}

waltid-libraries/crypto/waltid-crypto/src/androidMain/kotlin/id/walt/crypto/AndroidKey.kt

@@ -1,49 +1,78 @@
 package id.walt.crypto
 
+import android.os.Build
+import android.security.keystore.KeyPermanentlyInvalidatedException
+import android.security.keystore.KeyProperties
+import androidx.biometric.BiometricManager.Authenticators.BIOMETRIC_STRONG
+import androidx.fragment.app.FragmentActivity
 import at.asitplus.signum.indispensable.josef.io.joseCompliantSerializer
 import at.asitplus.signum.indispensable.josef.toJsonWebKey
 import at.asitplus.signum.supreme.SignatureResult
+import at.asitplus.signum.supreme.os.AndroidKeystoreSigner
 import at.asitplus.signum.supreme.os.AndroidKeyStoreProvider
+import at.asitplus.signum.supreme.os.needsAuthentication
+import at.asitplus.signum.supreme.os.needsAuthenticationForEveryUse
 import dev.whyoleg.cryptography.CryptographyProvider
 import dev.whyoleg.cryptography.providers.jdk.JDK
 import id.walt.crypto.keys.JwkKeyMeta
 import id.walt.crypto.keys.Key
+import id.walt.crypto.keys.KeyHardwareBacking
 import id.walt.crypto.keys.KeyMeta
 import id.walt.crypto.keys.KeyType
+import id.walt.crypto.keys.KeyUseAuthorizationAware
+import id.walt.crypto.keys.KeyUseAuthorizationException
+import id.walt.crypto.keys.KeyUseAuthorizationFailure
+import id.walt.crypto.keys.KeyUseAuthorizationPolicy
+import id.walt.crypto.keys.KeyUseAuthorizationPrompt
 import kotlinx.serialization.json.Json
 import kotlinx.serialization.json.JsonElement
 import kotlinx.serialization.json.JsonObject
 import org.bouncycastle.jce.provider.BouncyCastleProvider
 import kotlin.io.encoding.Base64
+import kotlin.time.Duration
 import kotlin.uuid.Uuid
 
 sealed class AndroidKey : Key() {
 
     class Options(
         val kid: String = Uuid.random().toString(),
         val keyType: KeyType,
-    )
+        val keyUseAuthorizationPolicy: KeyUseAuthorizationPolicy = KeyUseAuthorizationPolicy.None,
+        val authorizationPrompt: KeyUseAuthorizationPrompt = KeyUseAuthorizationPrompt(),
+        interactionContext: Any? = null,
+    ) {
+        internal val interactionContext: FragmentActivity? = interactionContext as? FragmentActivity
+    }
 
     class Platform internal constructor(
         private val options: Options,
         override val hasPrivateKey: Boolean = true,
-    ) : AndroidKey() {
+    ) : AndroidKey(), KeyUseAuthorizationAware {
 
         companion object {
             suspend fun create(options: Options): Platform {
+                options.requireSupportedProtectedCombination()
                 when (val curve = options.keyType.toPlatformKeyStoreCurve()) {
                     null -> AndroidKeyStoreProvider.createSigningKey(options.kid) {
                         rsa { }
+                        if (options.keyUseAuthorizationPolicy == KeyUseAuthorizationPolicy.BiometricCurrentSet) {
+                            configureBiometricCurrentSet(options)
+                        }
                     }.getOrThrow()
                     else -> AndroidKeyStoreProvider.createSigningKey(options.kid) {
                         ec { this.curve = curve }
+                        if (options.keyUseAuthorizationPolicy == KeyUseAuthorizationPolicy.BiometricCurrentSet) {
+                            configureBiometricCurrentSet(options)
+                        }
                     }.getOrThrow()
                 }
                 return Platform(options)
             }
 
             suspend fun load(options: Options): Platform {
-                AndroidKeyStoreProvider.getSignerForKey(options.kid).getOrThrow()
+                options.requireSupportedProtectedCombination()
+                runCatching { options.loadSigner() }
+                    .getOrElse { throw options.mapPlatformFailure(it) }
                 return Platform(options)
             }
 
@@ -53,8 +82,23 @@ sealed class AndroidKey : Key() {
         }
 
         override val keyType get() = options.keyType
-
-        private suspend fun signer() = AndroidKeyStoreProvider.getSignerForKey(options.kid).getOrThrow()
+        override val keyUseAuthorizationPolicy get() = options.keyUseAuthorizationPolicy
+        override val isPlatformBacked: Boolean = true
+
+        private suspend fun signer(): AndroidKeystoreSigner = runCatching { options.loadSigner() }
+            .getOrElse { throw options.mapPlatformFailure(it) }
+
+        private fun requireSigningInteractionContext() {
+            if (
+                options.keyUseAuthorizationPolicy == KeyUseAuthorizationPolicy.BiometricCurrentSet &&
+                options.interactionContext == null
+            ) {
+                throw KeyUseAuthorizationException(
+                    failure = KeyUseAuthorizationFailure.InteractionContextUnavailable,
+                    message = "A FragmentActivity interaction context is required for biometric key use",
+                )
+            }
+        }
 
         override suspend fun getKeyId(): String = options.kid
 
@@ -76,15 +120,24 @@ sealed class AndroidKey : Key() {
 
         override suspend fun signRaw(plaintext: ByteArray, customSignatureAlgorithm: String?): ByteArray {
             check(hasPrivateKey) { "Only private key can do signing." }
-            val result = signer().sign(plaintext)
-            check(result is SignatureResult.Success) { "Signing failed: $result" }
-            return result.signature.rawByteArray
+            requireSigningInteractionContext()
+            return signer().sign(plaintext).mapPlatformFailure(options).signatureBytesOrThrow(
+                protectedKeyUse = options.keyUseAuthorizationPolicy != KeyUseAuthorizationPolicy.None,
+            )
         }
 
         override suspend fun signJws(plaintext: ByteArray, headers: Map<String, JsonElement>): String {
             check(hasPrivateKey) { "Only private key can do signing." }
+            requireSigningInteractionContext()
             val signer = signer()
-            return signJwsWithPlatformSigner(options.keyType, plaintext, headers) { data -> signer.sign(data) }
+            return signJwsWithPlatformSigner(
+                options.keyType,
+                plaintext,
+                headers,
+                protectedKeyUse = options.keyUseAuthorizationPolicy != KeyUseAuthorizationPolicy.None,
+            ) { data ->
+                signer.sign(data).mapPlatformFailure(options)
+            }
         }
 
         override suspend fun verifyRaw(
@@ -102,6 +155,23 @@ sealed class AndroidKey : Key() {
         override suspend fun getPublicKey(): Key = Platform(options, hasPrivateKey = false)
         override suspend fun getPublicKeyRepresentation(): ByteArray = signer().publicKey.encodeToTlv().derEncoded
         override suspend fun getMeta(): KeyMeta = JwkKeyMeta(getKeyId())
+        @Suppress("DEPRECATION")
+        override suspend fun effectiveHardwareBacking(): KeyHardwareBacking {
+            val keyInfo = signer().keyInfo
+            return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+                when (keyInfo.securityLevel) {
+                    KeyProperties.SECURITY_LEVEL_SOFTWARE -> KeyHardwareBacking.Software
+                    KeyProperties.SECURITY_LEVEL_TRUSTED_ENVIRONMENT -> KeyHardwareBacking.TrustedEnvironment
+                    KeyProperties.SECURITY_LEVEL_STRONGBOX -> KeyHardwareBacking.StrongBox
+                    KeyProperties.SECURITY_LEVEL_UNKNOWN_SECURE -> KeyHardwareBacking.SecureHardware
+                    else -> KeyHardwareBacking.Unknown
+                }
+            } else if (keyInfo.isInsideSecureHardware) {
+                KeyHardwareBacking.SecureHardware
+            } else {
+                KeyHardwareBacking.Software
+            }
+        }
         override suspend fun deleteKey(): Boolean = runCatching {
             AndroidKeyStoreProvider.deleteSigningKey(options.kid).getOrThrow()
         }.isSuccess
@@ -159,3 +229,93 @@ sealed class AndroidKey : Key() {
         override suspend fun deleteKey(): Boolean = delegate.deleteKey()
     }
 }
+
+private fun at.asitplus.signum.supreme.os.AndroidSigningKeyConfiguration.configureBiometricCurrentSet(
+    options: AndroidKey.Options,
+) {
+    hardware {
+        protection {
+            factors {
+                biometry = true
+                biometryWithNewFactors = false
+                deviceLock = false
+            }
+            timeout = Duration.ZERO
+        }
+    }
+    signer {
+        unlockPrompt {
+            message = options.authorizationPrompt.message
+            cancelText = options.authorizationPrompt.cancelText
+            allowedAuthenticators = BIOMETRIC_STRONG
+            options.interactionContext?.let { activity = it }
+        }
+    }
+}
+
+private suspend fun AndroidKey.Options.loadSigner(): AndroidKeystoreSigner {
+    val signer = AndroidKeyStoreProvider.getSignerForKey(kid) {
+        unlockPrompt {
+            message = authorizationPrompt.message
+            cancelText = authorizationPrompt.cancelText
+            if (keyUseAuthorizationPolicy == KeyUseAuthorizationPolicy.BiometricCurrentSet) {
+                allowedAuthenticators = BIOMETRIC_STRONG
+            }
+            interactionContext?.let { activity = it }
+        }
+    }.getOrThrow()
+    if (keyUseAuthorizationPolicy == KeyUseAuthorizationPolicy.BiometricCurrentSet) {
+        val biometricOnly = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            signer.keyInfo.userAuthenticationType == KeyProperties.AUTH_BIOMETRIC_STRONG
+        } else {
+            true
+        }
+        if (
+            !signer.needsAuthentication ||
+            !signer.needsAuthenticationForEveryUse ||
+            !signer.keyInfo.isInvalidatedByBiometricEnrollment ||
+            !biometricOnly
+        ) {
+            throw KeyUseAuthorizationException(
+                failure = KeyUseAuthorizationFailure.ProtectedKeyInvalidated,
+                message = "The stored key does not enforce biometric current-set authorization for every use",
+            )
+        }
+    }
+    return signer
+}
+
+private fun AndroidKey.Options.requireSupportedProtectedCombination() {
+    if (
+        keyUseAuthorizationPolicy == KeyUseAuthorizationPolicy.BiometricCurrentSet &&
+        keyType != KeyType.secp256r1
+    ) {
+        throw KeyUseAuthorizationException(
+            failure = KeyUseAuthorizationFailure.UnsupportedCombination,
+            message = "Android biometric current-set authorization is supported only for secp256r1 keys",
+        )
+    }
+}
+
+private fun AndroidKey.Options.mapPlatformFailure(throwable: Throwable): Throwable {
+    if (keyUseAuthorizationPolicy == KeyUseAuthorizationPolicy.None) return throwable
+    val causes = generateSequence(throwable as Throwable?) { it.cause }.toList()
+    return when {
+        causes.any { it is KeyPermanentlyInvalidatedException } -> KeyUseAuthorizationException(
+            failure = KeyUseAuthorizationFailure.ProtectedKeyInvalidated,
+            message = "The protected key was invalidated",
+            cause = throwable,
+        )
+        causes.any { it is NoSuchElementException } -> KeyUseAuthorizationException(
+            failure = KeyUseAuthorizationFailure.ProtectedKeyMissing,
+            message = "The protected key is missing",
+            cause = throwable,
+        )
+        else -> throwable
+    }
+}
+
+private fun SignatureResult<*>.mapPlatformFailure(options: AndroidKey.Options): SignatureResult<*> = when (this) {
+    is SignatureResult.Error -> SignatureResult.Error(options.mapPlatformFailure(exception))
+    else -> this
+}