Introduce ChallengeChecker to keyattestation library

PiperOrigin-RevId: 777707059

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

roots.json

@@ -0,0 +1,4 @@
+[
+  "-----BEGIN CERTIFICATE-----\nMIIFHDCCAwSgAwIBAgIJAPHBcqaZ6vUdMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\nBAUTEGY5MjAwOWU4NTNiNmIwNDUwHhcNMjIwMzIwMTgwNzQ4WhcNNDIwMzE1MTgw\nNzQ4WjAbMRkwFwYDVQQFExBmOTIwMDllODUzYjZiMDQ1MIICIjANBgkqhkiG9w0B\nAQEFAAOCAg8AMIICCgKCAgEAr7bHgiuxpwHsK7Qui8xUFmOr75gvMsd/dTEDDJdS\nSxtf6An7xyqpRR90PL2abxM1dEqlXnf2tqw1Ne4Xwl5jlRfdnJLmN0pTy/4lj4/7\ntv0Sk3iiKkypnEUtR6WfMgH0QZfKHM1+di+y9TFRtv6y//0rb+T+W8a9nsNL/ggj\nnar86461qO0rOs2cXjp3kOG1FEJ5MVmFmBGtnrKpa73XpXyTqRxB/M0n1n/W9nGq\nC4FSYa04T6N5RIZGBN2z2MT5IKGbFlbC8UrW0DxW7AYImQQcHtGl/m00QLVWutHQ\noVJYnFPlXTcHYvASLu+RhhsbDmxMgJJ0mcDpvsC4PjvB+TxywElgS70vE0XmLD+O\nJtvsBslHZvPBKCOdT0MS+tgSOIfga+z1Z1g7+DVagf7quvmag8jfPioyKvxnK/Eg\nsTUVi2ghzq8wm27ud/mIM7AY2qEORR8Go3TVB4HzWQgpZrt3i5MIlCaY504LzSRi\nigHCzAPlHws+W0rB5N+er5/2pJKnfBSDiCiFAVtCLOZ7gLiMm0jhO2B6tUXHI/+M\nRPjy02i59lINMRRev56GKtcd9qO/0kUJWdZTdA2XoS82ixPvZtXQpUpuL12ab+9E\naDK8Z4RHJYYfCT3Q5vNAXaiWQ+8PTWm2QgBR/bkwSWc+NpUFgNPN9PvQi8WEg5Um\nAGMCAwEAAaNjMGEwHQYDVR0OBBYEFDZh4QB8iAUJUYtEbEf/GkzJ6k8SMB8GA1Ud\nIwQYMBaAFDZh4QB8iAUJUYtEbEf/GkzJ6k8SMA8GA1UdEwEB/wQFMAMBAf8wDgYD\nVR0PAQH/BAQDAgIEMA0GCSqGSIb3DQEBCwUAA4ICAQB8cMqTllHc8U+qCrOlg3H7\n174lmaCsbo/bJ0C17JEgMLb4kvrqsXZs01U3mB/qABg/1t5Pd5AORHARs1hhqGIC\nW/nKMav574f9rZN4PC2ZlufGXb7sIdJpGiO9ctRhiLuYuly10JccUZGEHpHSYM2G\ntkgYbZba6lsCPYAAP83cyDV+1aOkTf1RCp/lM0PKvmxYN10RYsK631jrleGdcdkx\noSK//mSQbgcWnmAEZrzHoF1/0gso1HZgIn0YLzVhLSA/iXCX4QT2h3J5z3znluKG\n1nv8NQdxei2DIIhASWfu804CA96cQKTTlaae2fweqXjdN1/v2nqOhngNyz1361mF\nmr4XmaKH/ItTwOe72NI9ZcwS1lVaCvsIkTDCEXdm9rCNPAY10iTunIHFXRh+7KPz\nlHGewCq/8TOohBRn0/NNfh7uRslOSZ/xKbN9tMBtw37Z8d2vvnXq/YWdsm1+JLVw\nn6yYD/yacNJBlwpddla8eaVMjsF6nBnIgQOf9zKSe06nSTqvgwUHosgOECZJZ1Eu\nzbH4yswbt02tKtKEFhx+v+OTge/06V+jGsqTWLsfrOCNLuA8H++z+pUENmpqnnHo\nvaI47gC+TNpkgYGkkBT6B/m/U01BuOBBTzhIlMEZq9qkDWuM2cA5kW5V3FJUcfHn\nw1IdYIg2Wxg7yHcQZemFQg==\n-----END CERTIFICATE-----",
+  "-----BEGIN CERTIFICATE-----\nMIICIjCCAaigAwIBAgIRAISp0Cl7DrWK5/8OgN52BgUwCgYIKoZIzj0EAwMwUjEc\nMBoGA1UEAwwTS2V5IEF0dGVzdGF0aW9uIENBMTEQMA4GA1UECwwHQW5kcm9pZDET\nMBEGA1UECgwKR29vZ2xlIExMQzELMAkGA1UEBhMCVVMwHhcNMjUwNzE3MjIzMjE4\nWhcNMzUwNzE1MjIzMjE4WjBSMRwwGgYDVQQDDBNLZXkgQXR0ZXN0YXRpb24gQ0Ex\nMRAwDgYDVQQLDAdBbmRyb2lkMRMwEQYDVQQKDApHb29nbGUgTExDMQswCQYDVQQG\nEwJVUzB2MBAGByqGSM49AgEGBSuBBAAiA2IABCPaI3FO3z5bBQo8cuiEas4HjqCt\nG/mLFfRT0MsIssPBEEU5Cfbt6sH5yOAxqEi5QagpU1yX4HwnGb7OtBYpDTB57uH5\nEczm34A5FNijV3s0/f0UPl7zbJcTx6xwqMIRq6NCMEAwDwYDVR0TAQH/BAUwAwEB\n/zAOBgNVHQ8BAf8EBAMCAQYwHQYDVR0OBBYEFFIyuyz7RkOb3NaBqQ5lZuA0QepA\nMAoGCCqGSM49BAMDA2gAMGUCMETfjPO/HwqReR2CS7p0ZWoD/LHs6hDi422opifH\nEUaYLxwGlT9SLdjkVpz0UUOR5wIxAIoGyxGKRHVTpqpGRFiJtQEOOTp/+s1GcxeY\nuR2zh/80lQyu9vAFCj6E4AXc+osmRg==\n-----END CERTIFICATE-----"
+]

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/main/kotlin/testing/TestUtils.kt

