No public description

PiperOrigin-RevId: 791371467

Author: suzannajiwani

README.md

@@ -12,8 +12,8 @@ val verifier = Verifier(
   { Instant.now() }                               // Time source
 )
 
-// Verify an attestation certificate chain with challenge
-val result = verifier.verify(certificateChain, challenge)
+// Verify an attestation certificate chain
+val result = verifier.verify(certificateChain)
 
 // Handle the verification result
 when (result) {
@@ -32,6 +32,22 @@ when (result) {
 }
 ```
 
+If there is additional verification you'd like to perform on the challenge
+associated with the attestation certificate chain, pass in a `ChallengeChecker`
+when verifying. For example, if you expect the challenge to be equal to
+"challenge123", then usage would look like
+
+```kotlin
+// Create a ChallengeChecker
+val challengeChecker = ChallengeMatcher("challenge123")
+
+// Verify an attestation certificate chain with the checker
+val result = verifier.verify(certificateChain, challengeChecker)
+```
+
+If the implementations in challengecheckers/ don't fit your needs, simply extend
+the `ChallengeChecker` interface.
+
 ## Building
 
 ```bash

src/main/kotlin/ChallengeChecker.kt

@@ -0,0 +1,14 @@
+package com.android.keyattestation.verifier
+
+import com.google.protobuf.ByteString
+
+/** An interface to handle checking validity of challenges. */
+interface ChallengeChecker {
+  /**
+   * Checks the given challenge for validity.
+   *
+   * @param challenge The challenge being check.
+   * @return True if the challenge is valid, else false.
+   */
+  fun checkChallenge(challenge: ByteString): Boolean
+}

src/main/kotlin/Verifier.kt

@@ -22,7 +22,6 @@ import com.android.keyattestation.verifier.provider.ProvisioningMethod
 import com.android.keyattestation.verifier.provider.RevocationChecker
 import com.google.errorprone.annotations.ThreadSafe
 import com.google.protobuf.ByteString
-import java.nio.ByteBuffer
 import java.security.PublicKey
 import java.security.Security
 import java.security.cert.CertPathValidator
@@ -73,26 +72,42 @@ open class Verifier(
     Security.addProvider(KeyAttestationProvider())
   }
 
-  fun verify(chain: List<X509Certificate>, challenge: ByteArray? = null): VerificationResult {
+  /**
+   * Verifies an Android Key Attestation certificate chain.
+   *
+   * @param chain The attestation certificate chain to verify.
+   * @param challengeChecker The challenge checker to use for additional challenge validation.
+   * @return [VerificationResult]
+   */
+  @JvmOverloads
+  fun verify(
+    chain: List<X509Certificate>,
+    challengeChecker: ChallengeChecker? = null,
+  ): VerificationResult {
     val certPath =
       try {
         KeyAttestationCertPath(chain)
       } catch (e: Exception) {
         return VerificationResult.ChainParsingFailure
       }
-    return verify(certPath, challenge)
+    return verify(certPath, challengeChecker)
   }
 
   /**
    * Verifies an Android Key Attestation certificate chain.
    *
    * @param chain The attestation certificate chain to verify.
+   * @param challengeChecker The challenge checker to use for additional validation of the challenge
+   *   in the attestation chain.
    * @return [VerificationResult]
    *
    * TODO: b/366058500 - Make the challenge required after Apparat's changes are rollback safe.
    */
   @JvmOverloads
-  fun verify(certPath: KeyAttestationCertPath, challenge: ByteArray? = null): VerificationResult {
+  fun verify(
+    certPath: KeyAttestationCertPath,
+    challengeChecker: ChallengeChecker? = null,
+  ): VerificationResult {
     val certPathValidator = CertPathValidator.getInstance("KeyAttestation")
     val certPathParameters =
       PKIXParameters(trustAnchorsSource()).apply {
@@ -114,8 +129,8 @@ open class Verifier(
       }
 
     if (
-      challenge != null &&
-        keyDescription.attestationChallenge.asReadOnlyByteBuffer() != ByteBuffer.wrap(challenge)
+      challengeChecker != null &&
+        !challengeChecker.checkChallenge(keyDescription.attestationChallenge)
     ) {
       return VerificationResult.ChallengeMismatch
     }

src/main/kotlin/challengecheckers/ChallengeMatcher.kt

@@ -0,0 +1,15 @@
+package com.android.keyattestation.verifier.challengecheckers
+
+import com.android.keyattestation.verifier.ChallengeChecker
+import com.google.protobuf.ByteString
+
+/**
+ * A basic implementation of [ChallengeChecker] that checks if the challenge in the attestation
+ * certificate is equal to the expected challenge.
+ */
+class ChallengeMatcher(private val expectedChallenge: ByteString) : ChallengeChecker {
+
+  constructor(expectedChallenge: ByteArray) : this(ByteString.copyFrom(expectedChallenge))
+
+  override fun checkChallenge(challenge: ByteString): Boolean = challenge.equals(expectedChallenge)
+}

src/test/kotlin/VerifierTest.kt

@@ -16,6 +16,7 @@
 
 package com.android.keyattestation.verifier
 
+import com.android.keyattestation.verifier.challengecheckers.ChallengeMatcher
 import com.android.keyattestation.verifier.testing.CertLists
 import com.android.keyattestation.verifier.testing.TestUtils.prodAnchors
 import com.android.keyattestation.verifier.testing.TestUtils.readCertPath
@@ -35,8 +36,7 @@ class VerifierTest {
   @Test
   fun verify_validChain_returnsSuccess() {
     val chain = readCertPath("blueline/sdk28/TEE_EC_NONE.pem")
-    val result =
-      assertIs<VerificationResult.Success>(verifier.verify(chain, "challenge".toByteArray()))
+    val result = assertIs<VerificationResult.Success>(verifier.verify(chain))
     assertThat(result.publicKey).isEqualTo(chain.leafCert().publicKey)
     assertThat(result.challenge).isEqualTo(ByteString.copyFromUtf8("challenge"))
     assertThat(result.securityLevel).isEqualTo(SecurityLevel.TRUSTED_ENVIRONMENT)
@@ -46,8 +46,7 @@ class VerifierTest {
   @Test
   fun verify_validChain_returnsDeviceIdentity() {
     val chain = readCertPath("blueline/sdk28/TEE_RSA_BASE+IMEI.pem")
-    val result =
-      assertIs<VerificationResult.Success>(verifier.verify(chain, "challenge".toByteArray()))
+    val result = assertIs<VerificationResult.Success>(verifier.verify(chain))
     assertThat(result.attestedDeviceIds)
       .isEqualTo(
         DeviceIdentity(
@@ -64,15 +63,34 @@ class VerifierTest {
   }
 
   @Test
-  fun verify_unexpectedChallenge_returnsChallengeMismatch() {
+  fun verify_challengeCheckerReturnsTrue_returnsSuccess() {
+    val challengeChecker: ChallengeChecker =
+      object : ChallengeChecker {
+        override fun checkChallenge(challenge: ByteString) = true
+      }
+
     val chain = readCertPath("blueline/sdk28/TEE_EC_NONE.pem")
-    assertIs<VerificationResult.ChallengeMismatch>(verifier.verify(chain, "foo".toByteArray()))
+    assertIs<VerificationResult.Success>(verifier.verify(chain, challengeChecker))
+  }
+
+  @Test
+  fun verify_challengeCheckerReturnsFalse_returnsChallengeMismatch() {
+    val challengeChecker: ChallengeChecker =
+      object : ChallengeChecker {
+        override fun checkChallenge(challenge: ByteString) = false
+      }
+
+    val chain = readCertPath("blueline/sdk28/TEE_EC_NONE.pem")
+    assertIs<VerificationResult.ChallengeMismatch>(verifier.verify(chain, challengeChecker))
   }
 
   @Test
   fun verify_unexpectedRootKey_returnsPathValidationFailure() {
     assertIs<VerificationResult.PathValidationFailure>(
-      verifier.verify(CertLists.wrongTrustAnchor, "challenge".toByteArray())
+      verifier.verify(
+        CertLists.wrongTrustAnchor,
+        ChallengeMatcher(ByteString.copyFromUtf8("challenge")),
+      )
     )
   }
 }

src/test/kotlin/challengecheckers/ChallengeMatcherTest.kt

@@ -0,0 +1,49 @@
+package com.android.keyattestation.verifier.challengecheckers
+
+import com.android.keyattestation.verifier.VerificationResult
+import com.android.keyattestation.verifier.Verifier
+import com.android.keyattestation.verifier.testing.TestUtils.prodAnchors
+import com.android.keyattestation.verifier.testing.TestUtils.readCertPath
+import com.google.common.truth.Truth.assertThat
+import com.google.protobuf.ByteString
+import java.time.Instant
+import kotlin.test.assertIs
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.junit.runners.JUnit4
+
+@RunWith(JUnit4::class)
+class ChallengeMatcherTest {
+
+  companion object {
+    private val testChallenge = ByteString.copyFromUtf8("challenge")
+  }
+
+  @Test
+  fun checkChallenge_matchingChallenge_returnsTrue() {
+    val challengeChecker = ChallengeMatcher(testChallenge)
+    assertThat(challengeChecker.checkChallenge(testChallenge)).isTrue()
+  }
+
+  @Test
+  fun checkChallenge_mismatchedChallenge_returnsFalse() {
+    val challengeChecker = ChallengeMatcher(testChallenge)
+    assertThat(challengeChecker.checkChallenge(ByteString.copyFromUtf8("foo"))).isFalse()
+  }
+
+  @Test
+  fun verify_expectedChallenge_returnsSuccess() {
+    val verifier = Verifier({ prodAnchors }, { setOf<String>() }, { Instant.now() })
+    val chain = readCertPath("blueline/sdk28/TEE_EC_NONE.pem")
+    assertIs<VerificationResult.Success>(verifier.verify(chain, ChallengeMatcher(testChallenge)))
+  }
+
+  @Test
+  fun verify_unexpectedChallenge_returnsChallengeMismatch() {
+    val verifier = Verifier({ prodAnchors }, { setOf<String>() }, { Instant.now() })
+    val chain = readCertPath("blueline/sdk28/TEE_EC_NONE.pem")
+    assertIs<VerificationResult.ChallengeMismatch>(
+      verifier.verify(chain, ChallengeMatcher(ByteString.copyFromUtf8("foo")))
+    )
+  }
+}