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,12 +102,13 @@ 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(),
+  @SuppressWarnings("Immutable") val imeis: Set<String> = emptySet(),
   val meid: String? = null,
   val manufacturer: String? = null,
   val model: String? = null,
@@ -126,6 +133,7 @@ data class DeviceIdentity(
 }
 
 @Immutable
+@RequiresApi(24)
 data class KeyDescription(
   val attestationVersion: BigInteger,
   val attestationSecurityLevel: SecurityLevel,
@@ -229,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),
@@ -271,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,
+        )
   }
 }
 
@@ -282,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,
@@ -637,6 +650,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,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,
+}

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. */
@@ -114,6 +116,7 @@ interface LogHook {
  * @param anchor a [TrustAnchor] to use for certificate path verification.
  */
 @ThreadSafe
+@RequiresApi(24)
 open class Verifier(
   private val trustAnchorsSource: () -> Set<TrustAnchor>,
   private val revokedSerialsSource: () -> Set<String>,
@@ -211,10 +214,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 (
@@ -229,7 +238,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,
       )
     }
 
@@ -238,13 +248,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

@@ -16,11 +16,13 @@
 
 package com.android.keyattestation.verifier.provider
 
+import com.android.keyattestation.verifier.SecurityLevel
 import com.android.keyattestation.verifier.asX509Certificate
 import com.google.protobuf.ByteString
 import java.security.cert.CertPath
 import java.security.cert.CertificateException
 import java.security.cert.X509Certificate
+import javax.security.auth.x500.X500Principal
 
 /**
  * [CertPath] representing an Android key attestation certificate chain.
@@ -29,9 +31,9 @@ import java.security.cert.X509Certificate
  * `KeyStore.getCertificateChain()`) in the following order:
  * 1. Leaf certificate (containing the extension)
  * 2. Attestation certificate (contains the ProvisioningInfo extension if remotely provisioned)
- * 3. Intermediate certificate
- * 5. [Intermediate certificate] (if remotely provisioned)
- * 4. Root certificate
+ * 3. Intermediate certificate (not present if software-backed attestation)
+ * 4. [Intermediate certificate] (only present if remotely provisioned)
+ * 5. Root certificate
  *
  * The last certificate in the chain is the trust anchor and is not included in the resulting
  * [CertPath]: "By convention, the certificates in a CertPath object of type X.509 are ordered
@@ -45,15 +47,8 @@ class KeyAttestationCertPath(certs: List<X509Certificate>) : CertPath("X.509") {
   val certificatesWithAnchor: List<X509Certificate>
 
   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
   }
@@ -68,7 +63,43 @@ class KeyAttestationCertPath(certs: List<X509Certificate>) : CertPath("X.509") {
 
   override fun getCertificates(): List<X509Certificate> = certificatesWithAnchor.dropLast(1)
 
-  fun provisioningMethod(): ProvisioningMethod = intermediateCert().provisioningMethod()
+  fun provisioningMethod() =
+    when {
+      isFactoryProvisioned() -> ProvisioningMethod.FACTORY_PROVISIONED
+      isRemoteProvisioned() -> ProvisioningMethod.REMOTELY_PROVISIONED
+      else -> ProvisioningMethod.UNKNOWN
+    }
+
+  fun securityLevel() =
+    when (provisioningMethod()) {
+      ProvisioningMethod.FACTORY_PROVISIONED ->
+        when (
+          parseDN(intermediateCert().subjectX500Principal.getName(X500Principal.RFC1779))[
+            "OID.2.5.4.12"]
+        ) {
+          "TEE" -> SecurityLevel.TRUSTED_ENVIRONMENT
+          "StrongBox" -> SecurityLevel.STRONG_BOX
+          else -> SecurityLevel.SOFTWARE // Should never happen because isFactoryProvisioned()
+        }
+      ProvisioningMethod.REMOTELY_PROVISIONED -> {
+        try {
+          when (
+            parseDN(
+              certificates[certificates.size - 2]
+                .subjectX500Principal
+                .getName(X500Principal.RFC1779)
+            )["O"]
+          ) {
+            "TEE" -> SecurityLevel.TRUSTED_ENVIRONMENT
+            "StrongBox" -> SecurityLevel.STRONG_BOX
+            else -> SecurityLevel.SOFTWARE
+          }
+        } catch (e: Exception) {
+          SecurityLevel.SOFTWARE
+        }
+      }
+      else -> SecurityLevel.SOFTWARE
+    }
 
   /**
    * Returns the leaf certificate from the certificate chain.
@@ -84,6 +115,17 @@ class KeyAttestationCertPath(certs: List<X509Certificate>) : CertPath("X.509") {
 
   fun intermediateCert(): X509Certificate = certificates.last()
 
+  private fun isFactoryProvisioned(): Boolean {
+    val rdn = parseDN(this.intermediateCert().subjectX500Principal.getName(X500Principal.RFC1779))
+    return rdn.containsKey("OID.2.5.4.5") && rdn["OID.2.5.4.12"] in setOf("TEE", "StrongBox")
+  }
+
+  // TODO(google-internal bug): Update this to use fields in the RKP root.
+  private fun isRemoteProvisioned(): Boolean {
+    val rdn = parseDN(this.intermediateCert().subjectX500Principal.getName(X500Principal.RFC1779))
+    return rdn["CN"] == "Droid CA2" && rdn["O"] == "Google LLC"
+  }
+
   companion object {
     @JvmStatic
     @Throws(CertificateException::class)
@@ -93,3 +135,22 @@ class KeyAttestationCertPath(certs: List<X509Certificate>) : CertPath("X.509") {
     private fun X509Certificate.isSelfIssued() = issuerX500Principal == subjectX500Principal
   }
 }
+
+enum class ProvisioningMethod {
+  UNKNOWN,
+  FACTORY_PROVISIONED,
+  REMOTELY_PROVISIONED,
+}
+
+private fun parseDN(dn: String): Map<String, String> {
+  val attributes = mutableMapOf<String, String>()
+  val parts = dn.split(",")
+
+  for (part in parts) {
+    val keyValue = part.trim().split("=", limit = 2)
+    if (keyValue.size == 2) {
+      attributes[keyValue[0].trim()] = keyValue[1].trim()
+    }
+  }
+  return attributes
+}