@@ -38,9 +38,8 @@ import org.bouncycastle.cert.jcajce.JcaX509CertificateConverter
 import org.bouncycastle.openssl.PEMParser
 
 object TestUtils {
-  private const val PROD_ROOT_PATH =
-    "googledata/html/external_content/android_googleapis_com/attestation/root"
-  const val TESTDATA_PATH = "third_party/java/keyattestation/testdata"
+  private const val PROD_ROOT_PATH = "roots.json"
+  const val TESTDATA_PATH = "testdata"
 
   fun readCertPath(subpath: String): KeyAttestationCertPath =
     readCertPath(readFile(Path(base = TESTDATA_PATH, /* subpaths...= */ subpath)))
@@ -60,14 +59,13 @@ object TestUtils {
       .let { KeyAttestationCertPath(it) }
   }
 
-  val prodRoot by lazy {
-    val certs = Gson().fromJson(readFile(PROD_ROOT_PATH), Array<String>::class.java).toSet()
-    check(certs.size == 1) { "Multiple certificates in the root file are not yet supported" }
-    certs.first().asX509Certificate()
+  val prodAnchors by lazy {
+    Gson()
+      .fromJson(readFile(PROD_ROOT_PATH), Array<String>::class.java)
+      .map { TrustAnchor(it.asX509Certificate(), null) }
+      .toSet()
   }
 
-  val prodAnchor = TrustAnchor(prodRoot, null)
-
   private fun readFile(path: Path) = path.reader()
   private fun readFile(path: String) = path.reader()
 }

src/test/kotlin/VerifierTest.kt

@@ -16,12 +16,12 @@
 
 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.prodRoot
+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.security.cert.TrustAnchor
 import java.time.Instant
 import kotlin.test.assertIs
 import org.junit.Test
@@ -31,18 +31,12 @@ import org.junit.runners.JUnit4
 /** Unit tests for [Verifier]. */
 @RunWith(JUnit4::class)
 class VerifierTest {
-  private val verifier =
-    Verifier(
-      { setOf(TrustAnchor(prodRoot, /* nameConstraints= */ null)) },
-      { setOf<String>() },
-      { Instant.now() },
-    )
+  private val verifier = Verifier({ prodAnchors }, { setOf<String>() }, { Instant.now() })
 
   @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)
@@ -52,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(
@@ -70,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.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, "foo".toByteArray()))
+    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,60 @@
+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.prodRoot
+import com.android.keyattestation.verifier.testing.TestUtils.readCertPath
+import com.google.common.truth.Truth.assertThat
+import com.google.protobuf.ByteString
+import java.security.cert.TrustAnchor
+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(
+        { setOf(TrustAnchor(prodRoot, /* nameConstraints= */ null)) },
+        { 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(
+        { setOf(TrustAnchor(prodRoot, /* nameConstraints= */ null)) },
+        { setOf<String>() },
+        { Instant.now() },
+      )
+    val chain = readCertPath("blueline/sdk28/TEE_EC_NONE.pem")
+    assertIs<VerificationResult.ChallengeMismatch>(
+      verifier.verify(chain, ChallengeMatcher(ByteString.copyFromUtf8("foo")))
+    )
+  }
+}

