901 lines
38 KiB
C
901 lines
38 KiB
C
// Copyright 2019 Google LLC. This file and proprietary
|
|
// source code may only be used and distributed under the Widevine
|
|
// License Agreement.
|
|
|
|
/**
|
|
* @mainpage OEMCrypto v16 Core Message Serialization library
|
|
*
|
|
* For Widevine Modular DRM, there are six message types between a server and
|
|
* a client device: license request and response, provisioning request and
|
|
* response, and renewal request and response.
|
|
*
|
|
* In OEMCrypto v15 and earlier, messages from the server were parsed by the
|
|
* CDM layer above OEMCrypto; the CDM in turn gave OEMCrypto a collection of
|
|
* pointers to protected data within the message. However, the pointers
|
|
* themselves were not signed by the server.
|
|
*
|
|
* Starting from OEMCrypto v16, all fields used by OEMCrypto in each of these
|
|
* messages have been identified in the document "Widevine Core Message
|
|
* Serialization". These fields are called the core of the message. Core
|
|
* message fields are (de)serialized using the ODK, a C library provided by
|
|
* Widevine. OEMCrypto will parse and verify the core of the message with
|
|
* help from the ODK.
|
|
*
|
|
* The ODK functions that parse code will fill out structs that have similar
|
|
* formats to the function parameters of the OEMCrypto v15 functions being
|
|
* replaced. The ODK will be provided in source code and it is Widevine's
|
|
* intention that partners can build and link ODK with their implementation
|
|
* of OEMCrypto with no or few code changes.
|
|
*
|
|
* OEMCrypto implementers shall build the ODK library as part of the Trusted
|
|
* Application (TA) running in the TEE. All memory and buffers used by the
|
|
* ODK library shall be sanitized by the OEMCrypto implementer to prevent
|
|
* modification by any process running the REE.
|
|
*
|
|
* See the documents
|
|
* <a href="../odk">Widevine Core Message Serialization</a>
|
|
* and
|
|
* <a href="../../lic_duration_and_renewal">License Duration and Renewal</a>
|
|
* for a detailed description of the ODK API. You can
|
|
* find these documents in the widevine repository as
|
|
* docs/Widevine_Core_Message_Serialization.pdf and
|
|
* docs/License_Duration_and_Renewal.pdf
|
|
*
|
|
* @defgroup odk_parser Core Message Parsing and Verification
|
|
* Functions that parse core messages and verify they are valid.
|
|
* TODO(fredgc): add documentation for parsing functions.
|
|
*
|
|
* @defgroup odk_packer Core Message Creation
|
|
* Functions that create core messages.
|
|
* TODO(fredgc): add documentation for packing functions.
|
|
*
|
|
* @defgroup odk_timer Timer and Clock Functions
|
|
* Functions related to enforcing timer and duration restrictions.
|
|
* TODO(fredgc): add documentation for timers and clocks.
|
|
*
|
|
* @defgroup common_types Common Types
|
|
* Enumerations and structures that are used by several OEMCrypto and ODK
|
|
*
|
|
* @defgroup odk_derivation Key Derivation Utils
|
|
* Utilities and constants relating to key derivation.
|
|
* functions.
|
|
*********************************************************************/
|
|
|
|
#ifndef WIDEVINE_ODK_INCLUDE_ODK_H_
|
|
#define WIDEVINE_ODK_INCLUDE_ODK_H_
|
|
|
|
#include <stdint.h>
|
|
|
|
#include "OEMCryptoCENCCommon.h"
|
|
#include "odk_structs.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/// @addtogroup odk_timer
|
|
/// @{
|
|
|
|
/**
|
|
* This function initializes the session's data structures. It shall be
|
|
* called from OEMCrypto_OpenSession.
|
|
*
|
|
* @param[out] timer_limits: the session's timer limits.
|
|
* @param[out] clock_values: the session's clock values.
|
|
* @param[out] nonce_values: the session's ODK nonce values.
|
|
* @param[in] api_major_version: the API version of OEMCrypto.
|
|
* @param[in] session_id: the session id of the newly created session.
|
|
*
|
|
* @retval OEMCrypto_SUCCESS
|
|
* @retval OEMCrypto_ERROR_INVALID_CONTEXT
|
|
*
|
|
* @version
|
|
* This method is new in version 16 of the API.
|
|
*/
|
|
OEMCryptoResult ODK_InitializeSessionValues(ODK_TimerLimits* timer_limits,
|
|
ODK_ClockValues* clock_values,
|
|
ODK_NonceValues* nonce_values,
|
|
uint32_t api_major_version,
|
|
uint32_t session_id);
|
|
|
|
/**
|
|
* This function sets the nonce value in the session's nonce structure. It
|
|
* shall be called from OEMCrypto_GenerateNonce.
|
|
*
|
|
* @param[in,out] nonce_values: the session's nonce data.
|
|
* @param[in] nonce: the new nonce that was just generated.
|
|
*
|
|
* @retval true on success
|
|
*
|
|
* @version
|
|
* This method is new in version 16 of the API.
|
|
*/
|
|
OEMCryptoResult ODK_SetNonceValues(ODK_NonceValues* nonce_values,
|
|
uint32_t nonce);
|
|
|
|
/**
|
|
* This function initializes the clock values in the session clock_values
|
|
* structure. It shall be called from OEMCrypto_PrepAndSignLicenseRequest.
|
|
*
|
|
* Parameters:
|
|
* @param[in,out] clock_values: the session's clock data.
|
|
* @param[in] system_time_seconds: the current time on OEMCrypto's monotonic
|
|
* clock.
|
|
*
|
|
* @retval OEMCrypto_SUCCESS
|
|
* @retval OEMCrypto_ERROR_INVALID_CONTEXT
|
|
*
|
|
* @version
|
|
* This method is new in version 16 of the API.
|
|
*/
|
|
OEMCryptoResult ODK_InitializeClockValues(ODK_ClockValues* clock_values,
|
|
uint64_t system_time_seconds);
|
|
|
|
/**
|
|
* This function sets the values in the clock_values structure. It shall be
|
|
* called from OEMCrypto_LoadUsageEntry. When a usage entry from a v15 or
|
|
* earlier license is loaded, the value time_of_license_loaded shall be used
|
|
* in place of time_of_license_request_signed.
|
|
*
|
|
* @param[in,out] clock_values: the session's clock data.
|
|
* @param[in] time_of_license_request_signed: the value time_license_received
|
|
* from the loaded usage entry.
|
|
* @param[in] time_of_first_decrypt: the value time_of_first_decrypt from the
|
|
* loaded usage entry.
|
|
* @param[in] time_of_last_decrypt: the value time_of_last_decrypt from the
|
|
* loaded usage entry.
|
|
* @param[in] status: the value status from the loaded usage entry.
|
|
* @param[in] system_time_seconds: the current time on OEMCrypto's monotonic
|
|
* clock.
|
|
*
|
|
* @retval OEMCrypto_SUCCESS
|
|
* @retval OEMCrypto_ERROR_INVALID_CONTEXT
|
|
*
|
|
* @version
|
|
* This method is new in version 16 of the API.
|
|
*/
|
|
OEMCryptoResult ODK_ReloadClockValues(ODK_ClockValues* clock_values,
|
|
uint64_t time_of_license_request_signed,
|
|
uint64_t time_of_first_decrypt,
|
|
uint64_t time_of_last_decrypt,
|
|
enum OEMCrypto_Usage_Entry_Status status,
|
|
uint64_t system_time_seconds);
|
|
|
|
/**
|
|
* This updates the clock values, and determines if playback may start based
|
|
* on the given system time. It uses the values in clock_values to determine
|
|
* if this is the first playback for the license or the first playback for
|
|
* just this session.
|
|
*
|
|
* This shall be called from the first call in a session to any of
|
|
* OEMCrypto_DecryptCENC or any of the OEMCrypto_Generic* functions.
|
|
*
|
|
* If OEMCrypto uses a hardware timer, and this function returns
|
|
* ODK_SET_TIMER, then the timer should be set to the value pointed to by
|
|
* timer_value.
|
|
*
|
|
* @param[in] system_time_seconds: the current time on OEMCrypto's monotonic
|
|
* clock, in seconds.
|
|
* @param[in] timer_limits: timer limits specified in the license.
|
|
* @param[in,out] clock_values: the sessions clock values.
|
|
* @param[out] timer_value: set to the new timer value. Only used if the return
|
|
* value is ODK_SET_TIMER. This must be non-null if OEMCrypto uses a
|
|
* hardware timer.
|
|
*
|
|
* @retval ODK_SET_TIMER: Success. The timer should be reset to the specified
|
|
* value and playback is allowed.
|
|
* @retval ODK_DISABLE_TIMER: Success, but disable timer. Unlimited playback is
|
|
* allowed.
|
|
* @retval ODK_TIMER_EXPIRED: Set timer as disabled. Playback is not allowed.
|
|
*
|
|
* @version
|
|
* This method is new in version 16 of the API.
|
|
*/
|
|
OEMCryptoResult ODK_AttemptFirstPlayback(uint64_t system_time_seconds,
|
|
const ODK_TimerLimits* timer_limits,
|
|
ODK_ClockValues* clock_values,
|
|
uint64_t* timer_value);
|
|
|
|
/**
|
|
* Vendors that do not implement their own timer should call
|
|
* ODK_UpdateLastPlaybackTime regularly during playback. This updates the
|
|
* clock values, and determines if playback may continue based on the given
|
|
* system time. This shall be called from any of OEMCrypto_DecryptCENC or any
|
|
* of the OEMCrypto_Generic* functions.
|
|
*
|
|
* All Vendors (i.e. those that do or do not implement their own timer) shall
|
|
* call ODK_UpdateLastPlaybackTime from the function
|
|
* OEMCrypto_UpdateUsageEntry before updating the usage entry so that the
|
|
* clock values are accurate.
|
|
*
|
|
* @param[in] system_time_seconds: the current time on OEMCrypto's monotonic
|
|
* clock, in seconds.
|
|
* @param[in] timer_limits: timer limits specified in the license.
|
|
* @param[in,out] clock_values: the sessions clock values.
|
|
*
|
|
* @retval OEMCrypto_SUCCESS: Success. Playback is allowed.
|
|
* @retval ODK_TIMER_EXPIRED: Set timer as disabled. Playback is not allowed.
|
|
*
|
|
* @version
|
|
* This method is new in version 16 of the API.
|
|
*/
|
|
OEMCryptoResult ODK_UpdateLastPlaybackTime(uint64_t system_time_seconds,
|
|
const ODK_TimerLimits* timer_limits,
|
|
ODK_ClockValues* clock_values);
|
|
|
|
/**
|
|
* This function modifies the session's clock values to indicate that the
|
|
* license has been deactivated. It shall be called from
|
|
* OEMCrypto_DeactivateUsageEntry
|
|
*
|
|
* Parameters:
|
|
* @param[in,out] clock_values: the sessions clock values.
|
|
*
|
|
* @retval OEMCrypto_SUCCESS
|
|
* @retval OEMCrypto_ERROR_INVALID_CONTEXT
|
|
*
|
|
* @version
|
|
* This method is new in version 16 of the API.
|
|
*/
|
|
OEMCryptoResult ODK_DeactivateUsageEntry(ODK_ClockValues* clock_values);
|
|
|
|
/// @}
|
|
|
|
/// @addtogroup odk_packer
|
|
/// @{
|
|
|
|
/**
|
|
* Modifies the message to include a core license request at the beginning of
|
|
* the message buffer. The values in nonce_values are used to populate the
|
|
* message.
|
|
*
|
|
* This shall be called by OEMCrypto from OEMCrypto_PrepAndSignLicenseRequest.
|
|
*
|
|
* NOTE: if the message pointer is null and/or input core_message_size is
|
|
* zero, this function returns OEMCrypto_ERROR_SHORT_BUFFER and sets output
|
|
* core_message_size to the size needed.
|
|
*
|
|
* @param[in,out] message: Pointer to memory for the entire message. Modified by
|
|
* the ODK library.
|
|
* @param[in] message_length: length of the entire message buffer.
|
|
* @param[in,out] core_message_size: length of the core message at the beginning
|
|
* of the message. (in) size of buffer reserved for the core message, in
|
|
* bytes. (out) actual length of the core message, in bytes.
|
|
* @param[in] nonce_values: pointer to the session's nonce data.
|
|
* @param[in] message_count_info: information used for server-side anomaly
|
|
* detection
|
|
*
|
|
* @retval OEMCrypto_SUCCESS
|
|
* @retval OEMCrypto_ERROR_SHORT_BUFFER: core_message_size is too small
|
|
* @retval OEMCrypto_ERROR_INVALID_CONTEXT
|
|
*
|
|
* @version
|
|
* This method is new in version 16 of the API.
|
|
*/
|
|
OEMCryptoResult ODK_PrepareCoreLicenseRequest(
|
|
uint8_t* message, size_t message_length, size_t* core_message_size,
|
|
const ODK_NonceValues* nonce_values,
|
|
const ODK_MessageCounterInfo* counter_info);
|
|
|
|
/**
|
|
* Modifies the message to include a core license release at the beginning of
|
|
* the message buffer. The values in nonce_values are used to populate the
|
|
* message.
|
|
*
|
|
* This shall be called by OEMCrypto from OEMCrypto_PrepAndSignLicenseRelease.
|
|
*
|
|
* NOTE: if the message pointer is null and/or input core_message_size is
|
|
* zero, this function returns OEMCrypto_ERROR_SHORT_BUFFER and sets output
|
|
* core_message_size to the size needed.
|
|
*
|
|
* @param[in,out] message: Pointer to memory for the entire message. Modified by
|
|
* the ODK library.
|
|
* @param[in] message_length: length of the entire message buffer.
|
|
* @param[in,out] core_message_size: length of the core message at the beginning
|
|
* of the message. (in) size of buffer reserved for the core message, in
|
|
* bytes. (out) actual length of the core message, in bytes.
|
|
* @param[in] nonce_values: pointer to the session's nonce data.
|
|
* @param[in] status: the enumeration of OEMCrypto_Usage_Entry_Status
|
|
* @param[in] clock_security_level: the enumeration of
|
|
* OEMCryto_Clock_Security_Level
|
|
* @param[in] seconds_since_license_requested: the time between the license
|
|
* being requested and the release being generated in seconds
|
|
* @param[in] seconds_since_first_decrypt: The time since playback has started
|
|
* in seconds
|
|
* @param[in,out] clock_values: the session's clock values.
|
|
* @param[in] system_time_seconds: the current time on OEMCrypto's clock, in
|
|
* seconds.
|
|
*
|
|
* @retval OEMCrypto_SUCCESS
|
|
* @retval OEMCrypto_ERROR_SHORT_BUFFER: core_message_size is too small
|
|
* @retval OEMCrypto_ERROR_INVALID_CONTEXT
|
|
*
|
|
* @version
|
|
* This method is new in version 19 of the API.
|
|
*/
|
|
OEMCryptoResult ODK_PrepareCoreReleaseRequest(
|
|
uint8_t* message, size_t message_length, size_t* core_message_size,
|
|
ODK_NonceValues* nonce_values, uint32_t status,
|
|
uint32_t clock_security_level, int64_t seconds_since_license_requested,
|
|
int64_t seconds_since_first_decrypt, ODK_ClockValues* clock_values,
|
|
uint64_t system_time_seconds);
|
|
|
|
/**
|
|
* Modifies the message to include a core renewal request at the beginning of
|
|
* the message buffer. The values in nonce_values, clock_values and
|
|
* system_time_seconds are used to populate the message. The nonce_values
|
|
* should match those from the license.
|
|
*
|
|
* This shall be called by OEMCrypto from OEMCrypto_PrepAndSignRenewalRequest.
|
|
*
|
|
* If status in clock_values indicates that a license has not been loaded,
|
|
* then this is a license release. The ODK library will change the value of
|
|
* nonce_values.api_major_version to 15. This will make
|
|
* OEMCrypto_PrepAndSignRenewalRequest sign just the message body, as it does
|
|
* for all legacy licenses.
|
|
*
|
|
* NOTE: if the message pointer is null and/or input core_message_size is
|
|
* zero, this function returns OEMCrypto_ERROR_SHORT_BUFFER and sets output
|
|
* core_message_size to the size needed.
|
|
*
|
|
* @param[in,out] message: Pointer to memory for the entire message. Modified by
|
|
* the ODK library.
|
|
* @param[in] message_length: length of the entire message buffer.
|
|
* @param[in,out] core_message_size: length of the core message at the beginning
|
|
* of the message. (in) size of buffer reserved for the core message, in
|
|
* bytes. (out) actual length of the core message, in bytes.
|
|
* @param[in,out] nonce_values: pointer to the session's nonce data.
|
|
* @param[in,out] clock_values: the session's clock values.
|
|
* @param[in] system_time_seconds: the current time on OEMCrypto's clock, in
|
|
* seconds.
|
|
*
|
|
* @retval OEMCrypto_SUCCESS
|
|
* @retval OEMCrypto_ERROR_SHORT_BUFFER: core_message_size is too small
|
|
* @retval OEMCrypto_ERROR_INVALID_CONTEXT
|
|
*
|
|
* @version
|
|
* This method is new in version 16 of the API.
|
|
*/
|
|
OEMCryptoResult ODK_PrepareCoreRenewalRequest(uint8_t* message,
|
|
size_t message_length,
|
|
size_t* core_message_size,
|
|
ODK_NonceValues* nonce_values,
|
|
ODK_ClockValues* clock_values,
|
|
uint64_t system_time_seconds);
|
|
|
|
/**
|
|
* Modifies the message to include a core provisioning request at the
|
|
* beginning of the message buffer. The values in nonce_values are used to
|
|
* populate the message.
|
|
*
|
|
* This shall be called by OEMCrypto from
|
|
* OEMCrypto_PrepAndSignProvisioningRequest.
|
|
*
|
|
* The buffer device_id shall be the same string returned by
|
|
* OEMCrypto_GetDeviceID. The device ID shall be unique to the device, and
|
|
* stable across reboots and factory resets for an L1 device.
|
|
*
|
|
* NOTE: if the message pointer is null and/or input core_message_length is
|
|
* zero, this function returns OEMCrypto_ERROR_SHORT_BUFFER and sets output
|
|
* core_message_size to the size needed.
|
|
*
|
|
* @param[in,out] message: Pointer to memory for the entire message. Modified by
|
|
* the ODK library.
|
|
* @param[in] message_length: length of the entire message buffer.
|
|
* @param[in,out] core_message_size: length of the core message at the beginning
|
|
* of the message. (in) size of buffer reserved for the core message, in
|
|
* bytes. (out) actual length of the core message, in bytes.
|
|
* @param[in] nonce_values: pointer to the session's nonce data.
|
|
* @param[in] counter_info: information used for server-side anomaly
|
|
* detection
|
|
*
|
|
* @retval OEMCrypto_SUCCESS
|
|
* @retval OEMCrypto_ERROR_SHORT_BUFFER: core_message_size is too small
|
|
* @retval OEMCrypto_ERROR_INVALID_CONTEXT
|
|
*
|
|
* @version
|
|
* This method is new in version 16 of the API.
|
|
*/
|
|
OEMCryptoResult ODK_PrepareCoreProvisioningRequest(
|
|
uint8_t* message, size_t message_length, size_t* core_message_length,
|
|
const ODK_NonceValues* nonce_values,
|
|
const ODK_MessageCounterInfo* counter_info);
|
|
|
|
/**
|
|
* Modifies the message to include a core provisioning 4.0 request at the
|
|
* beginning of the message buffer. The values in nonce_values are used to
|
|
* populate the message.
|
|
*
|
|
* This shall be called by OEMCrypto from
|
|
* OEMCrypto_PrepAndSignProvisioningRequest.
|
|
*
|
|
* NOTE: if the message pointer is null and/or input core_message_length is
|
|
* zero, this function returns OEMCrypto_ERROR_SHORT_BUFFER and sets output
|
|
* core_message_size to the size needed.
|
|
*
|
|
* @param[in,out] message: Pointer to memory for the entire message. Modified by
|
|
* the ODK library.
|
|
* @param[in] message_length: length of the entire message buffer.
|
|
* @param[in,out] core_message_size: length of the core message at the beginning
|
|
* of the message. (in) size of buffer reserved for the core message, in
|
|
* bytes. (out) actual length of the core message, in bytes.
|
|
* @param[in] nonce_values: pointer to the session's nonce data.
|
|
* @param[in] device_info: Encoded device hardware info in CBOR format.
|
|
* @param[in] device_info_length: length of device_info.
|
|
* @param[in] message_count_info: information used for server-side anomaly
|
|
* detection
|
|
*
|
|
* @retval OEMCrypto_SUCCESS
|
|
* @retval OEMCrypto_ERROR_SHORT_BUFFER: core_message_size is too small
|
|
* @retval OEMCrypto_ERROR_INVALID_CONTEXT
|
|
*
|
|
* @version
|
|
* This method is new in version 18 of the API.
|
|
*/
|
|
OEMCryptoResult ODK_PrepareCoreProvisioning40Request(
|
|
uint8_t* message, size_t message_length, size_t* core_message_length,
|
|
const ODK_NonceValues* nonce_values, const uint8_t* device_info,
|
|
size_t device_info_length, const ODK_MessageCounterInfo* counter_info);
|
|
|
|
/**
|
|
* Modifies the message to include a core renewal provisioning request at the
|
|
* beginning of the message buffer. The values in nonce_values are used to
|
|
* populate the message.
|
|
*
|
|
* This shall be called by OEMCrypto from
|
|
* OEMCrypto_PrepAndSignProvisioningRequest.
|
|
*
|
|
* The buffer device_id shall be the same string returned by
|
|
* OEMCrypto_GetDeviceID. The device ID shall be unique to the device, and
|
|
* stable across reboots and factory resets for an L1 device.
|
|
*
|
|
* NOTE: if the message pointer is null and/or input core_message_length is
|
|
* zero, this function returns OEMCrypto_ERROR_SHORT_BUFFER and sets output
|
|
* core_message_size to the size needed.
|
|
*
|
|
* @param[in,out] message: pointer to memory for the entire message. Modified by
|
|
* the ODK library.
|
|
* @param[in] message_length: length of the entire message buffer.
|
|
* @param[in,out] core_message_size: length of the core message at the beginning
|
|
* of the message. (in) size of buffer reserved for the core message, in
|
|
* bytes. (out) actual length of the core message, in bytes.
|
|
* @param[in] nonce_values: pointer to the session's nonce data.
|
|
* @param[in] device_id: For devices with a keybox, this is the device ID from
|
|
* the keybox. For devices with an OEM Certificate, this is a device
|
|
* unique id string.
|
|
* @param[in] device_id_length: length of device_id. The device ID can be at
|
|
* most 64 bytes.
|
|
* @param[in] renewal_type: type of renewal used
|
|
* @param[in] renewal_data: renewal data used. For renewal_type = 1,
|
|
* renewal_data is the Android attestation batch certificate.
|
|
* @param[in] renewal_data_length: length of renewal_data
|
|
*
|
|
* @retval OEMCrypto_SUCCESS
|
|
* @retval OEMCrypto_ERROR_SHORT_BUFFER: core_message_size is too small
|
|
* @retval OEMCrypto_ERROR_INVALID_CONTEXT
|
|
*
|
|
* @version
|
|
* This method is new in version 17 of the API.
|
|
*/
|
|
OEMCryptoResult ODK_PrepareCoreRenewedProvisioningRequest(
|
|
uint8_t* message, size_t message_length, size_t* core_message_length,
|
|
const ODK_NonceValues* nonce_values, const uint8_t* device_id,
|
|
size_t device_id_length, uint16_t renewal_type, const uint8_t* renewal_data,
|
|
size_t renewal_data_length);
|
|
|
|
/// @}
|
|
|
|
/// @addtogroup odk_timer
|
|
/// @{
|
|
|
|
/**
|
|
* This function sets all limits in the timer_limits struct to the
|
|
* key_duration and initializes the other values. The field
|
|
* nonce_values.api_major_version will be set to 15. It shall be called from
|
|
* OEMCrypto_LoadKeys when loading a legacy license.
|
|
*
|
|
* @param[out] timer_limits: The session's timer limits.
|
|
* @param[in,out] clock_values: The session's clock values.
|
|
* @param[in,out] nonce_values: The session's ODK nonce values.
|
|
* @param[in] key_duration: The duration from the first key's key control
|
|
* block. In practice, the key duration is the same for all keys and is
|
|
* the same as the license duration.
|
|
* @param[in] system_time_seconds: The current time on the system clock, as
|
|
* described in the document "License Duration and Renewal".
|
|
*
|
|
* @retval OEMCrypto_SUCCESS
|
|
* @retval OEMCrypto_ERROR_INVALID_CONTEXT
|
|
*
|
|
* @version
|
|
* This method is new in version 16 of the API.
|
|
*/
|
|
OEMCryptoResult ODK_InitializeV15Values(ODK_TimerLimits* timer_limits,
|
|
ODK_ClockValues* clock_values,
|
|
ODK_NonceValues* nonce_values,
|
|
uint32_t key_duration,
|
|
uint64_t system_time_seconds);
|
|
|
|
/**
|
|
* This function updates the clock_values as needed if a v15 renewal is
|
|
* accepted. The field nonce_values.api_major_version is verified to be 15.
|
|
*
|
|
* This is called from OEMCrypto_RefreshKeys for a valid license renewal.
|
|
* OEMCrypto shall pass in the current system time, and the key duration from
|
|
* the first object in the OEMCrypto_KeyRefreshObject.
|
|
*
|
|
* @param[in] timer_limits: The session's timer limits.
|
|
* @param[in,out] clock_values: The session's clock values.
|
|
* @param[in] nonce_values: The session's ODK nonce values.
|
|
* @param[in] system_time_seconds: The current time on the system clock, as
|
|
* described in the document "License Duration and Renewal".
|
|
* @param[in] new_key_duration: The duration from the first
|
|
* OEMCrypto_KeyRefreshObject in key_array.
|
|
* @param[out] timer_value: set to the new timer value. Only used if the return
|
|
* value is ODK_SET_TIMER. This must be non-null if OEMCrypto uses a
|
|
* hardware timer.
|
|
*
|
|
* @retval OEMCrypto_SUCCESS
|
|
* @retval OEMCrypto_ERROR_UNKNOWN_FAILURE
|
|
* @retval ODK_SET_TIMER: Success. The timer should be reset to the specified
|
|
* value and playback is allowed.
|
|
* @retval ODK_DISABLE_TIMER: Success, but disable timer. Unlimited playback is
|
|
* allowed.
|
|
* @retval ODK_TIMER_EXPIRED: Set timer as disabled. Playback is not allowed.
|
|
*
|
|
* @version
|
|
* This method is new in version 16 of the API.
|
|
*/
|
|
OEMCryptoResult ODK_RefreshV15Values(const ODK_TimerLimits* timer_limits,
|
|
ODK_ClockValues* clock_values,
|
|
const ODK_NonceValues* nonce_values,
|
|
uint64_t system_time_seconds,
|
|
uint32_t new_key_duration,
|
|
uint64_t* timer_value);
|
|
|
|
/// @}
|
|
|
|
/// @addtogroup odk_parser
|
|
/// @{
|
|
|
|
/**
|
|
* The function ODK_ParseLicense will parse the message and verify fields in
|
|
* the message.
|
|
*
|
|
* If the message does not parse correctly, ODK_VerifyAndParseLicense will
|
|
* return ODK_ERROR_CORE_MESSAGE that OEMCrypto should return to the CDM
|
|
* layer above.
|
|
*
|
|
* If the API in the message is not 16, then ODK_UNSUPPORTED_API is returned.
|
|
*
|
|
* If initial_license_load is true, and nonce_required in the license is
|
|
* true, then the ODK library shall verify that nonce_values->nonce and
|
|
* nonce_values->session_id are the same as those in the message. If
|
|
* verification fails, then it shall return OEMCrypto_ERROR_INVALID_NONCE.
|
|
*
|
|
* If initial_license_load is false, and nonce_required is true, then
|
|
* ODK_ParseLicense will set the values in nonce_values from those in the
|
|
* message.
|
|
*
|
|
* The function ODK_ParseLicense will verify that each substring points to a
|
|
* location in the message body. The message body is the buffer starting at
|
|
* message + core_message_length with size message_length -
|
|
* core_message_length.
|
|
*
|
|
* If initial_license_load is true, then ODK_ParseLicense shall verify that
|
|
* the parameter request_hash matches request_hash in the parsed license. If
|
|
* verification fails, then it shall return ODK_ERROR_CORE_MESSAGE. This was
|
|
* computed by OEMCrypto when the license was requested.
|
|
*
|
|
* If usage_entry_present is true, then ODK_ParseLicense shall verify that
|
|
* the pst in the license has a nonzero length.
|
|
*
|
|
* @param[in] message: pointer to the message buffer.
|
|
* @param[in] message_length: length of the entire message buffer.
|
|
* @param[in] core_message_size: length of the core message, at the beginning of
|
|
* the message buffer.
|
|
* @param[in] initial_license_load: true when called for OEMCrypto_LoadLicense
|
|
* and false when called for OEMCrypto_ReloadLicense.
|
|
* @param[in] usage_entry_present: true if the session has a new usage entry
|
|
* associated with it created via OEMCrypto_CreateNewUsageEntry.
|
|
* @param[in] system_time_seconds: The current system's time in seconds.
|
|
* @param[in,out] timer_limits: The session's timer limits. These will be
|
|
* updated.
|
|
* @param[in,out] clock_values: The session's clock values. These will be
|
|
* updated.
|
|
* @param[in,out] nonce_values: The session's nonce values. These will be
|
|
* updated.
|
|
* @param[out] parsed_license: the destination for the data.
|
|
* @param[out] timer_value: set to the new timer value. Only used if the return
|
|
* value is ODK_SET_TIMER. This must be non-null if OEMCrypto uses a
|
|
* hardware timer.
|
|
*
|
|
* @retval OEMCrypto_SUCCESS
|
|
* @retval ODK_ERROR_CORE_MESSAGE: if the message did not parse correctly, or
|
|
* there were other incorrect values. An error should be returned to the
|
|
* CDM layer.
|
|
* @retval ODK_UNSUPPORTED_API
|
|
* @retval ODK_SET_TIMER: Success. The timer should be reset to the specified
|
|
* timer value.
|
|
* @retval ODK_DISABLE_TIMER: if the playtime timer has been started
|
|
* successfully then is disabled.
|
|
* @retval ODK_TIMER_EXPIRED: if the license is attempted to be loaded after the
|
|
* rental duration expires.
|
|
* @retval OEMCrypto_ERROR_INVALåID_NONCE
|
|
*
|
|
* @version
|
|
* This method changed in version 18 of the API.
|
|
*/
|
|
OEMCryptoResult ODK_ParseLicense(
|
|
const uint8_t* message, size_t message_length, size_t core_message_length,
|
|
bool initial_license_load, bool usage_entry_present,
|
|
uint64_t system_time_seconds, ODK_TimerLimits* timer_limits,
|
|
ODK_ClockValues* clock_values, ODK_NonceValues* nonce_values,
|
|
ODK_ParsedLicense* parsed_license, uint64_t* timer_value);
|
|
|
|
/**
|
|
* The function ODK_ParseRenewal will parse the message and verify its
|
|
* contents. If the message does not parse correctly, an error of
|
|
* ODK_ERROR_CORE_MESSAGE is returned.
|
|
*
|
|
* ODK_ParseRenewal shall verify that all fields in nonce_values match those
|
|
* in the license. Otherwise it shall return OEMCrypto_ERROR_INVALID_NONCE.
|
|
*
|
|
* After parsing the message, this function updates the clock_values based on
|
|
* the timer_limits and the current system time. If playback may not
|
|
* continue, then ODK_TIMER_EXPIRED is returned.
|
|
*
|
|
* If playback may continue, a return value of ODK_SET_TIMER or
|
|
* ODK_TIMER_EXPIRED is returned. If the return value is ODK_SET_TIMER, then
|
|
* playback may continue until the timer expires. If the return value is
|
|
* ODK_DISABLE_TIMER, then playback time is not limited.
|
|
*
|
|
* If OEMCrypto uses a hardware timer, and this function returns
|
|
* ODK_SET_TIMER, then OEMCrypto shall set the timer to the value pointed to
|
|
* by timer_value.
|
|
*
|
|
* @param[in] message: pointer to the message buffer.
|
|
* @param[in] message_length: length of the entire message buffer.
|
|
* @param[in] core_message_size: length of the core message, at the beginning of
|
|
* the message buffer.
|
|
* @param[in,out] nonce_values: pointer to the session's nonce data. These might
|
|
* be updated if the server returns a lower API version.
|
|
* @param[in] system_time_seconds: the current time on OEMCrypto's clock, in
|
|
* seconds.
|
|
* @param[in] timer_limits: timer limits specified in the license.
|
|
* @param[in,out] clock_values: the sessions clock values.
|
|
* @param[out] timer_value: set to the new timer value. Only used if the return
|
|
* value is ODK_SET_TIMER. This must be non-null if OEMCrypto uses a
|
|
* hardware timer.
|
|
*
|
|
* @retval OEMCrypto_SUCCESS
|
|
* @retval ODK_ERROR_CORE_MESSAGE: the message did not parse correctly, or there
|
|
* were other incorrect values. An error should be returned to the CDM
|
|
* layer.
|
|
* @retval ODK_SET_TIMER: Success. The timer should be reset to the specified
|
|
* timer value.
|
|
* @retval ODK_DISABLE_TIMER: Success, but disable timer. Unlimited playback is
|
|
* allowed.
|
|
* @retval ODK_TIMER_EXPIRED: Set timer as disabled. Playback is not allowed.
|
|
* @retval ODK_UNSUPPORTED_API
|
|
* @retval ODK_STALE_RENEWAL: This renewal is not the most recently signed. It
|
|
* is rejected.
|
|
* @retval OEMCrypto_ERROR_INVALID_NONCE
|
|
*
|
|
* @version
|
|
* This method changed in version 18 of the API.
|
|
*/
|
|
OEMCryptoResult ODK_ParseRenewal(const uint8_t* message, size_t message_length,
|
|
size_t core_message_length,
|
|
ODK_NonceValues* nonce_values,
|
|
uint64_t system_time_seconds,
|
|
const ODK_TimerLimits* timer_limits,
|
|
ODK_ClockValues* clock_values,
|
|
uint64_t* timer_value);
|
|
|
|
/**
|
|
* The function ODK_ParseRelease will parse the message and verify its
|
|
* header contents. If the message does not parse correctly, an error of
|
|
* ODK_ERROR_CORE_MESSAGE is returned. This function is mostly a placeholder
|
|
* function since there is no information needed in the release response.
|
|
*
|
|
* @param[in] message: pointer to the message buffer.
|
|
* @param[in] message_length: length of the entire message buffer.
|
|
* @param[in] core_message_size: length of the core message, at the beginning of
|
|
* the message buffer.
|
|
* @param[in,out] nonce_values: pointer to the session's nonce data. These might
|
|
* be updated if the server returns a lower API version.
|
|
*
|
|
* @retval OEMCrypto_SUCCESS
|
|
* @retval ODK_ERROR_CORE_MESSAGE: the message did not parse correctly, or there
|
|
* were other incorrect values. An error should be returned to the CDM
|
|
* layer.
|
|
* @retval ODK_UNSUPPORTED_API
|
|
* @retval OEMCrypto_ERROR_INVALID_NONCE
|
|
*
|
|
* @version
|
|
* This method is new in version 19 of the API.
|
|
*/
|
|
OEMCryptoResult ODK_ParseRelease(const uint8_t* message, size_t message_length,
|
|
size_t core_message_length,
|
|
ODK_NonceValues* nonce_values);
|
|
|
|
/**
|
|
* The function ODK_ParseProvisioning will parse the message and verify the
|
|
* nonce values match those in the license.
|
|
*
|
|
* If the message does not parse correctly, ODK_ParseProvisioning will return
|
|
* an error that OEMCrypto should return to the CDM layer above.
|
|
*
|
|
* If the API in the message is larger than ODK_MAJOR_VERSION, then
|
|
* ODK_UNSUPPORTED_API is returned.
|
|
*
|
|
* ODK_ParseProvisioning shall verify that nonce_values->nonce and
|
|
* nonce_values->session_id are the same as those in the message. Otherwise
|
|
* it shall return OEMCrypto_ERROR_INVALID_NONCE.
|
|
*
|
|
* The function ODK_ParseProvisioning will verify that each substring points
|
|
* to a location in the message body. The message body is the buffer starting
|
|
* at message + core_message_length with size message_length -
|
|
* core_message_length.
|
|
*
|
|
* @param[in] message: pointer to the message buffer.
|
|
* @param[in] message_length: length of the entire message buffer.
|
|
* @param[in] core_message_size: length of the core message, at the beginning of
|
|
* the message buffer.
|
|
* @param[in/out] nonce_values: pointer to the session's nonce data. These might
|
|
* be updated if the server returns a lower API version.
|
|
* @param[in] device_id: a pointer to a buffer containing the device ID of the
|
|
* device. The ODK function will verify it matches that in the message.
|
|
* @param[in] device_id_length: the length of the device ID.
|
|
* @param[out] parsed_response: destination for response portion of parse data.
|
|
*
|
|
* @retval OEMCrypto_SUCCESS
|
|
* @retval ODK_ERROR_CORE_MESSAGE: the message did not parse correctly, or there
|
|
* were other incorrect values. An error should be returned to the CDM
|
|
* layer.
|
|
* @retval ODK_UNSUPPORTED_API
|
|
* @retval OEMCrypto_ERROR_INVALID_NONCE
|
|
*
|
|
* @version
|
|
* This method changed in version 18 of the API.
|
|
*/
|
|
OEMCryptoResult ODK_ParseProvisioning(
|
|
const uint8_t* message, size_t message_length, size_t core_message_length,
|
|
ODK_NonceValues* nonce_values, const uint8_t* device_id,
|
|
size_t device_id_length, ODK_ParsedProvisioning* parsed_response);
|
|
|
|
/**
|
|
* The function ODK_ParseProvisioning40 will parse the message and verify the
|
|
* nonce values match those in the request.
|
|
*
|
|
* If the message does not parse correctly, ODK_ParseProvisioning40 will return
|
|
* an error that OEMCrypto should return to the CDM layer above.
|
|
*
|
|
* If the API in the message is larger than ODK_MAJOR_VERSION, then
|
|
* ODK_UNSUPPORTED_API is returned.
|
|
*
|
|
* ODK_ParseProvisioning40 shall verify that nonce_values->nonce and
|
|
* nonce_values->session_id are the same as those in the message. Otherwise
|
|
* it shall return OEMCrypto_ERROR_INVALID_NONCE.
|
|
*
|
|
* @param[in] message: pointer to the message buffer.
|
|
* @param[in] message_length: length of the entire message buffer.
|
|
* @param[in] core_message_size: length of the core message, at the beginning of
|
|
* the message buffer.
|
|
* @param[in,out] nonce_values: pointer to the session's nonce data. These might
|
|
* be updated if the server returns a lower API version.
|
|
*
|
|
* @retval OEMCrypto_SUCCESS
|
|
* @retval ODK_ERROR_CORE_MESSAGE: the message did not parse correctly, or there
|
|
* were other incorrect values. An error should be returned to the CDM
|
|
* layer.
|
|
* @retval ODK_UNSUPPORTED_API
|
|
* @retval OEMCrypto_ERROR_INVALID_NONCE
|
|
*
|
|
* @version
|
|
* This method is new in version 18 of the API.
|
|
*/
|
|
OEMCryptoResult ODK_ParseProvisioning40(const uint8_t* message,
|
|
size_t message_length,
|
|
size_t core_message_length,
|
|
ODK_NonceValues* nonce_values);
|
|
|
|
/**
|
|
* The function ODK_ParseProvisioning will parse the message and verify the
|
|
* API version is at most the version passed in.
|
|
*
|
|
* @param[in] nonce_values: pointer to the session's nonce data.
|
|
* @param[in] major_versioh: current API major version.
|
|
* @param[in] minor_version: current API minor version.
|
|
*
|
|
* @version
|
|
* This method is new in version 17 of the API.
|
|
*/
|
|
bool CheckApiVersionAtMost(const ODK_NonceValues* nonce_values,
|
|
uint16_t major_version, uint16_t minor_version);
|
|
|
|
/// @}
|
|
|
|
/// @addtogroup odk_derivation
|
|
/// @{
|
|
|
|
/**
|
|
* Contains the key label for the Mac key derivation. This contains
|
|
* |ODK_MacKeyLabelWithZeroLength| number of bytes.
|
|
*/
|
|
extern const uint8_t ODK_MacKeyLabelWithZero[];
|
|
|
|
/** Contains the number of bytes in |ODK_MacKeyLabelWithZero|. */
|
|
extern const size_t ODK_MacKeyLabelWithZeroLength;
|
|
|
|
/**
|
|
* Contains the key label for the Encryption key derivation. This contains
|
|
* |ODK_EncKeyLabelWithZeroLength| number of bytes.
|
|
*/
|
|
extern const uint8_t ODK_EncKeyLabelWithZero[];
|
|
|
|
/** Contains the number of bytes in |ODK_EncKeyLabelWithZero|. */
|
|
extern const size_t ODK_EncKeyLabelWithZeroLength;
|
|
|
|
/**
|
|
* Contains the suffix bytes (NIST 800-108 key length) for Mac key derivation.
|
|
* This value is appended after the context string. This contains
|
|
* ODK_MacKeySuffixLength number of bytes.
|
|
*/
|
|
extern const uint8_t ODK_MacKeySuffix[];
|
|
|
|
/** Contains the number of bytes in |ODK_MacKeySuffix|. */
|
|
extern const size_t ODK_MacKeySuffixLength;
|
|
|
|
/**
|
|
* Contains the suffix bytes (NIST 800-108 key length) for Encryption key
|
|
* derivation. This value is appended after the context string. This contains
|
|
* ODK_EncKeySuffixLength number of bytes.
|
|
*/
|
|
extern const uint8_t ODK_EncKeySuffix[];
|
|
|
|
/** Contains the number of bytes in |ODK_EncKeySuffix|. */
|
|
extern const size_t ODK_EncKeySuffixLength;
|
|
|
|
/**
|
|
* Generates the key-derivation contexts for the license exchange based on the
|
|
* given context value.
|
|
*
|
|
* NOTE: if the mac_key_context/enc_key_context pointer are null and/or input
|
|
* mac_key_context_length/enc_key_context_length is zero, this function returns
|
|
* OEMCrypto_ERROR_SHORT_BUFFER and sets output
|
|
* mac_key_context_length/enc_key_context_length to the size needed.
|
|
*
|
|
* @param[in] context: pointer to the context buffer.
|
|
* @param[in] context_length: the length of the context buffer.
|
|
* @param[out] mac_key_context: an output buffer to contain the MAC key context.
|
|
* @param[in,out] mac_key_context_length: on input, contains the number of bytes
|
|
* in |mac_key_context|; on return, will contain the context length.
|
|
* @param[out] enc_key_context: an output buffer to contain the encryption key
|
|
* context.
|
|
* @param[in,out] enc_key_context_length: on input, contains the number of bytes
|
|
* in |enc_key_context|; on return, will contain the context length.
|
|
*
|
|
* @retval OEMCrypto_SUCCESS
|
|
* @retval OEMCrypto_ERROR_SHORT_BUFFER: mac_key_context_length or
|
|
* enc_key_context_length is too small
|
|
* @retval OEMCrypto_ERROR_INVALID_CONTEXT
|
|
*
|
|
* @version
|
|
* This method is new in version 19 of the API.
|
|
*/
|
|
OEMCryptoResult ODK_GenerateKeyContexts(const uint8_t* context,
|
|
size_t context_length,
|
|
uint8_t* mac_key_context,
|
|
size_t* mac_key_context_length,
|
|
uint8_t* enc_key_context,
|
|
size_t* enc_key_context_length);
|
|
|
|
/// @}
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif // WIDEVINE_ODK_INCLUDE_ODK_H_
|