Update documentation of OEMCrypto_GetDeviceSignedCsrPayload()

Clearify usage and paremeters of OEMCrypto_GetDeviceSignedCsrPayload()
and OEMCrypto_GetDeviceInformation().

Bug: 291625901
Merged from https://widevine-internal-review.googlesource.com/179470

Change-Id: I0c69bd6fadded6d749fd6f33553bb4a51d69e719

libwvdrmengine/oemcrypto/include/OEMCryptoCENC.h

@@ -4975,7 +4975,9 @@ OEMCryptoResult OEMCrypto_GenerateCertificateKeyPair(
     OEMCrypto_PrivateKeyType* key_type);
 
 /**
- * Get the serialized device information in CBOR map format.
+ * Get the serialized device information in CBOR map format. This is for devices
+ * that use Provisioning 4.0, with the device key uploading option in the
+ * factory.
  *
  * The device
  * information may contain, for example, device make and model, "fused" status,
@@ -4984,7 +4986,9 @@ OEMCryptoResult OEMCrypto_GenerateCertificateKeyPair(
  * provisioning request is coming from the expected device in the fields, based
  * on the values previously uploaded and registered.
  *
- * This method is used by provisioning 4 only.
+ * Devices that do not support Provisioning 4.0, or do not support
+ * Provisioning 4.0 Uploading Option should return
+ * OEMCrypto_ERROR_NOT_IMPLEMENTED.
  *
  * @param[out] device_info: pointer to the buffer that receives the serialized
  * device information in CBOR map format.
@@ -5010,24 +5014,87 @@ OEMCryptoResult OEMCrypto_GetDeviceInformation(uint8_t* device_info,
                                                size_t* device_info_length);
 
 /**
- * Get the serialized signed Certificate Signing Request (Csr) payload in
- * COSE_Sign1 format.
+ * Get the serialized signed Certificate Signing Request (CSR) payload in
+ * COSE_Sign1 format. This is for devices that use Provisioning 4.0, with the
+ * device key uploading option in the factory.
  *
- * The signed CSR payload contains challenge and device information. It is
- * signed by the leaf cert of the boot certificate chain (BCC). It is only used
- * in the factory, uploaded and validated during device registration.
+ * With the uploading option, the RKP factory extraction tool provided by Google
+ * makes a call to this function to collect the signed CSR payload for
+ * generating the CSR to be uploaded to the device database. The CSR payload is
+ * signed by the leaf cert of the Boot Certificate Chain.
  *
- * This method is used by provisioning 4 only.
+ * The format of a CSR payload before COSE_Sign1 is a CBOR array described in
+ * Android IRemotelyProvisionedComponent.aidl (under "CsrPayload"):
+ *
+ * ~~~
+ *   CsrPayload = [       ; CBOR Array defining the payload for CSR.
+ *     version: 3,        ; The CsrPayload CDDL Schema version.
+ *     CertificateType: "widevine"  ; The type of certificate being requested.
+ *     DeviceInfo,        ; Defined in Android DeviceInfo.aidl
+ *     KeysToSign: []     ; Empty list
+ *   ]
+ * ~~~
+ *
+ * The type of CertificateType is tstr and the value should always be
+ * "widevine". The type of KeysToSign is CBOR array and the value is not used,
+ * which should be left as an empty list. Note that the DeviceInfo above is a
+ * CBOR map structure defined in DeviceInfo.aidl, which can be constructed from
+ * the input |encoded_device_info|. DeviceInfo must be canonicalized according
+ * to the specification in RFC 7049. The required fields from DeviceInfo.aidl
+ * are: brand, manufacturer, product, model, device, vb_state, bootloader_state,
+ * vbmeta_digest, security_level.
+ *
+ * Once CsrPayload is prepared, together with |challenge| it is signed by the
+ * leaf cert of BCC, in the format of:
+ *
+ * ~~~
+ *   |signed_csr_payload| = SignedData<[
+ *     challenge: bstr .size (0..64),
+ *     bstr .cbor CsrPayload,
+ *   ]>
+ * ~~~
+ *
+ * This function should output |signed_csr_payload| in the format of
+ * SignedData<Data>, which is a COSE_Sign1 CBOR and is defined in Android
+ * IRemotelyProvisionedComponent.aidl (under "SignedData<Data>"):
+ *
+ * ~~~
+ *   SignedData<Data> = [
+ *     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)
+ *   ]
+ * ~~~
+ *
+ * Also see OEMCrypto_GenerateCertificateKeyPair() for more details of
+ * SignedData<Data> and Sig_structure.
+ *
+ * Data in the payload field of SignedData<Data> is a CBOR array:
+ *
+ * ~~~
+ *   Data = [
+ *     challenge: bstr .size (0..64),
+ *     bstr .cbor CsrPayload,
+ *   ]
+ * ~~~
+ *
+ * Devices that do not support Provisioning 4.0, or do not support
+ * Provisioning 4.0 Uploading Option should return
+ * OEMCrypto_ERROR_NOT_IMPLEMENTED.
  *
  * @param[in] challenge: pointer to the buffer containing a byte string to be
- * signed.
+ * signed. It is generated by the RKP factory extraction tool.
  * @param[in] challenge_length: size of the challenge buffer.
  * @param[in] encoded_device_info: pointer to the buffer containing the
- * serialized device information in CBOR map format.
+ * serialized device information in CBOR map format. It should be returned as
+ * `device_info` in a call to the function `OEMCrypto_GetDeviceInformation()`.
  * @param[in] encoded_device_info_length: size of the encoded_device_info
  * buffer.
  * @param[out] signed_csr_payload: pointer to the buffer that receives the
- * serialized CSR payload in COSE_Sign1 format.
+ * serialized signed CSR payload in COSE_Sign1 format.
  * @param[in,out] signed_csr_payload_length: on input, size of the caller's
  * signed_csr_payload buffer. On output, the number of bytes written into the
  * buffer.