From 981c7e97d91a2467cdd9b7b807691ed03c0e68d3 Mon Sep 17 00:00:00 2001 From: Fred Gylys-Colwell Date: Sun, 19 Nov 2023 22:04:04 -0800 Subject: [PATCH] Replace reference to SelectKey with GetKeyHandle in docs Bug: 300514029 Merged from https://widevine-internal-review.googlesource.com/187930 Change-Id: I3134f9d12692dbd2916c576a872c79c87ad192fe --- .../oemcrypto/include/OEMCryptoCENC.h | 50 +++++++++---------- .../oemcrypto/test/oec_session_util.cpp | 6 +-- .../oemcrypto/test/oemcrypto_decrypt_test.cpp | 9 ++-- .../oemcrypto/test/oemcrypto_license_test.cpp | 2 +- 4 files changed, 33 insertions(+), 34 deletions(-) diff --git a/libwvdrmengine/oemcrypto/include/OEMCryptoCENC.h b/libwvdrmengine/oemcrypto/include/OEMCryptoCENC.h index 76baa6c2..ca9c3c94 100644 --- a/libwvdrmengine/oemcrypto/include/OEMCryptoCENC.h +++ b/libwvdrmengine/oemcrypto/include/OEMCryptoCENC.h @@ -367,7 +367,8 @@ typedef struct { } OEMCrypto_CENCEncryptPatternDesc; /** - * OEMCryptoCipherMode is used in SelectKey to prepare a key for decryption. + * OEMCryptoCipherMode is used in OEMCrypto_GetKeyHandle() to prepare a key for + * decryption. */ typedef enum OEMCryptoCipherMode { // explicit cipher modes used for modular DRM @@ -1510,9 +1511,9 @@ OEMCryptoResult OEMCrypto_PrepAndSignRenewalRequest( * Note: if the current SRM version requirement is not met, LoadLicense will * still succeed and the keys will be loaded. However, those keys with the * SRMVersionRequired bit set will have their HDCP_Version increased to 0xF - - * local display only. Any future call to SelectKey for these keys while - * there is an external display will return OEMCrypto_ERROR_INSUFFICIENT_HDCP - * at that time. + * local display only. Any future call to OEMCrypto_GetKeyHandle() for these + * keys while there is an external display will return + * OEMCrypto_ERROR_INSUFFICIENT_HDCP at that time. * * @param[in] session: crypto session identifier. * @param[in] message: pointer to memory containing data. @@ -1775,7 +1776,7 @@ OEMCryptoResult OEMCrypto_RemoveEntitledKeySession( * * For devices that use a hardware key ladder, it may be more convenient to * store the encrypted content key data in the key table, and decrypt it when - * the function SelectKey is called. + * the function OEMCrypto_GetKeyHandle() is called. * * @param[in] session: handle for the entitled key session to be used. * @param[in] message: pointer to memory containing message to be verified. @@ -2001,8 +2002,8 @@ OEMCryptoResult OEMCrypto_GetOEMKeyToken(OEMCrypto_SESSION key_session, * For platforms that do not need to support Bypass Decrypt, a mode compatible * with previous versions of OEMCrypto is available. These devices may latch the * key to the session and continue to use this key for this session until - * OEMCrypto_SelectKey() is called again, or until OEMCrypto_CloseSession() is - * called. + * OEMCrypto_GetKeyHandle() is called again, or until OEMCrypto_CloseSession() + * is called. * * The "key handle" in this mode is the session ID. Platforms should request a * 4-byte key handle buffer and copy the session ID into it. @@ -2015,13 +2016,13 @@ OEMCryptoResult OEMCrypto_GetOEMKeyToken(OEMCrypto_SESSION key_session, * the device should disable analog video output. If the device has * analog video output that cannot be disabled, then the key is not * selected, and OEMCrypto_ERROR_ANALOG_OUTPUT is returned. This step is - * optional -- SelectKey may return OEMCrypto_SUCCESS and delay the - * error until a call to OEMCrypto_DecryptCENC(). + * optional -- OEMCrypto_GetKeyHandle() may return OEMCrypto_SUCCESS and + * delay the error until a call to OEMCrypto_DecryptCENC(). * 3. If the key control block has HDCP required, and the device cannot * enforce HDCP, then the key is not selected, and * OEMCrypto_ERROR_INSUFFICIENT_HDCP is returned. This step is optional - * -- SelectKey may return OEMCrypto_SUCCESS and delay the error until a - * call to OEMCrypto_DecryptCENC(). + * -- OEMCrypto_GetKeyHandle() may return OEMCrypto_SUCCESS and delay the + * error until a call to OEMCrypto_DecryptCENC(). * 4. If the key control block has a nonzero value for HDCP_Version, and * the device cannot enforce at least that version of HDCP, then the key * is not selected, and OEMCrypto_ERROR_INSUFFICIENT_HDCP is returned. @@ -2091,9 +2092,9 @@ OEMCryptoResult OEMCrypto_GetKeyHandle(OEMCrypto_SESSION session, * ISO-CENC standard. * * Decryption mode is AES-128-CTR or AES-128-CBC depending on the value of - * cipher_mode previously passed in to OEMCrypto_SelectKey(). For the encrypted - * portion of subsamples, the content key associated with the handle is - * latched in the active hardware key ladder and is used for the decryption + * cipher_mode previously passed in to OEMCrypto_GetKeyHandle(). For the + * encrypted portion of subsamples, the content key associated with the handle + * is latched in the active hardware key ladder and is used for the decryption * operation. For the clear portion of subsamples, the data is simply copied. * * After decryption, all the input_data bytes are copied to the location @@ -2191,8 +2192,8 @@ OEMCryptoResult OEMCrypto_GetKeyHandle(OEMCrypto_SESSION session, * * The decryption mode, either OEMCrypto_CipherMode_CENC or * OEMCrypto_CipherMode_CBCS, was already specified in the call to - * OEMCrypto_SelectKey(). The encryption pattern is specified by the fields in - * the parameter pattern. A description of partial encryption patterns for + * OEMCrypto_GetKeyHandle(). The encryption pattern is specified by the fields + * in the parameter pattern. A description of partial encryption patterns for * 'cbcs' can be found in the ISO-CENC standard, section 10.4. * * 'cenc' SCHEME: @@ -3850,7 +3851,7 @@ OEMCryptoResult OEMCrypto_ProductionReady(void); * the most recent license should be honored. The watermarking feature should * be turned on or off when a license is loaded. If this conflicts with a * license that had been loaded earlier, then keys from the earlier license may - * not be used. In this case, either OEMCrypto_SelectKey or + * not be used. In this case, either OEMCrypto_GetKeyHandle or * OEMCrypto_DecryptCENC will return OEMCrypto_ERROR_INSUFFICIENT_PRIVILEGE to * indicate that the watermarking status has changed and the license is no * longer usable. @@ -5243,14 +5244,13 @@ uint32_t OEMCrypto_SupportsDecryptHash(void); * length of the hash will be at most 128 bytes, and will be 4 bytes (32 * bits) for the default CRC32 hash. * - * 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. + * This may be called before the first call to OEMCrypto_GetKeyHandle. 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 diff --git a/libwvdrmengine/oemcrypto/test/oec_session_util.cpp b/libwvdrmengine/oemcrypto/test/oec_session_util.cpp index 43fd50e7..fdf4c474 100644 --- a/libwvdrmengine/oemcrypto/test/oec_session_util.cpp +++ b/libwvdrmengine/oemcrypto/test/oec_session_util.cpp @@ -986,8 +986,8 @@ OEMCryptoResult LicenseRoundTrip::LoadResponse(Session* session, response_signature_.size()); if (verify_keys && result == OEMCrypto_SUCCESS) { // Give the session object a copy of the license truth data so that it can - // call SelectKey, use key control information, and so that it has key data - // to verify decrypt operations. + // call GetKeyHandle, use key control information, and so that it has key + // data to verify decrypt operations. session->set_license(response_data_); // Also, if the license has new mac keys, then install them now. if (core_response_.enc_mac_keys.length > 0) { @@ -1617,7 +1617,7 @@ void Session::TestDecryptEntitled(OEMCryptoResult expected_result, // We only have a few errors that we test are reported. ASSERT_NO_FATAL_FAILURE( TestDecryptResult(expected_result, getkeyhandle_result, decrypt_result)) - << "Either SelectKey or DecryptCENC should return " << expected_result + << "Either GetKeyHandle or DecryptCENC should return" << expected_result << ", but they returned " << getkeyhandle_result << " and " << decrypt_result << ", respectively."; } diff --git a/libwvdrmengine/oemcrypto/test/oemcrypto_decrypt_test.cpp b/libwvdrmengine/oemcrypto/test/oemcrypto_decrypt_test.cpp index 22c810c0..4c0a71d7 100644 --- a/libwvdrmengine/oemcrypto/test/oemcrypto_decrypt_test.cpp +++ b/libwvdrmengine/oemcrypto/test/oemcrypto_decrypt_test.cpp @@ -49,10 +49,9 @@ TEST_P(OEMCryptoLicenseTest, FailDecryptWithOldKeyHandle) { session_.TestDecryptCTR(false, OEMCrypto_ERROR_UNKNOWN_FAILURE)); } -// SelectKey should fail if we attempt to select a key that has not been loaded. -// Also, the error should be NO_CONTENT_KEY. -// This test should pass for v15 devices, except that the exact error code was -// not specified until v16. +// GetKeyHandle should fail if we attempt to select a key that has not been +// loaded. Also, the error should be NO_CONTENT_KEY. This test should pass for +// v15 devices, except that the exact error code was not specified until v16. TEST_P(OEMCryptoLicenseTest, SelectKeyNotThereAPI16) { ASSERT_NO_FATAL_FAILURE(license_messages_.SignAndVerifyRequest()); ASSERT_NO_FATAL_FAILURE(license_messages_.CreateDefaultResponse()); @@ -683,4 +682,4 @@ TEST_P(OEMCryptoLicenseTest, KeyDuration) { INSTANTIATE_TEST_SUITE_P(TestAll, OEMCryptoLicenseTest, Range(kCurrentAPI - 2, kCurrentAPI + 1)); -} // namespace wvoec \ No newline at end of file +} // namespace wvoec diff --git a/libwvdrmengine/oemcrypto/test/oemcrypto_license_test.cpp b/libwvdrmengine/oemcrypto/test/oemcrypto_license_test.cpp index 8e641ed9..ca2889e5 100644 --- a/libwvdrmengine/oemcrypto/test/oemcrypto_license_test.cpp +++ b/libwvdrmengine/oemcrypto/test/oemcrypto_license_test.cpp @@ -878,7 +878,7 @@ TEST_P(OEMCryptoRefreshTest, RefreshLargeBuffer) { } // This situation would occur if an app only uses one key in the license. When -// that happens, SelectKey would be called before the first decrypt, and then +// that happens, GetKeyHandle would be called before the first decrypt, and then // would not need to be called again, even if the license is refreshed. TEST_P(OEMCryptoRefreshTest, RefreshWithNoSelectKey) { LoadLicense();