From aaa1ce865fabdd4b2fa31977e15b71e1585d22d6 Mon Sep 17 00:00:00 2001
From: Matt Feddersen <mattfedd@google.com>
Date: Tue, 2 May 2023 17:31:52 +0000
Subject: [PATCH] Improve documentation for
 OEMCrypto_GenerateCertificateKeyPair

Bug: 279194702

Merged from https://widevine-internal-review.googlesource.com/173630

Merged from https://widevine-internal-review.googlesource.com/174539

Change-Id: I59dfe4c5053c24c011c9222fe516b446df6524e0
---
 .../oemcrypto/include/OEMCryptoCENC.h         | 58 ++++++++++++++++---
 1 file changed, 49 insertions(+), 9 deletions(-)

diff --git a/libwvdrmengine/oemcrypto/include/OEMCryptoCENC.h b/libwvdrmengine/oemcrypto/include/OEMCryptoCENC.h
index c0d411c6..340a045c 100644
--- a/libwvdrmengine/oemcrypto/include/OEMCryptoCENC.h
+++ b/libwvdrmengine/oemcrypto/include/OEMCryptoCENC.h
@@ -4864,11 +4864,54 @@ OEMCryptoResult OEMCrypto_GetBootCertificateChain(
  * key is supposed to be certified by the server. The private key is wrapped
  * with the encryption key so it can be stored in the file system.
  *
- * If an OEM private key is unavailable, the request is assumed for OEM
+ * The |public_key_signature| output is formatted differently depending
+ * on whether or not an OEM private key has been loaded.
+ *
+ * If an OEM private key is unavailable, the request is assumed to be for OEM
  * certificate provisioning. In this case, the public key is signed by the
- * device private key. If an OEM private key is available, the request is
- * assumed for DRM certificate provisioning and the public key is signed by the
- * OEM private key.
+ * device private key. The format of |public_key_signature| in this case is a
+ * COSE_Sign1 CBOR array. The format is described in RFC 8152 Section 4.2 and
+ * 4.4, as well as Android IRemotelyProvisionedComponent.aidl (under
+ * "SignedData<Data>")
+ *
+ *   |public_key_signature|: COSE_Sign1 CBOR array
+ *   [
+ *     protected: bstr .cbor { 1 : AlgorithmEdDSA / AlgorithmES256 /
+ *                                 AlgorithmES384 },
+ *     unprotected: {},
+ *     payload: bstr .cbor Data / nil,
+ *     signature: bstr      ; PureEd25519(priv_key, Sig_structure) /
+ *                          ; ECDSA(priv_key, Sig_structure)
+ *   ]
+ *
+ * Notes:
+ *   1. The payload field in the COSE_Sign1 struct is the public key generated
+ *      by OEMCrypto_GenerateCertificateKeyPair
+ *   2. The signature field in the COSE_Sign1 struct is the concatenation of the
+ *      (R,S) values from the EC/Ed signature. If either R or S is smaller than
+ *      the key size, it is left-padded with 0 to match the key size as
+ *      described in RFC 8152. This signature is not DER encoded.
+ *   3. The signature is generated by calling the selected EC signing function
+ *      (PureEd25519 or one of the supported ECDSA algorithms) on
+ *      `Sig_structure`, which is a CBOR array described below. The payload
+ *      field in Sig_structure is the same as the payload in the above
+ *      COSE_Sign1 CBOR array.
+ *
+ *   Sig_structure: CBOR array
+ *   [
+ *     context: "Signature1",
+ *     protected: bstr .cbor { 1 : AlgorithmEdDSA / AlgorithmES256 /
+ *                                 AlgorithmES384 },
+ *     external_aad: bstr .size 0,
+ *     payload: bstr .cbor Data / nil,
+ *   ]
+ *
+ * If an OEM private key is available, the request is assumed to be for DRM
+ * certificate provisioning and the public key is signed by the OEM private key.
+ * If the OEM private key is an RSA key, then |public_key_signature| is the raw
+ * output of the RSA sign operation with RSASSA-PSS padding. If the OEM private
+ * key is an ECC key, then |public_key_signature| is the ASN.1 DER-encoded (R,S)
+ * signature as specified in RFC 3279 2.2.3.
  *
  * @param[in] session: session id.
  * @param[out] public_key: pointer to the buffer that receives the public key
@@ -4877,11 +4920,8 @@ OEMCryptoResult OEMCrypto_GetBootCertificateChain(
  * @param[in,out] public_key_length: on input, size of the caller's public_key
  *    buffer. On output, the number of bytes written into the buffer.
  * @param[out] public_key_signature: pointer to the buffer that receives the
- *    signature of the public key.
- *    If an OEM private key is unavailable: it is signed by the device private
- *    key. The signature must be in COSE_SIGN1 format as specified in RFC 8152.
- *    If an OEM private key is available: it is signed by the OEM private key.
- *    The signature must be raw signature bytes.
+ *    signature of the public key. The format depends on whether an OEM private
+ *    key has been loaded.
  * @param[in,out] public_key_signature_length: on input, size of the caller's
  *    public_key_signature buffer. On output, the number of bytes written into
  *    the buffer.