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;
 }