/********************************************************************* * OEMCrypto.h * * (c) Copyright 2011-2012 Google, Inc. * * Reference APIs needed to support Widevine's crypto algorithms. *********************************************************************/ #ifndef WV_OEMCRYPTO_H_ #define WV_OEMCRYPTO_H_ #ifdef __cplusplus extern "C" { #endif #define OEMCRYPTO_VERSION "4.0" static const char oec_version[] = OEMCRYPTO_VERSION; typedef unsigned char OEMCrypto_UINT8; typedef char OEMCrypto_INT8; typedef unsigned long OEMCrypto_UINT32; typedef unsigned long OEMCrypto_SESSION; typedef enum OEMCryptoResult { OEMCrypto_SUCCESS = 0, OEMCrypto_ERROR_INIT_FAILED, OEMCrypto_ERROR_TERMINATE_FAILED, OEMCrypto_ERROR_OPEN_FAILURE, OEMCrypto_ERROR_CLOSE_FAILURE, OEMCrypto_ERROR_ENTER_SECURE_PLAYBACK_FAILED, OEMCrypto_ERROR_EXIT_SECURE_PLAYBACK_FAILED, OEMCrypto_ERROR_SHORT_BUFFER, OEMCrypto_ERROR_NO_DEVICE_KEY, OEMCrypto_ERROR_NO_ASSET_KEY, OEMCrypto_ERROR_KEYBOX_INVALID, OEMCrypto_ERROR_NO_KEYDATA, OEMCrypto_ERROR_NO_CW, OEMCrypto_ERROR_DECRYPT_FAILED, OEMCrypto_ERROR_WRITE_KEYBOX, OEMCrypto_ERROR_WRAP_KEYBOX, OEMCrypto_ERROR_BAD_MAGIC, OEMCrypto_ERROR_BAD_CRC, OEMCrypto_ERROR_NO_DEVICEID, OEMCrypto_ERROR_RNG_FAILED, OEMCrypto_ERROR_RNG_NOT_SUPPORTED, OEMCrypto_ERROR_SETUP, OEMCrypto_ERROR_OPEN_SESSION_FAILED, OEMCrypto_ERROR_CLOSE_SESSION_FAILED, OEMCrypto_ERROR_INVALID_SESSION, OEMCrypto_ERROR_NOT_IMPLEMENTED, OEMCrypto_ERROR_NO_CONTENT_KEY, OEMCrypto_ERROR_CONTROL_INVALID, OEMCrypto_ERROR_UNKNOWN_FAILURE, OEMCrypto_ERROR_INVALID_CONTEXT, OEMCrypto_ERROR_SIGNATURE_FAILURE } OEMCryptoResult; /* * OEMCrypto_DestBufferDesc * Describes the type and access information for the memory to receive * decrypted data. * * The OEMCrypto API supports a range of client device architectures. * Different architectures have different methods for acquiring and securing * buffers that will hold portions of the audio or video stream after * decryption. Three basic strategies are recognized for handling decrypted * stream data: * 1. Return the decrypted data in the clear into normal user memory * (ClearBuffer). The caller uses normal memory allocation methods to * acquire a buffer, and supplies the memory address of the buffer in the * descriptor. * 2. Place the decrypted data into protected memory (SecureBuffer). The * caller uses a platform-specific method to acquire the protected buffer * and a user-memory handle that references it. The handle is supplied * to the decrypt call in the descriptor. * 3. Place the decrypted data directly into the audio or video decoder fifo * (Direct). The caller will use platform-specific methods to initialize * the fifo and the decoders. The decrypted stream data is not accessible * to the caller. * * Specific fields are as follows: * * (type == OEMCrypto_BufferType_Clear) * address - Address of start of user memory buffer. * max_length - Size of user memory buffer. * (type == OEMCrypto_BufferType_Secure) * buffer - handle to a platform-specific secure buffer. * max_length - Size of platform-specific secure buffer. * (type == OEMCrypto_BufferType_Direct) * is_video - If true, decrypted bytes are routed to the video * decoder. If false, decrypted bytes are routed to the * audio decoder. */ typedef enum OEMCryptoBufferType { OEMCrypto_BufferType_Clear, OEMCrypto_BufferType_Secure, OEMCrypto_BufferType_Direct } OEMCrytoBufferType; typedef struct { OEMCryptoBufferType type; union { struct { // type == OEMCrypto_BufferType_Clear bool is_protected; OEMCrypto_UINT8* address; OEMCrypto_UINT32 max_length; } memory; struct { // type == OEMCrypto_BufferType_Secure void* handle; OEMCrypto_UINT32 max_length; } secure; struct { // type == OEMCrypto_BufferType_Direct bool is_video; } direct; } buffer; } OEMCrypto_DestBufferDesc; /* * OEMCrypto_KeyObject * Points to the relevant fields for a content key. The fields are extracted * from the License Response message offered to OEMCrypto_LoadKeys(). Each * field points to one of the components of the key. All fields are 128 bits * (16 bytes): * key_id - the unique id of this key. * key_data_iv - the IV for performing AES-128-CBC decryption of the * key_data field. * key_data - the key data. It is encrypted (AES-128-CBC) with the * session's derived encrypt key and the key_data_iv. * key_control_iv - the IV for performing AES-128-CBC decryption of the * key_control field. * key_control - the key control block. It is encrypted (AES-128-CBC) with * the content key from the key_data field. * * The memory for the OEMCrypto_KeyObject fields is allocated and freed * by the caller of OEMCrypto_LoadKeys(). */ typedef struct { const OEMCrypto_UINT8* key_id; const OEMCrypto_UINT8* key_data_iv; const OEMCrypto_UINT8* key_data; const OEMCrypto_UINT8* key_control_iv; const OEMCrypto_UINT8* key_control; } OEMCrypto_KeyObject; /* * OEMCrypto_KeyRefreshObject * Points to the relevant fields for renewing a content key. The fields are * extracted from the License Renewal Response message offered to * OEMCrypto_RefreshKeys(). Each field points to one of the components of * the key. All fields are 128 bits (16 bytes): * key_id - the unique id of this key. * key_control_iv - the IV for performing AES-128-CBC decryption of the * key_control field. * key_control - the key control block. It is encrypted (AES-128-CBC) with * the content key from the key_data field. * * The key_data is unchanged from the original OEMCrypto_LoadKeys() call. Some * Key Control Block fields, especially those related to key lifetime, may * change. * * The memory for the OEMCrypto_KeyRefreshObject fields is allocated and freed * by the caller of OEMCrypto_RefreshKeys(). */ typedef struct { const OEMCrypto_UINT8* key_id; const OEMCrypto_UINT8* key_control_iv; const OEMCrypto_UINT8* key_control; } OEMCrypto_KeyRefreshObject; #define OEMCrypto_Initialize _oec01 #define OEMCrypto_Terminate _oec02 #define OEMCrypto_SetEntitlementKey _oec03 #define OEMCrypto_DeriveControlWord _oec04 #define OEMCrypto_DecryptVideo _oec05 #define OEMCrypto_DecryptAudio _oec06 #define OEMCrypto_InstallKeybox _oec07 #define OEMCrypto_GetKeyData _oec08 #define OEMCrypto_IsKeyboxValid _oec09 #define OEMCrypto_GetRandom _oec10 #define OEMCrypto_GetDeviceID _oec11 #define OEMCrypto_EnterSecurePlayback _oec12 #define OEMCrypto_ExitSecurePlayback _oec13 #define OEMCrypto_WrapKeybox _oec14 #define OEMCrypto_OpenSession _oec15 #define OEMCrypto_CloseSession _oec16 #define OEMCrypto_SetContentKey _oec17 #define OEMCrypto_DecryptCTR _oec18 #define OEMCrypto_DecryptCTS _oec19 #define OEMCrypto_GenerateDerivedKeys _oec20 #define OEMCrypto_GenerateSignature _oec21 #define OEMCrypto_GenerateNonce _oec22 #define OEMCrypto_LoadKeys _oec23 #define OEMCrypto_RefreshKeys _oec24 #define OEMCrypto_SelectKey _oec25 /* * OEMCrypto_Initialize * * Description: * Initialize the crypto firmware/hardware. * * Parameters: * N/A * * Returns: * OEMCrypto_SUCCESS success * OEMCrypto_ERROR_INIT_FAILED failed to initialize crypto hardware */ OEMCryptoResult OEMCrypto_Initialize(void); /* * OEMCrypto_Terminate * * Description: * The API closes the crypto operation and releases all resources used. * * Parameters: * N/A * * Returns: * OEMCrypto_SUCCESS success * OEMCrypto_ERROR_TERMINATE_FAILED failed to de-initialize crypto hardware */ OEMCryptoResult OEMCrypto_Terminate(void); /* * OEMCrypto_OpenSession * * AES CTR Mode only, Levels 1 and 2 only * * Description: * The API provides for session based crypto initialization for AES CTR mode. * * Parameters: * session (out) - pointer to crypto session identifier. * * Returns: * OEMCrypto_SUCCESS success * OEMCrypto_ERROR_OPEN_SESSION_FAILED failed to initialize the crypto session */ OEMCryptoResult OEMCrypto_OpenSession(OEMCrypto_SESSION *session); /* * OEMCrypto_CloseSession * * AES CTR Mode only, Levels 1 and 2 only * * Description: * The API provides for session based crypto termination for AES CTR mode. * * Parameters: * session (in) - crypto session identifier. * * Returns: * OEMCrypto_SUCCESS success * OEMCrypto_ERROR_CLOSE_SESSION_FAILED failed to terminate the crypto session */ OEMCryptoResult OEMCrypto_CloseSession(OEMCrypto_SESSION session); /* * OEMCrypto_GenerateDerivedKeys * * AES CTR Mode only, Levels 1 and 2 only * * Description: * Generates a pair of secondary keys, mac_key and encrypt_key, for handling * signing and content key decryption under the license server protocol * for AES CTR mode. * * Refer to document "OEMCrypto Changes for V2 License Protocol" for details * * Parameters: * session (in) - crypto session identifier. * context (in) - pointer to memory containing context data for computing the * secondary keys. * context_length (in) - length of the context data. * * Returns: * OEMCrypto_SUCCESS success * OEMCrypto_ERROR_NO_DEVICE_KEY * OEMCrypto_ERROR_INVALID_SESSION * OEMCrypto_ERROR_UNKNOWN_FAILURE * OEMCrypto_ERROR_INVALID_CONTEXT */ OEMCryptoResult OEMCrypto_GenerateDerivedKeys( OEMCrypto_SESSION session, const OEMCrypto_UINT8 *context, OEMCrypto_UINT32 context_length); /* * OEMCrypto_GenerateNonce * * AES CTR Mode only, Levels 1 and 2 only * * Description: * Generates a 32-bit nonce to detect possible replay attack on the key * control block. * * Refer to documents "OEMCrypto Changes for V2 License Protocol" and "Key * Control Block Definition" for details. * * Parameters: * session (in) - crypto session identifier. * message (in) - pointer to memory containing message to be signed. * message_length (in) - length of the message. * signature (out) - pointer to memory to received the computed signature. * signature_length (in/out) - (in) length of the signature buffer. * (out) actual length of the signature * * Returns: * OEMCrypto_SUCCESS success * OEMCrypto_ERROR_NO_DEVICE_KEY * OEMCrypto_ERROR_INVALID_SESSION * OEMCrypto_ERROR_UNKNOWN_FAILURE * OEMCrypto_ERROR_INVALID_CONTEXT */ OEMCryptoResult OEMCrypto_GenerateNonce( OEMCrypto_SESSION session, OEMCrypto_UINT32* nonce); /* * OEMCrypto_GenerateSignature * * AES CTR Mode only, Levels 1 and 2 only * * Description: * Generates a HMAC-SHA256 signature for license request signing under the * license server protocol for AES CTR mode. * * NOTE: OEMCrypto_GenerateDerivedKeys() must be called first to establish the * mac_key * * Refer to document "OEMCrypto Changes for V2 License Protocol" for details. * * Parameters: * session (in) - crypto session identifier. * message (in) - pointer to memory containing message to be signed. * message_length (in) - length of the message. * signature (out) - pointer to memory to received the computed signature. * signature_length (in/out) - (in) length of the signature buffer. * (out) actual length of the signature * * Returns: * OEMCrypto_SUCCESS success * OEMCrypto_ERROR_NO_DEVICE_KEY * OEMCrypto_ERROR_INVALID_SESSION * OEMCrypto_ERROR_UNKNOWN_FAILURE * OEMCrypto_ERROR_INVALID_CONTEXT */ OEMCryptoResult OEMCrypto_GenerateSignature( OEMCrypto_SESSION session, const OEMCrypto_UINT8* message, OEMCrypto_UINT32 message_length, OEMCrypto_UINT8* signature, OEMCrypto_UINT32* signature_length); /* * OEMCrypto_LoadKeys * * AES CTR Mode only, Levels 1 and 2 only * * Description: * Installs a set of keys for performing decryption in the current session. * * The relevant fields have been extracted from the License Response protocol * message, but the entire message and associated signature are provided so * the message can be verified (using HMAC-SHA256 with the derived mac_key). * If the signature verification fails, ignore all other arguments and return * OEMCrypto_ERROR_SIGNATURE_FAILURE. Otherwise, add the keys to the session * context. * * The mac_key is encrypted with the current encrypt_key and the offered IV. * It replaces the mac_key created by OEMCrypto_GenerateDerivedkeys(). * * NOTE: OEMCrypto_GenerateDerivedKeys() must be called first to establish the * mac_key * * Refer to document "OEMCrypto Changes for V2 License Protocol" for details. * * Parameters: * session (in) - crypto session identifier. * message (in) - pointer to memory containing message to be verified. * message_length (in) - length of the message. * signature (in) - pointer to memory containing the signature. * signature_length (in) - length of the signature. * enc_mac_key_iv (in) - IV for decrypting new mac_key. Size is 128 bits. * enc_mac_key (in) - encrypted mac_key for generating new mac_key. Size is * 128 bits. * num_keys (in) - number of keys present. * key_array (in) - set of keys to be installed. * * Returns: * OEMCrypto_SUCCESS success * OEMCrypto_ERROR_NO_DEVICE_KEY * OEMCrypto_ERROR_INVALID_SESSION * OEMCrypto_ERROR_UNKNOWN_FAILURE * OEMCrypto_ERROR_INVALID_CONTEXT * OEMCrypto_ERROR_SIGNATURE_FAILURE */ OEMCryptoResult OEMCrypto_LoadKeys(OEMCrypto_SESSION session, const OEMCrypto_UINT8* message, OEMCrypto_UINT32 message_length, const OEMCrypto_UINT8* signature, OEMCrypto_UINT32 signature_length, const OEMCrypto_UINT8* enc_mac_key_iv, const OEMCrypto_UINT8* enc_mac_key, OEMCrypto_UINT32 num_keys, const OEMCrypto_KeyObject* key_array); /* * OEMCrypto_RefreshKeys * * AES CTR Mode only, Levels 1 and 2 only * * Description: * Updates an existing set of keys for continuing decryption in the * current session. * * The relevant fields have been extracted from the Renewal Response protocol * message, but the entire message and associated signature are provided so * the message can be verified (using HMAC-SHA256 with the current mac_key). * If the signature verification fails, ignore all other arguments and return * OEMCrypto_ERROR_SIGNATURE_FAILURE. Otherwise, add the keys to the session * context. * * NOTE: OEMCrypto_GenerateDerivedKeys() must be called first to establish * the mac_key * * Refer to document OEMCrypto Changes for V2 License Protocol for details. * * Parameters: * session (in) - crypto session identifier. * message (in) - pointer to memory containing message to be verified. * message_length (in) - length of the message. * signature (in) - pointer to memory containing the signature. * signature_length (in) - length of the signature. * num_keys (in) - number of keys present. * key_array (in) - set of keys to be installed. * * Returns: * OEMCrypto_SUCCESS success * OEMCrypto_ERROR_NO_DEVICE_KEY * OEMCrypto_ERROR_INVALID_SESSION * OEMCrypto_ERROR_UNKNOWN_FAILURE * OEMCrypto_ERROR_INVALID_CONTEXT * OEMCrypto_ERROR_SIGNATURE_FAILURE */ OEMCryptoResult OEMCrypto_RefreshKeys(OEMCrypto_SESSION session, const OEMCrypto_UINT8* message, OEMCrypto_UINT32 message_length, const OEMCrypto_UINT8* signature, OEMCrypto_UINT32 signature_length, OEMCrypto_UINT32 num_keys, const OEMCrypto_KeyRefreshObject* key_array); /* * OEMCrypto_EnterSecurePlayback * * Level 1 only * * Description: * Configures the security processor for secure decryption. This may involve * setting up firewall regions. It is called when the decrypt session for an * asset is established. * * For Non-Level1 API, return OEMCrypto_ERROR_NOT_IMPLEMENTED * * Parameters: * N/A * * Returns: * OEMCrypto_SUCCESS success * OEMCrypto_ERROR_ENTER_SECURE_PLAYBACK_FAILED */ OEMCryptoResult OEMCrypto_EnterSecurePlayback(void); /* * OEMCrypto_ExitSecurePlayback * * Level 1 only * * Description: * Exit the secure playback mode. This may involve releasing the firewall * regions. It is called when the decrypt session for an asset is closed. * * For Non-Level1 API, return OEMCrypto_ERROR_NOT_IMPLEMENTED * * Parameters: * N/A * * Returns: * OEMCrypto_SUCCESS success * OEMCrypto_ERROR_EXIT_SECURE_PLAYBACK_FAILED */ OEMCryptoResult OEMCrypto_ExitSecurePlayback(void); /* * OEMCrypto_SetEntitlementKey * * AES CTS Mode only, Levels 1 and 2 only * * Description: * Decrypt the entitlement (EMM) key, also known as the asset key, * using the encrypted device key (Device Key field) in the Widevine Keybox. * * Step 1: use the OEM root key to decrypt (AES-128-ECB) the Device Key * in the Keybox; latch the result in the hardware key ladder. * * Step 2: use the latched clear device key to decrypt (AES-128-ECB) * the entitlement key passed in as the *emmKey parameter. Latch * the resulting clear entitlement key in the key ladder for the * next operation. * * Parameters: * emmKey (in) - pointer to the encrypted entitlement key * emmKeyLength (in) - length of entitlement key in bytes * * Returns: * OEMCrypto_SUCCESS success * OEMCrypto_ERROR_NO_DEVICE_KEY failed to decrypt device key * OEMCrypto_ERROR_NO_ASSET_KEY failed to decrypt asset key * OEMCrypto_ERROR_KEYBOX_INVALID cannot decrypt and read from Keybox */ OEMCryptoResult OEMCrypto_SetEntitlementKey(const OEMCrypto_UINT8* emmKey, const OEMCrypto_UINT32 emmKeyLength); /* * OEMCrypto_DeriveControlWord * * AES CTS Mode only, Levels 1 and 2 only * * Description: * Using the active key ladder key from OEMCrypto_SetEntitlementKey(), * decrypt (AES-128-CBC, iv=0) the 32-byte ECM referenced by the *ecm * parameter; returns in *flags the first clear 4 bytes data. Latch the * clear bytes [4..20] as the clear control word for subsequent payload * decryption operation. * * Parameters: * ecm (in) - points to encrypted ECM data * length (in) - length of encrypted ECM data in bytes * flags (out) - points to buffer to receive 4 byte clear flag value * * Returns: * OEMCrypto_SUCCESS success * OEMCrypto_ERROR_NO_CW cannot decrypt control word */ OEMCryptoResult OEMCrypto_DeriveControlWord(const OEMCrypto_UINT8* ecm, const OEMCrypto_UINT32 length, OEMCrypto_UINT32* flags); /* * OEMCrypto_SetContentKey * * AES CTR Mode only, Levels 1 and 2 only * * For CDM implementations, this call is replaced by OEMCrypto_Loadkeys(), * and OEMCrypto_RefreshKeys(), and OEMCrypto_SelectKey() * * Description: * Place a new content key in the hardware key ladder for subsequent * decryption operations. Also accept control data and apply it to * configure the session. * * This operation is supported only while performing CTR mode decryption * (see OEMCrypto_DecryptCTR). * * Control data is associated with the session and the key, and is used * to configure the session context. If no control data is required, * controlLength will be zero, and control should be ignored. * * Currently, no control data is defined. ControlLength will be zero. * If controlLength is not zero, return OEMCrypto_ERROR_CONTROL_INVALID. * * Step 1: use the OEM root key to decrypt (AES-128-ECB) the Device Key * in the Widevine Keybox; latch the result in the hardware key * ladder. * * Step 2: use the latched clear device key to decrypt (AES-128-ECB) * the control parameter data. Verify the control data and apply * it to the current session. * * Step 2: use the latched clear device key to decrypt (AES-128-ECB) * the content key passed in as the *contentKey parameter. * Latch the resulting clear content key in the key ladder for * the next operation. * * Parameters: * session (in) - crypto session identifier * contentKey (in) - pointer to the encrypted content key * contentKeyLength (in) - length of content key in bytes * control (in) - pointer to server-supplied control information * controlLength (in) - length of control memory (bytes) * * Returns: * OEMCrypto_SUCCESS success * OEMCrypto_ERROR_INVALID_SESSION crypto session ID invalid or not open * OEMCrypto_ERROR_NO_DEVICE_KEY failed to decrypt device key * OEMCrypto_ERROR_NO_CONTENT_KEY failed to decrypt content key * OEMCrypto_ERROR_CONTROL_INVALID invalid or unsupported control input * OEMCrypto_ERROR_KEYBOX_INVALID cannot decrypt and read from Keybox */ OEMCryptoResult OEMCrypto_SetContentKey(const OEMCrypto_SESSION session, const OEMCrypto_UINT8* contentKey, const OEMCrypto_UINT32 contentKeyLength, const OEMCrypto_UINT8* control, const OEMCrypto_UINT32 controlLength); /* * OEMCrypto_SelectKey * * AES CTR Mode only, Levels 1 and 2 only (for CDM implementations) * * Description: * Select a content key and install it in the hardware key ladder for * subsequent decryption operations (OEMCrypto_DecryptCTR()). * * This operation is supported only while performing CTR mode decryption * (see OEMCrypto_DecryptCTR). The specified key must have been previously * "installed" via OEMCrypto_LoadKeys() or OEMCrypto_RefreshKeys(). * * A key control block is associated with the key and the session, and is used * to configure the session context. The Key Control data is documented in * "Key Control Block Definition". * * Step 1: Lookup the content key data via the offered key_id. The key data * includes the key value, the content key IV, the key control * block, and the key control block IV. * * Step 2: Lookup the encrypt_key (derived key). Latch the result in the * hardware key ladder. * * Step 3: use the encrypt_key to decrypt (AES-128-CBC) the content key data, * using the content key IV. Latch result in the hardware key ladder. * * Step 4: use the latched content key to decrypt (AES-128-CBC) the key * control block using the key control block IV. Verify the key * control block and apply it to the current session. * * Step 5: use the latched content key to decrypt (AES-128-CTR) * to decrypt buffers passed in via OEMCrypto_DecryptCTR(). Continue * to use this key until OEMCrypto_SelectKey() is called again, or * until OEMCrypto_CloseSession() is called. * * Parameters: * session (in) - crypto session identifier * key_id (in) - pointer to the Key ID * key_id_length (in) - length of the Key ID in bytes * * Returns: * OEMCrypto_SUCCESS success * OEMCrypto_ERROR_INVALID_SESSION crypto session ID invalid or not open * OEMCrypto_ERROR_NO_DEVICE_KEY failed to decrypt device key * OEMCrypto_ERROR_NO_CONTENT_KEY failed to decrypt content key * OEMCrypto_ERROR_CONTROL_INVALID invalid or unsupported control input * OEMCrypto_ERROR_KEYBOX_INVALID cannot decrypt and read from Keybox */ OEMCryptoResult OEMCrypto_SelectKey(const OEMCrypto_SESSION session, const OEMCrypto_UINT8* key_id, const OEMCrypto_UINT32 key_id_length); /* * OEMCrypto_DecryptVideo * * AES CTS Mode only, Levels 1 and 2 only * * Description: * * The API decrypts (AES-128-CBC) the video payload in the buffer referenced by * the *input parameter into the secure buffer referenced by the output * parameter, using the control word latched in the active hardware key * ladder. If inputLength is not a multiple of the crypto block size (16 bytes), * the API handles the residual bytes using CipherText Stealing (CTS). * * For Non-Level1 API, return OEMCrypto_ERROR_NOT_IMPLEMENTED * * Parameters: * iv (in/out) - If iv is NULL, then no decryption is required, i.e. the * packets are already clear. Otherwise, iv references the * AES initialization vector. Note that the updated IV after * processing the final crypto block must be passed back out in * *iv. * input (in) - buffer containing the encrypted data * inputLength (in) - number of bytes in the input payload. * output (in) - reference to the secure buffer which will receive the * decrypted data * outputLength (out) - number of bytes written into the secure buffer * * * Returns: * OEMCrypto_SUCCESS success * OEMCrypto_ERROR_DECRYPT_FAILED failed decryption */ OEMCryptoResult OEMCrypto_DecryptVideo(const OEMCrypto_UINT8* iv, const OEMCrypto_UINT8* input, const OEMCrypto_UINT32 inputLength, OEMCrypto_UINT32 output_handle, OEMCrypto_UINT32 output_offset, OEMCrypto_UINT32 *outputLength); /* * OEMCrypto_DecryptAudio * * AES CTS Mode only, Levels 1 and 2 only * * Description: * The API decrypts (AES-128-CBC) the audio payload in the buffer referenced * by the *input parameter into the non-secure buffer referenced by the output * parameter, using the control word latched in the active hardware key * ladder. If inputLength is not a multiple of the crypto block size (16 bytes), * the API handles the residual bytes using CipherText Stealing (CTS). * * OEMCrypto_DecryptAudio must make sure that it cannot be used to decrypt a * video stream into non-firewalled buffers, by verifying that no video * packets are processed. * * For Non-Level1 API, return OEMCrypto_ERROR_NOT_IMPLEMENTED * * Parameters: * iv (in/out) - If iv is NULL, then no decryption is required, i.e. the * packets are already clear. Otherwise, iv references the * AES initialization vector. Note that the updated IV after * processing the final crypto block must be passed back out * in *iv. * input (in) - buffer containing the encrypted data * inputLength (in) - number of bytes in the input payload. * output (in) - reference to the non-secure buffer which will receive the * decrypted data * outputLength (out) - number of bytes written into the non-secure buffer * * Returns: * OEMCrypto_SUCCESS success * OEMCrypto_ERROR_DECRYPT_FAILED failed decryption */ OEMCryptoResult OEMCrypto_DecryptAudio(const OEMCrypto_UINT8* iv, const OEMCrypto_UINT8* input, const OEMCrypto_UINT32 inputLength, OEMCrypto_UINT8 *output, OEMCrypto_UINT32 *outputLength); /* * OEMCrypto_DecryptCTR * * AES CTR Mode only, Levels 1 and 2 only * * Description: * * The API decrypts (AES-CTR) the payload in the buffer referenced by * the buffer_addr parameter into an internal buffer, using the key * identified by key_id. * * Parameters: * session (in) - crypto session identifier. * data_addr (in) - An unaligned pointer to this segment of the stream. * data_length (in) - The length of this segment of the stream. * is_encrypted (in) - True if the buffer described by data_addr, * data_length is encrypted. If is_encrypted is false, only the * data_addr and data_length parameters are used. The iv and offset * arguments are ignored. * iv (in) - The initial value block to be used for content decryption. * This is discussed further below. * offset (in) - If non-zero, the decryption block boundary is different * from the start of the data. offset should be subtracted from * data_addr to compute the starting address of the first decrypted * block. The bytes between the decryption block start address and * data_addr are discarded after decryption. * out_buffer (in) - A caller-owned descriptor that specifies the * handling of the decrypted byte stream. See OEMCrypto_DestbufferDesc * for details. * * AES CTR is a stream cipher. The stream may be composed of arbitrary- * length clear and encrypted segments. The encrypted portions of a sample * are collectively treated as a continuous sequence of decryption * block-sized blocks even though the sequence is interrupted by clear blocks. * This means a given encrypted segment may not start or end on a decryption * block boundary. * * If data_addr is not aligned with a decryption block boundary (offset != 0), * the additional offset bytes before data_addr (pre-padding) are included in * the decrypt operation, and they are dropped after decryption. If * data_length + offset is not a multiple of the decryption block size, the * extra bytes in the final decryption block (post-padding) are also dropped * after decryption. The caller is responsible for guaranteeing that all * memory addresses from (data-addr - pre-padding) to (data-addr + * data-length + post-padding) are valid memory addresses. * * After decrypting the entire buffer including any pre-padding and * post-padding, send data_length bytes starting at data_addr to the decoder. * * NOTES: * IV points to the counter value to be used for the initial * encrypted block of the input buffer. The IV length is the AES * block size. For subsequent encrypted AES blocks the IV is * calculated by incrementing the lower 64 bits (byte 8-15) of the * IV value used for the previous block. The counter rolls over to * zero when it reaches its maximum value (0xFFFFFFFFFFFFFFFF). * The upper 64 bits (byte 0-7) of the IV do not change. * * Returns: * OEMCrypto_SUCCESS * OEMCrypto_ERROR_NO_DEVICE_KEY * OEMCrypto_ERROR_INVALID_SESSION * OEMCrypto_ERROR_UNKNOWN_FAILURE * OEMCrypto_ERROR_INVALID_CONTEXT * OEMCrypto_ERROR_DECRYPT_FAILED */ OEMCryptoResult OEMCrypto_DecryptCTR(OEMCrypto_SESSION session_id, const OEMCrypto_UINT8 *data_addr, OEMCrypto_UINT32 data_length, bool is_encrypted, const OEMCrypto_UINT8 *iv, OEMCrypto_UINT32 offset, const OEMCrypto_DestBufferDesc* out_buffer); /* * OEMCrypto_InstallKeybox * * Description: * Unwrap and store the keybox to persistent memory. * The device key must be stored securely. The device key will be decrypted * and latched into hardware key ladder by OEMCrypto_SetEntitlementKey. * * This function is used once to load the keybox onto the device at * provisioning time. * * Parameters: * keybox (in) - Pointer to clear keybox data. Must have been originally * wrapped with OEMCrypto_WrapKeybox. * keyboxLength (in) - Length of the keybox data in bytes. * * Returns: * OEMCrypto_SUCCESS success * OEMCrypto_ERROR_WRITE_KEYBOX failed to handle and store Keybox */ OEMCryptoResult OEMCrypto_InstallKeybox(OEMCrypto_UINT8 *keybox, OEMCrypto_UINT32 keyBoxLength); /* * OEMCrypto_IsKeyboxValid * * Description: * Validate the Widevine Keybox stored on the device. * * The API performs two verification steps on the Keybox. It first verifies * the MAGIC field contains a valid signature (must be 'kbox'). The API then * computes the CRC using CRC-32 (Posix 1003.2 standard) and compares the * checksum to the CRC stored in the Keybox. The CRC is computed over the * entire Keybox excluding the 4 CRC bytes (i.e. Keybox[0..123]). * * Parameters: * none * * Returns: * OEMCrypto_SUCCESS * OEMCrypto_ERROR_BAD_MAGIC * OEMCrypto_ERROR_BAD_CRC */ OEMCryptoResult OEMCrypto_IsKeyboxValid(void); /* * OEMCrypto_GetDeviceID * * Description: * Retrieve the device's unique identifier from the Keybox. * * Parameters: * deviceId (out) - pointer to the buffer that receives the Device ID * idLength (in/out) - on input, size of the caller's device ID buffer. * On output, the number of bytes written into the buffer. * * Returns: * OEMCrypto_SUCCESS success * OEMCrypto_ERROR_SHORT_BUFFER buffer is too small to return the device ID * OEMCrypto_ERROR_NO_DEVICEID failed to return Device Id */ OEMCryptoResult OEMCrypto_GetDeviceID(OEMCrypto_UINT8* deviceID, OEMCrypto_UINT32 *idLength); /* * OEMCrypto_GetKeyData * * Description: * Returns the Key Data field from the Keybox. The Key Data field does not * need to be encrypted by an OEM root key, but may be if desired. * * If the Key Data field was encrypted with an OEM root key when the Keybox * was stored on the device, then this function should decrypt it and return * the clear Key Data. If the Key Data was not encrypted, then this function * should just access and return the clear Key data. * * Parameters: * keyData (out) - pointer to a caller-managed buffer to hold the Key Data * field from the Keybox * dataLength (in/out) - on input, the allocated buffer size. On output, * the number of bytes in KeyData. * * Returns: * OEMCrypto_SUCCESS success * OEMCrypto_ERROR_SHORT_BUFFER the buffer is too small to return the KeyData * OEMCrypto_ERROR_NO_KEYDATA failed to return KeyData */ OEMCryptoResult OEMCrypto_GetKeyData(OEMCrypto_UINT8* keyData, OEMCrypto_UINT32 *keyDataLength); /* * OEMCrypto_GetRandom * * Description: * Return a buffer filled with hardware-generated random bytes. If the * hardware feature does not exist, return OEMCrypto_ERROR_RNG_NOT_SUPPORTED. * * Parameters: * randomData (out) - Pointer to caller-manager buffer that will receive the * random data. * dataLength (in) - Length of the random data buffer in bytes. * * Returns: * OEMCrypto_SUCCESS success * OEMCrypto_ERROR_RNG_FAILED failed to generate random number * OEMCrypto_ERROR_RNG_NOT_SUPPORTED function not supported */ OEMCryptoResult OEMCrypto_GetRandom(OEMCrypto_UINT8* randomData, OEMCrypto_UINT32 dataLength); /* * OEMCrypto_WrapKeybox * * Description: * Wrap the Keybox with a key derived for the device key. If transportKey * is not NULL, the input keybox is encrypted with transportKey. If so, * decrypt the input keybox before wrapping it, using transportKey in AES-CBC * mode with an IV of all zeroes. * * Parameters: * keybox (in) - Pointer to keybox data. * keyboxLength - Length of the Keybox data in bytes * wrappedKeybox (out) - Pointer to wrapped keybox * wrappedKeyboxLength (out) - Pointer to the length of the wrapped keybox in * bytes * transportKey (in) - An optional AES transport key. If provided, the input * keybox is encrypted with this transport key with AES-CBC * and a null IV. * transportKeyLength - number of bytes in the transportKey * * Returns: * OEMCrypto_SUCCESS success * OEMCrypto_ERROR_WRAP_KEYBOX failed to wrap Keybox */ OEMCryptoResult OEMCrypto_WrapKeybox(OEMCrypto_UINT8 *keybox, OEMCrypto_UINT32 keyBoxLength, OEMCrypto_UINT8 *wrappedKeybox, OEMCrypto_UINT32 *wrappedKeyBoxLength, OEMCrypto_UINT8 *transportKey, OEMCrypto_UINT32 transportKeyLength); /* * OEMCrypto_DecryptCTS * * AES CTS Mode only, Level 2 only * * Description: * Decrypt the contents of the supplied buffer. * * This entry point is provided for compatibility with existing Level 2 * implementations. * * Parameters: * pSrcBuf (in) - Pointer to buffer of encrypted data * pDestBuf (in) - Pointer to buffer to receive decrypted data * length (in) - Length of the input/output buffers * bInitIvFlg (in) - Set to true to indicate that a new IV (all zeroes) * should be used. If false, the IV result from the * previous decryption should be use. * * Returns: * OEMCrypto_SUCCESS success * OEMCrypto_ERROR_DECRYPT_FAILED, */ OEMCryptoResult OEMCrypto_DecryptCTS(OEMCrypto_UINT8 *pSrcBuf, OEMCrypto_UINT8 *pDestBuf, const OEMCrypto_UINT32 length, const OEMCrypto_UINT8 bInitIvFlg); #ifdef __cplusplus } #endif #endif // WV_OEMCRYPTO_H_