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

Update docs for OEMCrypto v15.2

Browse Source 
Merge from Widevine repo of http://go/wvgerrit/77604

Test: ran unit tests

Bug: 131326334 Nonce collision should be avoided in open sessions
Bug: 131325434 mac key iv should not be 16 bytes before encrypted mac key
Bug: 129368634 HDCP 2.3 and 2.2 are not distinguishable
Bug: 127423611 Question about OEMCrypto V15 API
Bug: 124312571 Picture-in-Picture -- is it really needed for Android TV?
Bug: 131175454 Extend Provisioning 3.0 Schedule
Bug: 131359743 Do not allow multiple LoadKeys in a session

Change-Id: I8db4ec921978ea918adb17420db86de69e806120
This commit is contained in:
Fred Gylys-Colwell
2019-04-29 10:13:41 -07:00
parent 3e5ade22f9
commit db534a6a05
3 changed files with 68 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
libwvdrmengine/docs/WidevineModularDRMSecurityIntegrationGuideforCENC_v15.pdf
View File

Binary file not shown.

BIN
libwvdrmengine/docs/Widevine_Modular_DRM_Version_15_Delta.pdf
View File

Binary file not shown.

113
libwvdrmengine/oemcrypto/include/OEMCryptoCENC.h
View File

@@ -8,7 +8,7 @@
* Reference APIs needed to support Widevine's crypto algorithms.
*
* See the document "WV Modular DRM Security Integration Guide for Common
* Encryption (CENC) -- version 15" for a description of this API. You
* Encryption (CENC) -- version 15.2" for a description of this API. You
* can find this document in the widevine repository as
* docs/WidevineModularDRMSecurityIntegrationGuideforCENC_v15.pdf
* Changes between different versions of this API are documented in the files
@@ -339,9 +339,9 @@ typedef enum OEMCrypto_Clock_Security_Level {
typedef uint8_t RSA_Padding_Scheme;
// RSASSA-PSS with SHA1.
const RSA_Padding_Scheme kSign_RSASSA_PSS = 0x1;
#define kSign_RSASSA_PSS ((RSA_Padding_Scheme)0x1)
// PKCS1 with block type 1 padding (only).
const RSA_Padding_Scheme kSign_PKCS1_Block1 = 0x2;
#define kSign_PKCS1_Block1 ((RSA_Padding_Scheme)0x2)
/*
* OEMCrypto_HDCP_Capability is used in the key control block to enforce HDCP
@@ -376,9 +376,9 @@ typedef enum OEMCrypto_ProvisioningMethod {
/*
* Flags indicating full decrypt path hash supported.
*/
const uint32_t OEMCrypto_Hash_Not_Supported = 0;
const uint32_t OEMCrypto_CRC_Clear_Buffer = 1;
const uint32_t OEMCrypto_Partner_Defined_Hash = 2;
#define OEMCrypto_Hash_Not_Supported 0
#define OEMCrypto_CRC_Clear_Buffer 1
#define OEMCrypto_Partner_Defined_Hash 2
/*
* Return values from OEMCrypto_GetAnalogOutputFlags.
@@ -800,13 +800,17 @@ OEMCryptoResult OEMCrypto_DeriveKeysFromSessionKey(
* before requesting more nonces, then OEMCrypto will reset the error
* condition and generate valid nonces again.
*
* To prevent Birthday Paradox attacks, OEMCrypto shall verify that the value
* generated is not in this session's nonce table, and that it is not in the
* nonce table of any other session.
*
* Parameters:
* [in] session: handle for the session to be used.
* [out] nonce: pointer to memory to receive the computed nonce.
*
* Results:
* nonce: the nonce is also stored in secure memory. At least 4 nonces should
* be stored for each session.
* nonce: the nonce is also stored in secure memory. Each session should
* store 4 nonces.
*
* Returns:
* OEMCrypto_SUCCESS success
@@ -817,11 +821,9 @@ OEMCryptoResult OEMCrypto_DeriveKeysFromSessionKey(
* OEMCrypto_ERROR_SYSTEM_INVALIDATED
*
* Threading:
* This is a "Session Function" and may be called simultaneously with session
* functions for other sessions but not simultaneously with other functions
* for this session. It will not be called simultaneously with initialization
* or usage table functions. It is as if the CDM holds a write lock for this
* session, and a read lock on the OEMCrypto system.
* This is a "Session Initialization 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 changed in API version 5.
@@ -1049,6 +1051,9 @@ OEMCryptoResult OEMCrypto_LoadSRM(const uint8_t* buffer, size_t buffer_length);
* entry is marked as "inactive" (either kInactiveUsed or
* kInactiveUnused), then the keys are not loaded, and the error
* OEMCrypto_ERROR_LICENSE_INACTIVE is returned.
* 12. The data in enc_mac_keys_iv is not identical to the 16 bytes before
* enc_mac_keys. If it is, return OEMCrypto_ERROR_INVALID_CONTEXT.
*
* Usage Table and Provider Session Token (pst)
*
* If a key control block has a nonzero value for Replay_Control, then all
@@ -1627,8 +1632,8 @@ OEMCryptoResult OEMCrypto_SelectKey(OEMCrypto_SESSION session,
* 6. If the current session has an entry in the Usage Table, and the
* status of that entry is either kInactiveUsed or kInactiveUnused, then
* return the error OEMCrypto_ERROR_LICENSE_INACTIVE.
* 7. If an Decrypt Hash has been initialized via OEMCrypto_SetDecryptHash,
* and the current key's control block does not have the
* 7. If a Decrypt Hash has been initialized via OEMCrypto_SetDecryptHash,
* and the current key's control block does not have the
* Allow_Hash_Verification bit set, then do not compute a hash and
* return OEMCrypto_ERROR_UNKNOWN_FAILURE.
* If the flag is_encrypted is false, then no verification is performed. This
@@ -2201,7 +2206,7 @@ OEMCryptoResult OEMCrypto_InstallKeyboxOrOEMCert(const uint8_t* rot,
* Version:
* This method is new API version 12.
*/
OEMCrypto_ProvisioningMethod OEMCrypto_GetProvisioningMethod();
OEMCrypto_ProvisioningMethod OEMCrypto_GetProvisioningMethod(void);
/*
* OEMCrypto_IsKeyboxOrOEMCertValid
@@ -2257,7 +2262,7 @@ OEMCryptoResult OEMCrypto_IsKeyboxOrOEMCertValid(void);
* system upgrade.
*
* This function is optional but recommended for Provisioning 3.0 in API v15.
* It may be required for future version of this API.
* It may be required for a future version of this API.
*
* Parameters:
* [out] deviceId - pointer to the buffer that receives the Device ID
@@ -2459,7 +2464,7 @@ OEMCryptoResult OEMCrypto_GetRandom(uint8_t* randomData, size_t dataLength);
* Version:
* This method changed in each API version.
*/
uint32_t OEMCrypto_APIVersion();
uint32_t OEMCrypto_APIVersion(void);
/*
* OEMCrypto_BuildInformation
@@ -2497,7 +2502,7 @@ uint32_t OEMCrypto_APIVersion();
* Version:
* This method changed in each API version.
*/
const char* OEMCrypto_BuildInformation();
const char* OEMCrypto_BuildInformation(void);
/*
* OEMCrypto_Security_Patch_Level
@@ -2524,7 +2529,7 @@ const char* OEMCrypto_BuildInformation();
* Version:
* This method was introduced in API version 11.
*/
uint8_t OEMCrypto_Security_Patch_Level();
uint8_t OEMCrypto_Security_Patch_Level(void);
/*
* OEMCrypto_SecurityLevel
@@ -2550,7 +2555,7 @@ uint8_t OEMCrypto_Security_Patch_Level();
* Version:
* This method changed in API version 6.
*/
const char* OEMCrypto_SecurityLevel();
const char* OEMCrypto_SecurityLevel(void);
/*
* OEMCrypto_GetHDCPCapability
@@ -2565,12 +2570,6 @@ const char* OEMCrypto_SecurityLevel();
* instead of HDMI output. Notice that HDCP must use flag Type 1: all
* downstream devices will also use the same version or higher.
*
* The current HDCP should be the minimum value of any display currently
* connected through any channel, either through HDMI or a supported wireless
* format. The current value can be used by the application or server to
* decide which license can currently be used. If the key control block
* requires the current HDCP level, we expect the key to be usable.
*
* The maximum HDCP level should be the maximum value that the device can
* enforce. For example, if the device has an HDCP 1.0 port and an HDCP 2.0
* port, and the first port can be disabled, then the maximum is HDCP 2.0. If
@@ -2581,6 +2580,30 @@ const char* OEMCrypto_SecurityLevel();
* user intends to view the content on a local display. The user will want to
* download the higher quality content.
*
* The current HDCP level should be the level of HDCP currently negotiated
* with any connected receivers or repeaters either through HDMI or a
* supported wireless format. If multiple ports are connected, the current
* level should be the minimum HDCP level of all ports. If the key control
* block requires an HDCP level equal to or lower than the current HDCP
* level, the key is expected to be usable. If the key control block requires
* a higher HDCP level, the key is expected to be forbidden.
*
* When a key has version HDCP_V2_3 required in the key control block, the
* transmitter must have HDCP version 2.3 and have negotiated a connection
* with a version 2.3 receiver or repeater. The transmitter must configure
* the content stream to be Type 1. Since the transmitter cannot distinguish
* between 2.2 and 2.3 downstream receivers when connected to a repeater, it
* may transmit to both 2.2 and 2.3 receivers, but not 2.1 receivers.
*
* For example, if the transmitter is 2.3, and is connected to a receiver
* that supports 2.3 then the current level is HDCP_V2_3. If the transmitter
* is 2.3 and is connected to a 2.3 repeater, the current level is HDCP_V2_3
* even though the repeater can negotiate a connection with a 2.2 downstream
* receiver for a Type 1 Content Stream.
*
* As another example, if the transmitter can support 2.3, but a receiver
* supports 2.0, then the current level is HDCP_V2.
*
* When a license requires HDCP, a device may use a wireless protocol to
* connect to a display only if that protocol supports the version of HDCP as
* required by the license. Both WirelessHD (formerly WiFi Display) and
@@ -2633,7 +2656,7 @@ OEMCryptoResult OEMCrypto_GetHDCPCapability(OEMCrypto_HDCP_Capability* current,
* Version:
* This method changed in API version 9.
*/
bool OEMCrypto_SupportsUsageTable();
bool OEMCrypto_SupportsUsageTable(void);
/*
* OEMCrypto_IsAntiRollbackHwPresent
@@ -2661,7 +2684,7 @@ bool OEMCrypto_SupportsUsageTable();
* Version:
* This method is new in API version 10.
*/
bool OEMCrypto_IsAntiRollbackHwPresent();
bool OEMCrypto_IsAntiRollbackHwPresent(void);
/*
* OEMCrypto_GetNumberOfOpenSessions
@@ -2762,7 +2785,7 @@ OEMCryptoResult OEMCrypto_GetMaxNumberOfSessions(size_t* max);
* Version:
* This method changed in API version 13.
*/
uint32_t OEMCrypto_SupportedCertificates();
uint32_t OEMCrypto_SupportedCertificates(void);
/*
* OEMCrypto_IsSRMUpdateSupported
@@ -2789,7 +2812,7 @@ uint32_t OEMCrypto_SupportedCertificates();
* Version:
* This method changed in API version 13.
*/
bool OEMCrypto_IsSRMUpdateSupported();
bool OEMCrypto_IsSRMUpdateSupported(void);
/*
* OEMCrypto_GetCurrentSRMVersion
@@ -2856,7 +2879,7 @@ OEMCryptoResult OEMCrypto_GetCurrentSRMVersion(uint16_t* version);
* Version:
* This method is new in API version 14.
*/
uint32_t OEMCrypto_GetAnalogOutputFlags();
uint32_t OEMCrypto_GetAnalogOutputFlags(void);
/*
* OEMCrypto_ResourceRatingTier
@@ -2865,7 +2888,7 @@ uint32_t OEMCrypto_GetAnalogOutputFlags();
* This function returns a positive number indicating which resource rating
* it supports. This value will bubble up to the application level as a
* property. This will allow applications to estimate what resolution and
* bandwidth the device expects to support.
* bandwidth the device is expected to support.
*
* OEMCrypto unit tests and Android GTS tests will verify that devices do
* support the resource values specified in the table below at the tier
@@ -2925,8 +2948,6 @@ uint32_t OEMCrypto_GetAnalogOutputFlags();
* +-----------------------------------+-----------+------------+-----------+
* |Number of keys per session |4 |20 |20 |
* +-----------------------------------+-----------+------------+-----------+
* |Simultaneous secure playback |1 |2 |2 |
* +-----------------------------------+-----------+------------+-----------+
* |Decrypted Frames per Second |30 fps SD |30 fps HD |60 fps HD |
* +-----------------------------------+-----------+------------+-----------+
*
@@ -2945,7 +2966,7 @@ uint32_t OEMCrypto_GetAnalogOutputFlags();
* Version:
* This method is new in API version 15.
*/
uint32_t OEMCrypto_ResourceRatingTier();
uint32_t OEMCrypto_ResourceRatingTier(void);
/*
* OEMCrypto_RewrapDeviceRSAKey30
@@ -3306,7 +3327,7 @@ OEMCryptoResult OEMCrypto_LoadDeviceRSAKey(OEMCrypto_SESSION session,
* Version:
* This method is new in API version 10.
*/
OEMCryptoResult OEMCrypto_LoadTestRSAKey();
OEMCryptoResult OEMCrypto_LoadTestRSAKey(void);
/*
* OEMCrypto_GenerateRSASignature
@@ -3648,8 +3669,10 @@ OEMCryptoResult OEMCrypto_UpdateUsageEntry(OEMCrypto_SESSION session,
* means that the state of the usage entry is changed to InactiveUsed if it
* was Active, or InactiveUnused if it was Unused. This also increments the
* entry's generation number, and the header's master generation number. The
* entry's flag ForbidReport will be set. This flag prevents an application
* from generating a report of a deactivated license without first saving the
* corresponding generation number in the usage table header is also
* incremented so that it matches the one in the entry. The entry's flag
* ForbidReport will be set. This flag prevents an application from
* generating a report of a deactivated license without first saving the
* entry.
*
* It is allowed to call this function multiple times. If the state is
@@ -3954,14 +3977,14 @@ OEMCryptoResult OEMCrypto_CopyOldUsageEntry(OEMCrypto_SESSION session,
* Version:
* This method is new in API version 13.
*/
OEMCryptoResult OEMCrypto_DeleteOldUsageTable();
OEMCryptoResult OEMCrypto_DeleteOldUsageTable(void);
/*
* OEMCrypto_RemoveSRM
*
* Description:
* Delete the current SRM. Any valid SRM, regardless of version number, will
* be installable after this via OEMCrypto_LoadSRM.
* Delete the current SRM. Any valid SRM, regardless of its version number,
* will be installable after this via OEMCrypto_LoadSRM.
*
* This function should not be implemented on production devices, and will
* only be used to verify unit tests on a test device.
@@ -3981,7 +4004,7 @@ OEMCryptoResult OEMCrypto_DeleteOldUsageTable();
* Version:
* This method is new in API version 13.
*/
OEMCryptoResult OEMCrypto_RemoveSRM();
OEMCryptoResult OEMCrypto_RemoveSRM(void);
/*
* OEMCrypto_CreateOldUsageEntry
@@ -4027,7 +4050,7 @@ OEMCryptoResult OEMCrypto_CreateOldUsageEntry(uint64_t time_since_license_receiv
* supported. OEMCrypto is not required by Google to support this feature,
* but support will greatly improve automated testing. A hash type of
* OEMCrypto_CRC_Clear_Buffer = 1 means the device will be able to compute
* the CRC32 checksum of the decrypted content in the secure buffer after a
* the CRC 32 checksum of the decrypted content in the secure buffer after a
* call to OEMCrypto_DecryptCENC. Google intends to provide test applications
* on some platforms, such as Android, that will automate decryption testing
* using the CRC 32 checksum of all frames in some test content.
@@ -4055,7 +4078,7 @@ OEMCryptoResult OEMCrypto_CreateOldUsageEntry(uint64_t time_since_license_receiv
* Version:
* This method is new in API version 15.
*/
uint32_t OEMCrypto_SupportsDecryptHash();
uint32_t OEMCrypto_SupportsDecryptHash(void);
/*
* OEMCrypto_SetDecryptHash