Update docs for OEMCrypto v15.2

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

libwvdrmengine/oemcrypto/include/OEMCryptoCENC.h

@@ -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