From dafd837420c9a3129de270f58284db0f75b4b620 Mon Sep 17 00:00:00 2001 From: Cong Lin Date: Mon, 24 Jul 2023 22:51:38 -0700 Subject: [PATCH] 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 --- .../oemcrypto/include/OEMCryptoCENC.h | 89 ++++++++++++++++--- 1 file changed, 78 insertions(+), 11 deletions(-) diff --git a/libwvdrmengine/oemcrypto/include/OEMCryptoCENC.h b/libwvdrmengine/oemcrypto/include/OEMCryptoCENC.h index 66f243d1..4422370c 100644 --- a/libwvdrmengine/oemcrypto/include/OEMCryptoCENC.h +++ b/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, which is a COSE_Sign1 CBOR and is defined in Android + * IRemotelyProvisionedComponent.aidl (under "SignedData"): + * + * ~~~ + * SignedData = [ + * 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 and Sig_structure. + * + * Data in the payload field of SignedData 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.