Add KeyAttestationReason to CertPathValidatorException.

This will allow callers to distinguish between different errors in the
chain without string matching. This requires explicitly stating the
required API for each method which diretly or indirectly uses
KeyAttestationReason, but shouldn't be an actual change in requirements
since the other reasons also require API 24 when used on Android.

This also moves the key attestation chain format checks to be
exclusively in the validator instead of some of them being duplicated
in the KeyAttestationCertPath constructor. The validator checks could
previously never be executed and the CertPathValidatorException allows
for more structured information returned on exception.

PiperOrigin-RevId: 805800611

Author: carmenyh

build.gradle.kts

@@ -19,9 +19,13 @@ plugins {
   id("org.jetbrains.kotlin.jvm") version "2.2.0"
 }
 
-repositories { mavenCentral() }
+repositories {
+  mavenCentral()
+  google()
+}
 
 dependencies {
+  implementation("androidx.annotation:annotation:1.9.1")
   implementation("co.nstant.in:cbor:0.9")
   implementation("com.google.code.gson:gson:2.11.0")
   implementation("com.google.errorprone:error_prone_annotations:2.41.0")
@@ -95,6 +99,4 @@ val generateSources by
 
 sourceSets { main { kotlin.srcDir(generateSources) } }
 
-tasks.named("compileKotlin").configure {
-  dependsOn("generateSources")
-}
+tasks.named("compileKotlin").configure { dependsOn("generateSources") }

src/main/kotlin/Extension.kt

@@ -16,6 +16,7 @@
 
 package com.android.keyattestation.verifier
 
+import androidx.annotation.RequiresApi
 import co.nstant.`in`.cbor.CborDecoder
 import co.nstant.`in`.cbor.CborEncoder
 import co.nstant.`in`.cbor.CborException
@@ -57,6 +58,11 @@ import org.bouncycastle.asn1.DERSet
 import org.bouncycastle.asn1.DERTaggedObject
 import org.bouncycastle.asn1.x509.Extension
 
+@Immutable
+@RequiresApi(24)
+data class ExtensionParsingException(val msg: String, val reason: KeyAttestationReason? = null) :
+  Exception(msg)
+
 @Immutable
 data class ProvisioningInfoMap(
   val certificatesIssued: Int,
@@ -96,12 +102,14 @@ data class ProvisioningInfoMap(
   }
 }
 
+@Immutable
 data class DeviceIdentity(
   val brand: String? = null,
   val device: String? = null,
   val product: String? = null,
   val serialNumber: String? = null,
-  val imeis: Set<String> = emptySet(),
+  // TODO(google-internal bug): Look into using ImmutableSet.
+  @SuppressWarnings("Immutable") val imeis: Set<String> = emptySet(),
   val meid: String? = null,
   val manufacturer: String? = null,
   val model: String? = null,
@@ -126,6 +134,7 @@ data class DeviceIdentity(
 }
 
 @Immutable
+@RequiresApi(24)
 data class KeyDescription(
   val attestationVersion: BigInteger,
   val attestationSecurityLevel: SecurityLevel,
@@ -229,6 +238,7 @@ enum class Origin(val value: Long) {
  * @see
  *   https://cs.android.com/android/platform/superproject/main/+/main:hardware/interfaces/security/keymint/aidl/android/hardware/security/keymint/Tag.aidl
  */
+@RequiresApi(24)
 enum class KeyMintTag(val value: Int) {
   PURPOSE(1),
   ALGORITHM(2),
@@ -271,7 +281,10 @@ enum class KeyMintTag(val value: Int) {
   companion object {
     fun from(value: Int) =
       values().firstOrNull { it.value == value }
-        ?: throw IllegalArgumentException("unknown tag number: $value")
+        ?: throw ExtensionParsingException(
+          "unknown tag number: $value",
+          KeyAttestationReason.UNKNOWN_TAG_NUMBER,
+        )
   }
 }
 
@@ -282,6 +295,7 @@ enum class KeyMintTag(val value: Int) {
  *   https://source.android.com/docs/security/features/keystore/attestation#authorizationlist-fields
  */
 @Immutable
+@RequiresApi(24)
 data class AuthorizationList(
   @SuppressWarnings("Immutable") val purposes: Set<BigInteger>? = null,
   val algorithms: BigInteger? = null,
@@ -637,6 +651,7 @@ private fun ASN1Encodable.toAttestationApplicationId(): AttestationApplicationId
   return AttestationApplicationId.from(ASN1Sequence.getInstance(this.octets))
 }
 
+@RequiresApi(24)
 private fun ASN1Encodable.toAuthorizationList(logFn: (String) -> Unit): AuthorizationList {
   check(this is ASN1Sequence) { "Object must be an ASN1Sequence, was ${this::class.simpleName}" }
   return AuthorizationList.from(this, logFn)

src/main/kotlin/KeyAttestationReason.kt

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.android.keyattestation.verifier
+
+import androidx.annotation.RequiresApi
+import java.security.cert.CertPathValidatorException
+
+/** Reasons why a certificate chain could not be verified which are specific to key attestation. */
+@RequiresApi(24)
+enum class KeyAttestationReason : CertPathValidatorException.Reason {
+  // Certificate chain contains a certificate after the target certificate.
+  // This likely indicates that an attacker is trying to get the verifier to
+  // accept an attacker-controlled key.
+  CERTIFICATE_AFTER_TARGET,
+  // The key description is missing from the expected certificate.
+  // An Android key attestation chain without a key description is malformed.
+  TARGET_MISSING_ATTESTATION_EXTENSION,
+  // Certificate chain contains a certificate other than the target certificate with an attestation
+  // extension. This likely indicates that an attacker is trying to manipulate the key and
+  // device properties.
+  ADDITIONAL_ATTESTATION_EXTENSION,
+  // The key was not generated. The verifier cannot know that the key has always been in the
+  // secure environment.
+  KEY_ORIGIN_NOT_GENERATED,
+  // The attestation and the KeyMint security levels do not match.
+  // This likely indicates that the attestation was generated in software and so cannot be trusted.
+  MISMATCHED_SECURITY_LEVELS,
+  // The key description is missing the root of trust.
+  // An Android key attestation chain without a root of trust is malformed.
+  ROOT_OF_TRUST_MISSING,
+  // There was an error parsing the key description and an unknown tag number was encountered.
+  UNKNOWN_TAG_NUMBER,
+}

src/main/kotlin/Verifier.kt

@@ -16,6 +16,7 @@
 
 package com.android.keyattestation.verifier
 
+import androidx.annotation.RequiresApi
 import com.android.keyattestation.verifier.provider.KeyAttestationCertPath
 import com.android.keyattestation.verifier.provider.KeyAttestationProvider
 import com.android.keyattestation.verifier.provider.ProvisioningMethod
@@ -50,9 +51,10 @@ sealed interface VerificationResult {
 
   data class ChainParsingFailure(val cause: Exception) : VerificationResult
 
-  data class ExtensionParsingFailure(val cause: Exception) : VerificationResult
+  data class ExtensionParsingFailure(val cause: ExtensionParsingException) : VerificationResult
 
-  data class ExtensionConstraintViolation(val cause: String) : VerificationResult
+  data class ExtensionConstraintViolation(val cause: String, val reason: KeyAttestationReason) :
+    VerificationResult
 }
 
 /** Interface for logging info level key attestation events and information. */
@@ -131,6 +133,7 @@ open class Verifier(
    * @return [VerificationResult]
    */
   @JvmOverloads
+  @RequiresApi(24)
   fun verify(
     chain: List<X509Certificate>,
     challengeChecker: ChallengeChecker? = null,
@@ -150,6 +153,7 @@ open class Verifier(
     return result
   }
 
+  @RequiresApi(24)
   private fun internalVerify(
     certPath: KeyAttestationCertPath,
     challengeChecker: ChallengeChecker? = null,
@@ -192,10 +196,16 @@ open class Verifier(
         checkNotNull(
           KeyDescription.parseFrom(certPath.leafCert(), { msg -> log?.logInfoMessage(msg) })
         ) {
+          // Should never happen since the extension's presence is checked by by validate().
           "Key attestation extension not found"
         }
-      } catch (e: Exception) {
+      } catch (e: ExtensionParsingException) {
         return VerificationResult.ExtensionParsingFailure(e)
+      } catch (e: Exception) {
+        // TODO(google-internal bug): When experimental contracts aren't experimental,
+        // update the IllegalArgumentException and IllegalStateException cases to return
+        // ExtensionParsingException.
+        return VerificationResult.ExtensionParsingFailure(ExtensionParsingException(e.toString()))
       }
     log?.logKeyDescription(keyDescription)
     if (
@@ -210,7 +220,8 @@ open class Verifier(
         keyDescription.hardwareEnforced.origin != Origin.GENERATED
     ) {
       return VerificationResult.ExtensionConstraintViolation(
-        "origin != GENERATED: ${keyDescription.hardwareEnforced.origin}"
+        "origin != GENERATED: ${keyDescription.hardwareEnforced.origin}",
+        KeyAttestationReason.KEY_ORIGIN_NOT_GENERATED,
       )
     }
 
@@ -219,13 +230,15 @@ open class Verifier(
         keyDescription.attestationSecurityLevel
       } else {
         return VerificationResult.ExtensionConstraintViolation(
-          "attestationSecurityLevel != keyMintSecurityLevel: ${keyDescription.attestationSecurityLevel} != ${keyDescription.keyMintSecurityLevel}"
+          "attestationSecurityLevel != keyMintSecurityLevel: ${keyDescription.attestationSecurityLevel} != ${keyDescription.keyMintSecurityLevel}",
+          KeyAttestationReason.MISMATCHED_SECURITY_LEVELS,
         )
       }
     val rootOfTrust =
       keyDescription.hardwareEnforced.rootOfTrust
         ?: return VerificationResult.ExtensionConstraintViolation(
-          "hardwareEnforced.rootOfTrust is null"
+          "hardwareEnforced.rootOfTrust is null",
+          KeyAttestationReason.ROOT_OF_TRUST_MISSING,
         )
     return VerificationResult.Success(
       pathValidationResult.publicKey,

src/main/kotlin/X509CertificateExt.kt

@@ -16,6 +16,7 @@
 
 package com.android.keyattestation.verifier
 
+import androidx.annotation.RequiresApi
 import java.io.InputStream
 import java.security.cert.CertificateException
 import java.security.cert.CertificateFactory
@@ -36,7 +37,7 @@ fun InputStream.asX509Certificate() =
  * @return the DER-encoded OCTET string containing the KeyDescription sequence or null if the
  *   extension is not present in the certificate.
  */
-fun X509Certificate.keyDescription() = KeyDescription.parseFrom(this)
+@RequiresApi(24) fun X509Certificate.keyDescription() = KeyDescription.parseFrom(this)
 
 /**
  * Returns the Android Key Attestation extension for provisioning info.

src/main/kotlin/provider/KeyAttestationCertPath.kt

@@ -49,16 +49,6 @@ class KeyAttestationCertPath(certs: List<X509Certificate>) : CertPath("X.509") {
   init {
     // < 3 check needed to support parsing software-backed certs.
     if (certs.size < 3) throw CertificateException("At least 3 certificates are required")
-    when (certs.indexOfLast { it.hasAttestationExtension() }) {
-      0 -> {} // expected value
-      -1 -> throw CertificateException("Attestation extension not found")
-      else ->
-        if (certs[0].hasAttestationExtension()) {
-          throw CertificateException("Additional attestation extension found")
-        } else {
-          throw CertificateException("Certificate after target certificate")
-        }
-    }
     if (!certs.last().isSelfIssued()) throw CertificateException("Root certificate not found")
     this.certificatesWithAnchor = certs
   }