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

@@ -20,9 +20,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.guava:guava:33.3.1-android")
@@ -97,6 +101,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,15 +102,16 @@ data class ProvisioningInfoMap(
   }
 }
 
+@Immutable
 data class DeviceIdentity(
-  val brand: String?,
-  val device: String?,
-  val product: String?,
-  val serialNumber: String?,
-  val imeis: Set<String>,
-  val meid: String?,
-  val manufacturer: String?,
-  val model: String?,
+  val brand: String? = null,
+  val device: String? = null,
+  val product: String? = null,
+  val serialNumber: String? = null,
+  @SuppressWarnings("Immutable") val imeis: Set<String> = emptySet(),
+  val meid: String? = null,
+  val manufacturer: String? = null,
+  val model: String? = null,
 ) {
   companion object {
     @JvmStatic
@@ -126,6 +133,7 @@ data class DeviceIdentity(
 }
 
 @Immutable
+@RequiresApi(24)
 data class KeyDescription(
   val attestationVersion: BigInteger,
   val attestationSecurityLevel: SecurityLevel,
@@ -160,23 +168,25 @@ data class KeyDescription(
     @JvmField val OID = ASN1ObjectIdentifier("1.3.6.1.4.1.11129.2.1.17")
 
     @JvmStatic
-    fun parseFrom(cert: X509Certificate) =
+    @JvmOverloads
+    fun parseFrom(cert: X509Certificate, logFn: (String) -> Unit = {}) =
       cert
         .getExtensionValue(OID.id)
         .let { ASN1OctetString.getInstance(it).octets }
-        .let { parseFrom(it) }
+        .let { parseFrom(it, logFn) }
 
     @JvmStatic
-    fun parseFrom(bytes: ByteArray) =
+    @JvmOverloads
+    fun parseFrom(bytes: ByteArray, logFn: (String) -> Unit = {}) =
       try {
-        from(ASN1Sequence.getInstance(bytes))
+        from(ASN1Sequence.getInstance(bytes), logFn)
       } catch (e: NullPointerException) {
         // Workaround for a NPE in BouncyCastle.
         // https://github.com/bcgit/bc-java/blob/228211ecb973fe87fdd0fc4ab16ba0446ec1a29c/core/src/main/java/org/bouncycastle/asn1/ASN1UniversalType.java#L24
         throw IllegalArgumentException(e)
       }
 
-    private fun from(seq: ASN1Sequence): KeyDescription {
+    private fun from(seq: ASN1Sequence, logFn: (String) -> Unit = {}): KeyDescription {
       require(seq.size() == 8)
       return KeyDescription(
         attestationVersion = seq.getObjectAt(0).toInt(),
@@ -185,8 +195,8 @@ data class KeyDescription(
         keyMintSecurityLevel = seq.getObjectAt(3).toSecurityLevel(),
         attestationChallenge = seq.getObjectAt(4).toByteString(),
         uniqueId = seq.getObjectAt(5).toByteString(),
-        softwareEnforced = seq.getObjectAt(6).toAuthorizationList(),
-        hardwareEnforced = seq.getObjectAt(7).toAuthorizationList(),
+        softwareEnforced = seq.getObjectAt(6).toAuthorizationList(logFn),
+        hardwareEnforced = seq.getObjectAt(7).toAuthorizationList(logFn),
       )
     }
   }
@@ -218,7 +228,7 @@ enum class Origin(val value: Long) {
   RESERVED(3),
   SECURELY_IMPORTED(4);
 
-  internal fun toAsn1() = ASN1Integer(value)
+  fun toAsn1() = ASN1Integer(value)
 }
 
 /**
@@ -227,6 +237,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),
@@ -269,7 +280,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,
+        )
   }
 }
 
@@ -280,6 +294,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,
@@ -397,7 +412,7 @@ data class AuthorizationList(
       .let { DERSequence(it.toTypedArray()) }
 
   internal companion object {
-    fun from(seq: ASN1Sequence, validateTagOrder: Boolean = false): AuthorizationList {
+    fun from(seq: ASN1Sequence, logFn: (String) -> Unit = { _ -> }): AuthorizationList {
       val objects =
         seq.associate {
           require(it is ASN1TaggedObject) {
@@ -417,9 +432,8 @@ data class AuthorizationList(
        * 2. within each class of tags, the elements or alternatives shall appear in ascending order
        *    of their tag numbers.
        */
-      // TODO: b/356172932 - Add test data once an example certificate is found in the wild.
-      if (validateTagOrder && !objects.keys.zipWithNext().all { (lhs, rhs) -> rhs > lhs }) {
-        throw IllegalArgumentException("AuthorizationList tags must appear in ascending order")
+      if (!objects.keys.zipWithNext().all { (lhs, rhs) -> rhs > lhs }) {
+        logFn("AuthorizationList tags should appear in ascending order")
       }
 
       return AuthorizationList(
@@ -449,7 +463,7 @@ data class AuthorizationList(
         rollbackResistant = if (objects.containsKey(KeyMintTag.ROLLBACK_RESISTANT)) true else null,
         rootOfTrust = objects[KeyMintTag.ROOT_OF_TRUST]?.toRootOfTrust(),
         osVersion = objects[KeyMintTag.OS_VERSION]?.toInt(),
-        osPatchLevel = objects[KeyMintTag.OS_PATCH_LEVEL]?.toPatchLevel(),
+        osPatchLevel = objects[KeyMintTag.OS_PATCH_LEVEL]?.toPatchLevel("OS", logFn),
         attestationApplicationId =
           objects[KeyMintTag.ATTESTATION_APPLICATION_ID]?.toAttestationApplicationId(),
         attestationIdBrand = objects[KeyMintTag.ATTESTATION_ID_BRAND]?.toStr(),
@@ -460,8 +474,8 @@ data class AuthorizationList(
         attestationIdMeid = objects[KeyMintTag.ATTESTATION_ID_MEID]?.toStr(),
         attestationIdManufacturer = objects[KeyMintTag.ATTESTATION_ID_MANUFACTURER]?.toStr(),
         attestationIdModel = objects[KeyMintTag.ATTESTATION_ID_MODEL]?.toStr(),
-        vendorPatchLevel = objects[KeyMintTag.VENDOR_PATCH_LEVEL]?.toPatchLevel(),
-        bootPatchLevel = objects[KeyMintTag.BOOT_PATCH_LEVEL]?.toPatchLevel(),
+        vendorPatchLevel = objects[KeyMintTag.VENDOR_PATCH_LEVEL]?.toPatchLevel("vendor", logFn),
+        bootPatchLevel = objects[KeyMintTag.BOOT_PATCH_LEVEL]?.toPatchLevel("boot", logFn),
         attestationIdSecondImei = objects[KeyMintTag.ATTESTATION_ID_SECOND_IMEI]?.toStr(),
         moduleHash = objects[KeyMintTag.MODULE_HASH]?.toByteString(),
       )
@@ -480,14 +494,24 @@ data class PatchLevel(val yearMonth: YearMonth, val version: Int? = null) {
   }
 
   companion object {
-    fun from(patchLevel: ASN1Encodable): PatchLevel? {
+    fun from(
+      patchLevel: ASN1Encodable,
+      partitionName: String = "",
+      logFn: (String) -> Unit = { _ -> },
+    ): PatchLevel? {
       check(patchLevel is ASN1Integer) { "Must be an ASN1Integer, was ${this::class.simpleName}" }
-      return from(patchLevel.value.toString())
+      return from(patchLevel.value.toString(), partitionName, logFn)
     }
 
     @JvmStatic
-    fun from(patchLevel: String): PatchLevel? {
+    @JvmOverloads
+    fun from(
+      patchLevel: String,
+      partitionName: String = "",
+      logFn: (String) -> Unit = { _ -> },
+    ): PatchLevel? {
       if (patchLevel.length != 6 && patchLevel.length != 8) {
+        logFn("Invalid $partitionName patch level: $patchLevel")
         return null
       }
       try {
@@ -496,6 +520,7 @@ data class PatchLevel(val yearMonth: YearMonth, val version: Int? = null) {
         val version = if (patchLevel.length == 8) patchLevel.substring(6).toInt() else null
         return PatchLevel(yearMonth, version)
       } catch (e: DateTimeParseException) {
+        logFn("Invalid $partitionName patch level: $patchLevel")
         return null
       }
     }
@@ -625,12 +650,10 @@ private fun ASN1Encodable.toAttestationApplicationId(): AttestationApplicationId
   return AttestationApplicationId.from(ASN1Sequence.getInstance(this.octets))
 }
 
-// TODO: b/356172932 - `validateTagOrder` should default to true after making it user configurable.
-private fun ASN1Encodable.toAuthorizationList(
-  validateTagOrder: Boolean = false
-): AuthorizationList {
+@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, validateTagOrder)
+  return AuthorizationList.from(this, logFn)
 }
 
 private fun ASN1Encodable.toBoolean(): Boolean {
@@ -657,7 +680,10 @@ private fun ASN1Encodable.toInt(): BigInteger {
   return this.value
 }
 
-private fun ASN1Encodable.toPatchLevel(): PatchLevel? = PatchLevel.from(this)
+private fun ASN1Encodable.toPatchLevel(
+  partitionName: String = "",
+  logFn: (String) -> Unit = { _ -> },
+): PatchLevel? = PatchLevel.from(this, partitionName, logFn)
 
 private fun ASN1Encodable.toRootOfTrust(): RootOfTrust {
   check(this is ASN1Sequence) { "Object must be an ASN1Sequence, was ${this::class.simpleName}" }

src/main/kotlin/KeyAttestationReason.kt

@@ -0,0 +1,32 @@
+/*
+ * 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_AFTER_TARGET,
+  TARGET_MISSING_ATTESTATION_EXTENSION,
+  ADDITIONAL_ATTESTATION_EXTENSION,
+  KEY_ORIGIN_NOT_GENERATED,
+  MISMATCHED_SECURITY_LEVELS,
+  ROOT_OF_TRUST_MISSING,
+  UNKNOWN_TAG_NUMBER,
+}