src/test/kotlin/provider/KeyAttestationCertPathValidatorTest.kt

@@ -19,7 +19,7 @@ package com.android.keyattestation.verifier.provider
 import com.android.keyattestation.verifier.testing.Certs.rootAnchor as testAnchor
 import com.android.keyattestation.verifier.testing.Chains
 import com.android.keyattestation.verifier.testing.FakeCalendar
-import com.android.keyattestation.verifier.testing.TestUtils.prodAnchor
+import com.android.keyattestation.verifier.testing.TestUtils.prodAnchors
 import com.google.common.truth.Truth.assertThat
 import java.security.InvalidAlgorithmParameterException
 import java.security.Security
@@ -42,7 +42,7 @@ import org.junit.runners.JUnit4
 class KeyAttestationCertPathValidatorTest {
   private val certPathValidator = CertPathValidator.getInstance("KeyAttestation")
   private val pkixCertPathValidator = CertPathValidator.getInstance("PKIX")
-  private val prodParams = PKIXParameters(setOf(prodAnchor))
+  private val prodParams = PKIXParameters(prodAnchors)
   private val testParams =
     PKIXParameters(setOf(testAnchor)).apply { date = FakeCalendar.DEFAULT.today() }
 
@@ -116,10 +116,10 @@ class KeyAttestationCertPathValidatorTest {
   }
 
   @Test
-  fun multipleAnchors_returnsSuccess() {
+  fun additionalAnchors_returnsSuccess() {
     val certPath = Chains.validFactoryProvisioned
-    val params =
-      PKIXParameters(setOf(prodAnchor, testAnchor)).apply { date = FakeCalendar.DEFAULT.today() }
+    val moreAnchors = prodAnchors.union(setOf(testAnchor))
+    val params = PKIXParameters(moreAnchors).apply { date = FakeCalendar.DEFAULT.today() }
     val result = certPathValidator.validate(certPath, params) as PKIXCertPathValidatorResult
     assertThat(result.trustAnchor).isEqualTo(testAnchor)
     assertThat(result.policyTree).isNull()
@@ -136,7 +136,7 @@ class KeyAttestationCertPathValidatorTest {
   }
 
   @Test
-  fun wrongAnchor_throwsCertPathValidatorException() {
+  fun multipleWrongAnchors_throwsCertPathValidatorException() {
     val certPath = Chains.validFactoryProvisioned
     val exception =
       assertFailsWith<CertPathValidatorException> {
@@ -146,14 +146,15 @@ class KeyAttestationCertPathValidatorTest {
       assertFailsWith<CertPathValidatorException> {
         pkixCertPathValidator.validate(certPath, prodParams)
       }
+    assertThat(prodParams.trustAnchors.size).isAtLeast(2)
     assertThat(exception.reason).isEqualTo(PKIXReason.NO_TRUST_ANCHOR)
     assertThat(pkixException.reason).isEqualTo(PKIXReason.NO_TRUST_ANCHOR)
   }
 
   @Test
-  fun multipleWrongAnchors_throwsCertPathValidatorException() {
+  fun singleWrongAnchor_throwsCertPathValidatorException() {
     val params =
-      PKIXParameters(setOf(prodAnchor, prodAnchor)).apply { date = FakeCalendar.DEFAULT.today() }
+      PKIXParameters(setOf(prodAnchors.first())).apply { date = FakeCalendar.DEFAULT.today() }
     val exception =
       assertFailsWith<CertPathValidatorException> {
         certPathValidator.validate(Chains.validFactoryProvisioned, params)