From 28b953032ee2d0d23d3dcd87544466d987c18b39 Mon Sep 17 00:00:00 2001
From: David Drysdale <drysdale@google.com>
Date: Mon, 16 Jan 2023 16:00:47 +0000
Subject: [PATCH] RKPv2 spec clarifications

- Rename keysToCertify to keysToSign to match param name in a few
  places.
- Make clearer that P-256 is allowed in EEK.
- Make clearer that EEK curve should match that specified in
  RpcHardwareInfo.supportedEekCurve.
- Add note about AAD for AES-GCM encryption.
- Add note about format of public key data in KDF context.

Test: None, comments only
Change-Id: Ie775a453b4d3941b7d24396da66681ab91978d81
---
 .../IRemotelyProvisionedComponent.aidl        | 25 +++++++++++++------
 .../security/keymint/ProtectedData.aidl       |  9 +++++--
 2 files changed, 24 insertions(+), 10 deletions(-)

diff --git a/security/rkp/aidl/android/hardware/security/keymint/IRemotelyProvisionedComponent.aidl b/security/rkp/aidl/android/hardware/security/keymint/IRemotelyProvisionedComponent.aidl
index 770cc7bb16..5bd214544b 100644
--- a/security/rkp/aidl/android/hardware/security/keymint/IRemotelyProvisionedComponent.aidl
+++ b/security/rkp/aidl/android/hardware/security/keymint/IRemotelyProvisionedComponent.aidl
@@ -159,18 +159,27 @@ interface IRemotelyProvisionedComponent {
      *        IRemotelyProvisionedComponent must validate the MACs on each key.  If any entry in the
      *        array lacks a valid MAC, the method must return STATUS_INVALID_MAC.
      *
-     *        If testMode is true, the keysToCertify array must contain only keys flagged as test
+     *        If testMode is true, the keysToSign array must contain only keys flagged as test
      *        keys. Otherwise, the method must return STATUS_PRODUCTION_KEY_IN_TEST_REQUEST.
      *
-     *        If testMode is false, the keysToCertify array must not contain any keys flagged as
+     *        If testMode is false, the keysToSign array must not contain any keys flagged as
      *        test keys. Otherwise, the method must return STATUS_TEST_KEY_IN_PRODUCTION_REQUEST.
      *
-     * @param in endpointEncryptionKey contains an X25519 public key which will be used to encrypt
-     *        the BCC. For flexibility, this is represented as a certificate chain, represented as a
-     *        CBOR array of COSE_Sign1 objects, ordered from root to leaf. The leaf contains the
-     *        X25519 encryption key, each other element is an Ed25519 key signing the next in the
-     *        chain. The root is self-signed. An implementor may also choose to use P256 as an
-     *        alternative curve for signing and encryption instead of Curve 25519.
+     * @param in endpointEncryptionKey contains an X25519 or P-256 public key which will be used to
+     *        encrypt the BCC. For flexibility, this is represented as a certificate chain
+     *        in the form of a CBOR array of COSE_Sign1 objects, ordered from root to leaf.  An
+     *        implementor may also choose to use P256 as an alternative curve for signing and
+     *        encryption instead of Curve 25519, as indicated by the supportedEekCurve field in
+     *        RpcHardwareInfo; the contents of the EEK chain will match the specified
+     *        supportedEekCurve.
+     *
+     *        - For CURVE_25519 the leaf contains the X25519 agreement key, each other element is an
+     *          Ed25519 key signing the next in the chain.
+     *
+     *        - For CURVE_P256 the leaf contains the P-256 agreement key, each other element is a
+     *          P-256 key signing the next in the chain.
+     *
+     *        In either case, the root is self-signed.
      *
      *            EekChain = [ + SignedSignatureKey, SignedEek ]
      *
diff --git a/security/rkp/aidl/android/hardware/security/keymint/ProtectedData.aidl b/security/rkp/aidl/android/hardware/security/keymint/ProtectedData.aidl
index bfe84176f4..57ee8cf25b 100644
--- a/security/rkp/aidl/android/hardware/security/keymint/ProtectedData.aidl
+++ b/security/rkp/aidl/android/hardware/security/keymint/ProtectedData.aidl
@@ -50,6 +50,8 @@ parcelable ProtectedData {
      *                                     ; salt = null
      *                                     ; info = .cbor Context (see below)
      *                                     ; K = HKDF-SHA-256(ikm, salt, info)
+     *                                     ; AAD for the encryption is a CBOR-serialized
+     *                                     ; Enc_structure (RFC 8152 s5.3) with empty external_aad.
      *         recipients : [
      *             [                       ; COSE_Recipient
      *                 protected : bstr .cbor {
@@ -65,7 +67,10 @@ parcelable ProtectedData {
      *     ]
      *
      *     ; The COSE_KDF_Context that is used to derive the ProtectedData encryption key with
-     *     ; HKDF. See details on use in ProtectedData comments above.
+     *     ; HKDF. See details on use in ProtectedData comments above. The public key data
+     *     ; included in the other field of PartyUInfo / PartyVInfo is encoded as:
+     *     ;  - a raw 32-byte public key for X25519
+     *     ;  - uncompressed SEC-1 coordinate data (0x04 || x || y) for P-256
      *     Context = [
      *         AlgorithmID : 3             ; AES-GCM 256
      *         PartyUInfo : [
@@ -138,7 +143,7 @@ parcelable ProtectedData {
      *                                            ; bytes inclusive
      *         VerifiedDeviceInfo,
      *         tag: bstr                 ; This is the tag from COSE_Mac0 of
-     *                                   ; KeysToCertify, to tie the key set to
+     *                                   ; KeysToSign, to tie the key set to
      *                                   ; the signature.
      *     ]
      *