Update OEMCrypto documentation to 15.1
Merge from Widevine repo of http://go/wvgerrit/68184 Please add comments to the original documents at http://go/oemcrypto or http://go/wvdelta15. Some unit tests will need to be updated. Those will be in a separate CL. bug: 120795057 Full Decrypt Path Testing - change design bug: 119688262 Full Decryption Path Test update section in go/wvdelta15 bug: 117898271 Corrections to Documentation bug: 119881959 Remove shared license from documentation. bug: 80540710 Document double call to OEMCrypto_DeactivateUsageEntry Test: documentation and comment change only Change-Id: I1ef35e15207d3dabea8329a1f05518370ec099e6
This commit is contained in:
Fred Gylys-Colwell
committed by
Srujan Gaddam
Srujan Gaddam
parent
d44a8016ad
commit
f42038d89a
Binary file not shown.
Binary file not shown.
@@ -1013,7 +1013,9 @@ OEMCryptoResult OEMCrypto_LoadSRM(const uint8_t* buffer, size_t buffer_length);
|
||||
* < message_length) && (offset < offset+length),and offset+length does
|
||||
* not cause an integer overflow. If it does not have zero length, then
|
||||
* enc_mac_keys_iv must not have zero length, and must also satisfy the
|
||||
* range check. If not, return OEMCrypto_ERROR_INVALID_CONTEXT.
|
||||
* range check. If not, return OEMCrypto_ERROR_INVALID_CONTEXT. If the
|
||||
* length is zero, then OEMCrypto may assume that the offset is also
|
||||
* zero.
|
||||
* 3. The API shall verify that each substring in each KeyObject points to
|
||||
* a location in the message. I.e. (offset < message_length) &&
|
||||
* (offset + length < message_length) && (offset < offset+length) and
|
||||
@@ -1625,6 +1627,10 @@ 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
|
||||
* 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
|
||||
* call shall copy clear data even when there are no keys loaded, or there is
|
||||
* no selected key.
|
||||
@@ -2250,6 +2256,9 @@ OEMCryptoResult OEMCrypto_IsKeyboxOrOEMCertValid(void);
|
||||
* should be stable -- i.e. it should not change across a device reboot or a
|
||||
* 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.
|
||||
*
|
||||
* Parameters:
|
||||
* [out] deviceId - pointer to the buffer that receives the Device ID
|
||||
* [in/out] idLength – on input, size of the caller's device ID buffer. On
|
||||
@@ -2259,8 +2268,7 @@ OEMCryptoResult OEMCrypto_IsKeyboxOrOEMCertValid(void);
|
||||
* OEMCrypto_SUCCESS success
|
||||
* OEMCrypto_ERROR_SHORT_BUFFER if the buffer is too small to return device ID
|
||||
* OEMCrypto_ERROR_NO_DEVICEID failed to return Device Id
|
||||
* OEMCrypto_ERROR_NOT_IMPLEMENTED - this function is required for
|
||||
* Provisioning 2.0 only.
|
||||
* OEMCrypto_ERROR_NOT_IMPLEMENTED
|
||||
* OEMCrypto_ERROR_SYSTEM_INVALIDATED
|
||||
*
|
||||
* Threading:
|
||||
@@ -2856,9 +2864,8 @@ uint32_t OEMCrypto_GetAnalogOutputFlags();
|
||||
* Description:
|
||||
* This function returns a positive number indicating which resource rating
|
||||
* it supports. This value will bubble up to the application level as a
|
||||
* property in much the same way security level does. This will allow
|
||||
* applications to estimate what resolution and bandwidth the device expects
|
||||
* to support.
|
||||
* property. This will allow applications to estimate what resolution and
|
||||
* bandwidth the device expects 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
|
||||
@@ -2881,7 +2888,7 @@ uint32_t OEMCrypto_GetAnalogOutputFlags();
|
||||
* will break the sample into subsamples of size "Decrypt Buffer Size" as
|
||||
* specified in the table below. The "Decrypt Buffer Size" means the size of
|
||||
* one subsample that may be passed into DecryptCENC or CopyBuffer without
|
||||
* returning error OEMCrypto_ERROR_BUFFER_TOO_LARGE.
|
||||
* returning error OEMCrypto_ERROR_BUFFER_TOO_LARGE.
|
||||
*
|
||||
* The number of keys per session is an indication of how many different
|
||||
* track types there can be for a piece of content. Typically, content will
|
||||
@@ -3645,6 +3652,10 @@ OEMCryptoResult OEMCrypto_UpdateUsageEntry(OEMCrypto_SESSION session,
|
||||
* 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
|
||||
* already InactiveUsed or InactiveUnused, then this function does not change
|
||||
* the entry or its state.
|
||||
*
|
||||
* Parameters:
|
||||
* [in] session: handle for the session to be used.
|
||||
* [in] pst: pointer to memory containing Provider Session Token.
|
||||
@@ -4012,23 +4023,23 @@ OEMCryptoResult OEMCrypto_CreateOldUsageEntry(uint64_t time_since_license_receiv
|
||||
*
|
||||
* Description:
|
||||
* Returns the type of hash function supported for Full Decrypt Path Testing.
|
||||
* A hash type of 0 means this feature is not supported. OEMCrypto is not
|
||||
* required by Google to support this feature, but support will greatly
|
||||
* improve automated testing. A hash type of 1 means the device will be able
|
||||
* to compute the CRC32 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.
|
||||
* A hash type of OEMCrypto_Hash_Not_Supported = 0 means this feature is not
|
||||
* 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
|
||||
* 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.
|
||||
*
|
||||
* If an SOC vendor cannot support CRC 32 checksums of decrypted output, but
|
||||
* can support some other hash or checksum, then the function should return
|
||||
* OEMCrypto_Partner_Defined_Hash and those partners should provide files
|
||||
* containing hashes of test content. An application that computes the CRC 32
|
||||
* hashes of test content and builds a hash file in the correct format will
|
||||
* be provided by Widevine. The source of this application will be provided
|
||||
* so that partners may modify it to compute their own hash format and
|
||||
* generate their own hash files.
|
||||
* OEMCrypto_Partner_Defined_Hash = 2 and those partners should modify the
|
||||
* test application to compute the appropriate hash. An application that
|
||||
* computes the CRC 32 hashes of test content and builds a hash file in the
|
||||
* correct format will be provided by Widevine. The source of this
|
||||
* application will be provided so that partners may modify it to compute
|
||||
* their own hash format and generate their own hashes.
|
||||
*
|
||||
* Returns:
|
||||
* OEMCrypto_Hash_Not_Supported = 0;
|
||||
@@ -4046,57 +4057,29 @@ OEMCryptoResult OEMCrypto_CreateOldUsageEntry(uint64_t time_since_license_receiv
|
||||
*/
|
||||
uint32_t OEMCrypto_SupportsDecryptHash();
|
||||
|
||||
/*
|
||||
* OEMCrypto_InitializeDecryptHash
|
||||
*
|
||||
* Description:
|
||||
* This function is called before the first subsample is passed to
|
||||
* OEMCrypto_DecryptCENC, when the subsample_flag has the bit
|
||||
* OEMCrytpo_FirstSubsample set. OEMCrypto should expect to compute a hash
|
||||
* over the whole sample.
|
||||
*
|
||||
* This function returns OEMCrypto_ERROR_UNKNOWN_FAILURE if the current key
|
||||
* does not have the bit Allow_Hash_Verification set in its key control block.
|
||||
*
|
||||
* Parameters:
|
||||
* [in] session: session id for current decrypt operation
|
||||
*
|
||||
* Returns:
|
||||
* OEMCrypto_SUCCESS - if the hash was set
|
||||
* OEMCrypto_ERROR_NOT_IMPLEMENTED - function not implemented
|
||||
* OEMCrypto_ERROR_INVALID_SESSION - session not open
|
||||
* OEMCrypto_ERROR_UNKNOWN_FAILURE - other error
|
||||
* OEMCrypto_ERROR_SESSION_LOST_STATE
|
||||
* 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.
|
||||
*
|
||||
* Version:
|
||||
* This method is new in API version 15.
|
||||
*/
|
||||
OEMCryptoResult OEMCrypto_InitializeDecryptHash(OEMCrypto_SESSION session);
|
||||
|
||||
/*
|
||||
* OEMCrypto_SetDecryptHash
|
||||
*
|
||||
* Description:
|
||||
* Set the hash value for the frame that was just decrypted. The hash is over
|
||||
* all of the frame: encrypted and clear subsamples concatenated together. If
|
||||
* hashing the output is not supported, then this will return
|
||||
* Set the hash value for the next frame to be decrypted. This function is
|
||||
* called before the first subsample is passed to OEMCrypto_DecryptCENC, when
|
||||
* the subsample_flag has the bit OEMCrytpo_FirstSubsample set. The hash is
|
||||
* over all of the frame or sample: encrypted and clear subsamples
|
||||
* concatenated together, up to, and including the subsample with the
|
||||
* subsample_flag having the bit OEMCrypto_LastSubsample set. If hashing the
|
||||
* output is not supported, then this will return
|
||||
* OEMCrypto_ERROR_NOT_IMPLEMENTED. If the hash is ill formed or there are
|
||||
* other error conditions, this could return OEMCrypto_ERROR_UNKNOWN_FAILURE.
|
||||
* The length of the hash will be at most 128 bytes. This function is called
|
||||
* just after the last subsample in the frame, when the subsample_flag has
|
||||
* the bit OEMCrypto_LastSubsample set. The hash only applies to the previous
|
||||
* frame.
|
||||
* other error conditions, this returns OEMCrypto_ERROR_UNKNOWN_FAILURE. The
|
||||
* length of the hash will be at most 128 bytes.
|
||||
*
|
||||
* This function returns OEMCrypto_ERROR_UNKNOWN_FAILURE if the current key
|
||||
* does not have the bit Allow_Hash_Verification set in its key control block.
|
||||
* This may be called before the first call to SelectKey. In that case, this
|
||||
* function cannot verify that the key control block allows hash
|
||||
* verification. The function DecryptCENC should verify that the key control
|
||||
* bit allows hash verification when it is called. If an attempt is made to
|
||||
* compute a hash when the selected key does not have the bit
|
||||
* Allow_Hash_Verification set, then a hash should not be computed, and
|
||||
* OEMCrypto_GetHashErrorCode should return the error
|
||||
* OEMCrypto_ERROR_UNKNOWN_FAILURE.
|
||||
*
|
||||
* OEMCrypto should compute the hash of the frame and then compare it with
|
||||
* the correct value. If the values differ, then OEMCrypto should latch in an
|
||||
@@ -4147,13 +4130,18 @@ OEMCryptoResult OEMCrypto_SetDecryptHash(OEMCrypto_SESSION session,
|
||||
* If the hash set in OEMCrypto_SetDecryptHash did not match the computed
|
||||
* hash, then an error code was saved internally. This function returns that
|
||||
* error and the frame number of the bad hash. This will be called
|
||||
* periodically, but not exactly in sync with the decrypt loop. OEMCrypto
|
||||
* shall not reset the error state to "no error" once a frame has failed
|
||||
* periodically, but might not be in sync with the decrypt loop. OEMCrypto
|
||||
* shall not reset the error state to "no error" once any frame has failed
|
||||
* verification. It should be initialized to "no error" when the session is
|
||||
* first opened. If there is more than one bad frame, it is the implementer's
|
||||
* choice if it is more useful to return the number of the first bad frame,
|
||||
* or the most recent bad frame.
|
||||
*
|
||||
* If the hash could not be computed -- either because the
|
||||
* Allow_Hash_Verification was not set in the key control block, or because
|
||||
* there were other issues -- this function should return
|
||||
* OEMCrypto_ERROR_UNKNOWN_FAILURE.
|
||||
*
|
||||
* Parameters:
|
||||
* [in] session: session id for operation.
|
||||
* [out] failed_frame_number: frame number for sample with incorrect hash.
|
||||
|
||||
Reference in New Issue
Block a user