widevine-partner/ce_cdm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Source release 18.5.0

Browse Source
This commit is contained in:
Matt Feddersen
2024-03-28 19:15:22 -07:00
parent b2c35151ad
commit 28ec8548c6
109 changed files with 3623 additions and 1012 deletions
Download Patch File Download Diff File Expand all files Collapse all files

236
oemcrypto/include/OEMCryptoCENC.h
View File

@@ -3,7 +3,7 @@
// License Agreement.
/**
* @mainpage OEMCrypto API v18.2
* @mainpage OEMCrypto API v18.5
*
* OEMCrypto is the low level library implemented by the OEM to provide key and
* content protection, usually in a separate secure memory or process space. The
@@ -136,6 +136,7 @@
* license to be reloaded.
*
* @defgroup entitled Entitlement License API
* Functions that are needed for entitled and entitlement licenses.
*
* [Entitlement licensing](../../index#entitlement) is a way to provide access
* to content keys that may be stored elsewhere, such as in the content itself.
@@ -366,7 +367,8 @@ typedef struct {
} OEMCrypto_CENCEncryptPatternDesc;
/**
* OEMCryptoCipherMode is used in SelectKey to prepare a key for decryption.
* OEMCryptoCipherMode is used in OEMCrypto_GetKeyHandle() to prepare a key for
* decryption.
*/
typedef enum OEMCryptoCipherMode {
// explicit cipher modes used for modular DRM
@@ -511,7 +513,9 @@ typedef enum OEMCrypto_ProvisioningMethod {
// Device has factory installed OEM certificate.
OEMCrypto_OEMCertificate = 3,
// Device has Boot Certificate Chain (BCC).
OEMCrypto_BootCertificateChain = 4
OEMCrypto_BootCertificateChain = 4,
// Device has baked in DRM certificate with reprovisioning (level 3 only).
OEMCrypto_DrmReprovisioning = 5
} OEMCrypto_ProvisioningMethod;
/**
@@ -712,6 +716,9 @@ typedef enum OEMCrypto_SignatureHashAlgorithm {
#define OEMCrypto_GetSignatureHashAlgorithm _oecc139
#define OEMCrypto_EnterTestMode _oecc140
#define OEMCrypto_GetDeviceSignedCsrPayload _oecc141
#define OEMCrypto_FactoryInstallBCCSignature _oecc142
#define OEMCrypto_GetEmbeddedDrmCertificate _oecc143
#define OEMCrypto_UseSecondaryKey _oecc144
// clang-format on
/// @addtogroup initcontrol
@@ -1198,6 +1205,8 @@ OEMCryptoResult OEMCrypto_GenerateNonce(OEMCrypto_SESSION session,
* @retval OEMCrypto_ERROR_BUFFER_TOO_LARGE
* @retval OEMCrypto_ERROR_SESSION_LOST_STATE
* @retval OEMCrypto_ERROR_SYSTEM_INVALIDATED
* @retval OEMCrypto_ERROR_INVALID_KEY if the session's private key is not a
* DRM key.
*
* @buffer_size
* OEMCrypto shall support message sizes as described in the section
@@ -1508,9 +1517,9 @@ OEMCryptoResult OEMCrypto_PrepAndSignRenewalRequest(
* Note: if the current SRM version requirement is not met, LoadLicense will
* still succeed and the keys will be loaded. However, those keys with the
* SRMVersionRequired bit set will have their HDCP_Version increased to 0xF -
* local display only. Any future call to SelectKey for these keys while
* there is an external display will return OEMCrypto_ERROR_INSUFFICIENT_HDCP
* at that time.
* local display only. Any future call to OEMCrypto_GetKeyHandle() for these
* keys while there is an external display will return
* OEMCrypto_ERROR_INSUFFICIENT_HDCP at that time.
*
* @param[in] session: crypto session identifier.
* @param[in] message: pointer to memory containing data.
@@ -1774,7 +1783,7 @@ OEMCryptoResult OEMCrypto_RemoveEntitledKeySession(
*
* For devices that use a hardware key ladder, it may be more convenient to
* store the encrypted content key data in the key table, and decrypt it when
* the function SelectKey is called.
* the function OEMCrypto_GetKeyHandle() is called.
*
* @param[in] session: handle for the entitled key session to be used.
* @param[in] message: pointer to memory containing message to be verified.
@@ -2000,8 +2009,8 @@ OEMCryptoResult OEMCrypto_GetOEMKeyToken(OEMCrypto_SESSION key_session,
* For platforms that do not need to support Bypass Decrypt, a mode compatible
* with previous versions of OEMCrypto is available. These devices may latch the
* key to the session and continue to use this key for this session until
* OEMCrypto_SelectKey() is called again, or until OEMCrypto_CloseSession() is
* called.
* OEMCrypto_GetKeyHandle() is called again, or until OEMCrypto_CloseSession()
* is called.
*
* The "key handle" in this mode is the session ID. Platforms should request a
* 4-byte key handle buffer and copy the session ID into it.
@@ -2014,13 +2023,13 @@ OEMCryptoResult OEMCrypto_GetOEMKeyToken(OEMCrypto_SESSION key_session,
* the device should disable analog video output. If the device has
* analog video output that cannot be disabled, then the key is not
* selected, and OEMCrypto_ERROR_ANALOG_OUTPUT is returned. This step is
* optional -- SelectKey may return OEMCrypto_SUCCESS and delay the
* error until a call to OEMCrypto_DecryptCENC().
* optional -- OEMCrypto_GetKeyHandle() may return OEMCrypto_SUCCESS and
* delay the error until a call to OEMCrypto_DecryptCENC().
* 3. If the key control block has HDCP required, and the device cannot
* enforce HDCP, then the key is not selected, and
* OEMCrypto_ERROR_INSUFFICIENT_HDCP is returned. This step is optional
* -- SelectKey may return OEMCrypto_SUCCESS and delay the error until a
* call to OEMCrypto_DecryptCENC().
* -- OEMCrypto_GetKeyHandle() may return OEMCrypto_SUCCESS and delay the
* error until a call to OEMCrypto_DecryptCENC().
* 4. If the key control block has a nonzero value for HDCP_Version, and
* the device cannot enforce at least that version of HDCP, then the key
* is not selected, and OEMCrypto_ERROR_INSUFFICIENT_HDCP is returned.
@@ -2090,9 +2099,9 @@ OEMCryptoResult OEMCrypto_GetKeyHandle(OEMCrypto_SESSION session,
* ISO-CENC standard.
*
* Decryption mode is AES-128-CTR or AES-128-CBC depending on the value of
* cipher_mode previously passed in to OEMCrypto_SelectKey(). For the encrypted
* portion of subsamples, the content key associated with the handle is
* latched in the active hardware key ladder and is used for the decryption
* cipher_mode previously passed in to OEMCrypto_GetKeyHandle(). For the
* encrypted portion of subsamples, the content key associated with the handle
* is latched in the active hardware key ladder and is used for the decryption
* operation. For the clear portion of subsamples, the data is simply copied.
*
* After decryption, all the input_data bytes are copied to the location
@@ -2190,8 +2199,8 @@ OEMCryptoResult OEMCrypto_GetKeyHandle(OEMCrypto_SESSION session,
*
* The decryption mode, either OEMCrypto_CipherMode_CENC or
* OEMCrypto_CipherMode_CBCS, was already specified in the call to
* OEMCrypto_SelectKey(). The encryption pattern is specified by the fields in
* the parameter pattern. A description of partial encryption patterns for
* OEMCrypto_GetKeyHandle(). The encryption pattern is specified by the fields
* in the parameter pattern. A description of partial encryption patterns for
* 'cbcs' can be found in the ISO-CENC standard, section 10.4.
*
* 'cenc' SCHEME:
@@ -2996,6 +3005,41 @@ OEMCryptoResult OEMCrypto_WrapKeyboxOrOEMCert(
OEMCryptoResult OEMCrypto_InstallKeyboxOrOEMCert(const uint8_t* keybox_or_cert,
size_t keybox_or_cert_length);
/**
* Install a factory generated signature for the BCC. This is for devices that
* use Provisioning 4.0, with the signing option in the factory. With the
* signing option, the BCC is extracted from the device in the factory. Instead
* of being uploaded to the Widevine server, the BCC is signed by a certificate
* that the manufacturer shares with Widevine. The signature is then installed
* on the device is a secure location. The signature must not be erased during
* factory reset.
*
* This signature should be returned as `addition_signature` in a call to the
* function `OEMCrypto_GetBootCertificateChain()`.
*
* Devices that do not support Provisioning 4.0, or only support Provisioning
* 4.0 Option 1 should return OEMCrypto_ERROR_NOT_IMPLEMENTED.
*
*
* @param[in] signature: pointer to data as input
* @param[in] signature_length: length of the data in bytes
*
* @retval OEMCrypto_SUCCESS success
* @retval OEMCrypto_ERROR_INSUFFICIENT_RESOURCES
* @retval OEMCrypto_ERROR_NOT_IMPLEMENTED
* @retval OEMCrypto_ERROR_SYSTEM_INVALIDATED
*
* @threading
* This is an "Initialization and Termination Function" and will not be
* called simultaneously with any other function, as if the CDM holds a write
* lock on the OEMCrypto system.
*
* @version
* This method is new in API version 18.3.
*/
OEMCryptoResult OEMCrypto_FactoryInstallBCCSignature(const uint8_t* signature,
size_t signature_length);
/**
* This function is for OEMCrypto to tell the layer above what provisioning
* method it uses: keybox or OEM certificate.
@@ -3319,6 +3363,8 @@ uint32_t OEMCrypto_MinorAPIVersion(void);
* different TA builds.
* - "build_timestamp" [string]: ISO 8601 formatted timestamp of the time the
* TA was compiled, eg "YYYY-MM-DDTHH:MM:SS"
* - "is_factory_mode" [bool]: Whether this was built with FACTORY_MODE_ONLY
* defined
*
* While not required, another optional top level struct can be added to the
* build information string to provide information about liboemcrypto.so:
@@ -3812,7 +3858,7 @@ OEMCryptoResult OEMCrypto_ProductionReady(void);
* the most recent license should be honored. The watermarking feature should
* be turned on or off when a license is loaded. If this conflicts with a
* license that had been loaded earlier, then keys from the earlier license may
* not be used. In this case, either OEMCrypto_SelectKey or
* not be used. In this case, either OEMCrypto_GetKeyHandle or
* OEMCrypto_DecryptCENC will return OEMCrypto_ERROR_INSUFFICIENT_PRIVILEGE to
* indicate that the watermarking status has changed and the license is no
* longer usable.
@@ -4838,6 +4884,7 @@ OEMCryptoResult OEMCrypto_GetBootCertificateChain(
* 4.4, as well as Android IRemotelyProvisionedComponent.aidl (under
* "SignedData<Data>")
*
* ~~~
* |public_key_signature|: COSE_Sign1 CBOR array
* [
* protected: bstr .cbor { 1 : AlgorithmEdDSA / AlgorithmES256 /
@@ -4847,6 +4894,7 @@ OEMCryptoResult OEMCrypto_GetBootCertificateChain(
* 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
@@ -4861,6 +4909,7 @@ OEMCryptoResult OEMCrypto_GetBootCertificateChain(
* field in Sig_structure is the same as the payload in the above
* COSE_Sign1 CBOR array.
*
* ~~~
* Sig_structure: CBOR array
* [
* context: "Signature1",
@@ -4869,6 +4918,7 @@ OEMCryptoResult OEMCrypto_GetBootCertificateChain(
* 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.
@@ -4877,6 +4927,19 @@ OEMCryptoResult OEMCrypto_GetBootCertificateChain(
* 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.
*
* After this function completes successfully, the session will hold a private
* key and will be ready for a call to
* OEMCrypto_PrepAndSignProvisioningRequest(). In particular, when this
* function is used to generate a DRM Certificate key pair, the session will be
* ready to sign a provisioning request with the DRM Cert private key. When this
* function is used to generate an OEM Certificate key pair, the session will be
* ready to sign a provisioning request with the OEM Cert private key.
*
* The public key shall be an ASN.1 DER-encoded SubjectPublicKeyInfo as
* specified in RFC 5280. Widevine recommends ECC keys for Provisioning 4.0, but
* an RSA key may also be used. If the key is an RSA key, then the encoding
* should use "rsaEncryption" (OID 1.2.840.113549.1.1.1), and not RSASSA-PSS.
*
* @param[in] session: session id.
* @param[out] public_key: pointer to the buffer that receives the public key
* that is to be certified by the server. The key must be an ASN.1
@@ -4920,7 +4983,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,
@@ -4929,7 +4994,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.
@@ -4955,24 +5022,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.
@@ -5121,14 +5251,13 @@ uint32_t OEMCrypto_SupportsDecryptHash(void);
* length of the hash will be at most 128 bytes, and will be 4 bytes (32
* bits) for the default CRC32 hash.
*
* This may be called before the first call to SelectKey. In that case, this
* function cannot verify that the key control block allows hash
* verification. The function DecryptCENC should verify that the key control
* bit allows hash verification when it is called. If an attempt is made to
* compute a hash when the selected key does not have the bit
* Allow_Hash_Verification set, then a hash should not be computed, and
* OEMCrypto_GetHashErrorCode() should return the error
* OEMCrypto_ERROR_UNKNOWN_FAILURE.
* This may be called before the first call to OEMCrypto_GetKeyHandle. In that
* case, this function cannot verify that the key control block allows hash
* verification. The function DecryptCENC should verify that the key control bit
* allows hash verification when it is called. If an attempt is made to compute
* a hash when the selected key does not have the bit Allow_Hash_Verification
* set, then a hash should not be computed, and OEMCrypto_GetHashErrorCode()
* should return the error OEMCrypto_ERROR_UNKNOWN_FAILURE.
*
* OEMCrypto should compute the hash of the frame and then compare it with
* the correct value. If the values differ, then OEMCrypto should latch in an
@@ -5255,7 +5384,7 @@ OEMCryptoResult OEMCrypto_AllocateSecureBuffer(
* will cause the unit test using secure buffers to fail.
*
* @param[in] session: session id for operation.
* @param[out] output_descriptor: the buffer descriptor modified by
* @param[in,out] output_descriptor: the buffer descriptor modified by
* OEMCrypto_AllocateSecureBuffer()
* @param[in] secure_fd: The integer returned by
* OEMCrypto_AllocateSecureBuffer()
@@ -5717,6 +5846,35 @@ OEMCryptoResult OEMCrypto_Generic_Verify_V17(
/****************************************************************************/
/****************************************************************************/
/* The following functions are used by internal L3 CDMs and are not required by
* other CDM implementations.
*/
/**
* Get the embedded Drm Certificate used by internal L3 CDMs.
*
* @param[out] public_cert where the certificate is stored.
* @param[in,out] public_cert_length the length, in bytes, of the certificate.
*
* @retval OEMCrypto_SUCCESS on success
* @retval OEMCrypto_ERROR_SHORT_BUFFER if public_cert_length is too small.
* @retval OEMCrypto_ERROR_NOT_IMPLEMENTED
*/
OEMCryptoResult OEMCrypto_GetEmbeddedDrmCertificate(uint8_t* public_cert,
size_t* public_cert_length);
/**
* Marks the given session as using a secondary key.
*
* @param[in] session_id: handle for the session to be used.
* @param[in] dual_key: whether this session uses a secondary key.
*
* @ignore
* @retval OEMCrypto_SUCCESS on success
* @retval OEMCrypto_ERROR_NOT_IMPLEMENTED
*/
OEMCryptoResult OEMCrypto_UseSecondaryKey(OEMCrypto_SESSION session_id,
bool dual_key);
#ifdef __cplusplus
}