Merge "Clarify certificate chain requirements documentation." am: 93d82aca8f am: bdaff3d05e am: 987b215d3c am: d709ccbc59
Original change: https://android-review.googlesource.com/c/platform/hardware/interfaces/+/1655827
Change-Id: I45cb259e7ae830b1237440c40be170faea6b8371
diff --git a/security/keymint/aidl/android/hardware/security/keymint/KeyCreationResult.aidl b/security/keymint/aidl/android/hardware/security/keymint/KeyCreationResult.aidl
index c589ca1..f3c5477 100644
--- a/security/keymint/aidl/android/hardware/security/keymint/KeyCreationResult.aidl
+++ b/security/keymint/aidl/android/hardware/security/keymint/KeyCreationResult.aidl
@@ -53,13 +53,36 @@
/**
* If the generated/imported key is an asymmetric key, `certificateChain` will contain a chain
- * of one or more certificates. If the key parameters provided to the generate/import method
- * contains Tag::ATTESTATION_CHALLENGE the first certificate will contain an attestation
- * extension, and will be signed by a factory-installed attestation key and followed by a chain
- * of certificates leading to an authoritative root. If there is no attestation challenge, only
- * one certificate will be returned, and it will be self-signed or contain a fake signature,
- * depending on whether the key has KeyPurpose::SIGN. If the generated key is symmetric,
- * certificateChain will be empty.
+ * of one or more certificates.
+ *
+ * There are a few variations in what is contained in `certificateChain`, depending on whether
+ * the caller requested attestation, whether they provided an attestation key (via the
+ * `attestationKey` parameter of `generateKey()`, `importKey()` or `importWrappedKey()`), and in
+ * the non-attestaion case, whether the key can self-sign.
+ *
+ * 1. Attestation with factory key. If Tag::ATTESTATION_CHALLENGE is provided and the
+ * `attestationKey` parameter on the generate/import call is null, the returned certificate
+ * chain must contain an attestation certificate signed with a factory-provisioned
+ * attestation key, and the full certificate chain for that factory-provisioned attestation
+ * key.
+ *
+ * 2. Attestation with caller-provided key. If Tag::ATTESTATION_CHALLENGE is provided and the
+ * `attestationKey` parameter on the generat/import call is non-null and contains the key
+ * blob of a key with KeyPurpose::ATTEST_KEY, the returned certificate chain must contain
+ * only an attestation certificate signed with the specified key. The caller must know the
+ * certificate chain for the provided key.
+ *
+ * 3. Non-attestation with signing key. If Tag::ATTESTATION_CHALLENGE is not provided and the
+ * generated/imported key has KeyPurpose::SIGN, then the returned certificate chain must
+ * contain only a single self-signed certificate with no attestation extension.
+ *
+ * 4. Non-attestation with non-signing key. If TAG::ATTESTATION_CHALLENGE is not provided and
+ * the generated/imported key does not have KeyPurpose::SIGN, then the returned certificate
+ * chain must contain only a single certificate with an empty signature and no attestation
+ * extension.
+ *
+ * 5. Symmetric key. If the generated/imported key is symmetric, the certificate chain must be
+ * empty.
*/
Certificate[] certificateChain;
}