android/libwvdrmengine/oemcrypto/CHANGELOG.md

Widevine OEMCrypto, ODK, and OPK Changelog

[TOC]

Version 19.0

This is the initial release of OPK v19.0, which implements OEMCrypto v19.0.

OEMCrypto v19

All features outlined in the v19 Delta Document are supported in this release:

• License Release
• Multiple Entitled Sessions per License Session
• Provisioning 4 Manufacturing Updates
• Support License Protocol v2.2
• Derived Key Context Computed Inside OEMCrypto
• Refactor OEMCrypto_SetDecryptHash

Other changes

• OEMCrypto_BuildInformation() previously produced JSON that had a trailing comma after the last entry. This passes some JSON parsing libraries such as jsmn, but is ultimately incorrect. This has been fixed.
• Changed key sanity checks in the wtpi_reference code to be constant time.
• Memory containing keys is now erased after the keys are used.
• FACTORY_BUILD_ONLY macro added to separate OEMCrypto functions that are only intended to be used in the factory, eg OEMCrypto_InstallKeyboxOrOEMCert().
• Added support for Provisioning 4 alternative signing models. Keybox-based signatures are fully supported, and externally generated X509 signatures are planned for a future update.
• Restrict OEMCrypto_GenerateRSASignature() to only allow Cast certificates.
• Added libcppbor to OEMCrypto unit tests. See opk/setup.sh for instructions on how to download and patch in order to build with OPK.

OP-TEE port changes

• Added an option to generate an ECC keypair instead of RSA. Use the OEMCRYPTO_GEN_KEYPAIR_TYPE make variable at compilation time to specify which method to use.
• Modified the key derivation step (device unique key -> asymmetric key pair) in Provisioning 4 CoseSign1 operations to use a NIST standard KDF process. Implementers can opt out of this by using the DEVICEKEY_NON_NIST_KDF make variable during compilation, which may be useful for existing devices in the field that are upgrading from older OPK versions tha used a non-standard key derivation.
• Renamed der_parse files to crypto_util_* to better reflect their purpose.
• Renamed wtpi_persistent_storage_layer2.c to wtpi_persistent_storage_layer1.c to better reflect its purpose.
• Removed TEE_DATA_FLAG_OVERWRITE flag from persistent storage read operations, to avoid accidentally creating empty files and overwriting existing files when encountering an error.
• Fixed bug in WTPI_GetBootCertificateChain() where ECC keys that are smaller than 32 bytes cause an error during parsing.
• Update OEMCrypto_GetDeviceInformation() implementation to include all required fields to pass device info validation tests. Field contents still need to be filled in by implementers for platform specific parameters such as device brand, bootloader unlock state, etc.

Known issues

• The OP-TEE port does not yet support Provisioning 4 stage 2, or Provisioning 4 alternate signing models. Implementers may choose to write their own functionality for these features using the BoringSSL-based wtpi_reference as a guide.

Version 18.4

Version 18.4 includes the reference implementation in OPK to support MediaCAS, and an end-to-end demo of OEMCrypto CAS functionality. These updates were in fact introduced in Version 17.2. See CAS-related updates in the change log of Version 17.2 for details. Since Version 17.2 changes were merged to OEMCrypto v18 after Version 18.3 got published, we bumped the version to 18.4 to reflect the updates. If your device doesn't support MediaCAS, this update can be skipped.

Other changes

• A fix in ODK that matches minor version with major version during session initialization.
• Added a unit test for zero subsample size.

Version 18.3

Version 18.3 includes a major feature (Cast with Provisioning 4.0) and various minor changes. Version 18.2 was an internal version bump for the ODK that included changes used by the provisioning server. Since we keep the ODK and OPK version numbers in sync, the OPK version effectively skipped 18.2.

Cast with Provisioning 4.0

The OPK now supports devices that wish to act as cast receivers while using Provisioning 4.0. Previously, only devices using Provisioning 2.0 or devices with factory provisioned certs could do this. These changes span the OPK, CDM, and provisioning server code.

The OPK changes are included in this release. The CDM changes are part of Android U. The provisioning server changes are live on Widevine staging servers, and will be pushed to production by August 2023.

OP-TEE port changes

• Added CSR and DeviceInformation implementations for Provisioning 4.0.
• Bugfix: REE->TEE message shared memory was sized based on the incoming request length, yet the response could be larger than the request and crash the TA if it did not fit in the nearest page boundary. Fixed by setting the shared memory size to the maximum allowed and passing in the request size as a separate TEE_Param.

Other changes

• Updated BoringSSL dependency to https://boringssl.googlesource.com/boringssl/+/e1b8685770d0e82e5a4a3c5d24ad1602e05f2e83
• Removed WTPI_MaxBufferSizeForDecrypt() and WTPI_ApplyCGMS() from wtpi_config_interface.h. These functions are not called by any of the OPK code.
• Updated the documentation for WTPI_GetDeviceKey() to be clearer.
• Added new optional fields to OEMCrypto_BuildInformation() output.
• Removed v15 functions OEMCrypto_LoadKeys() and OEMCrypto_RefreshKeys(), which were replaced by OEMCrypto_LoadLicense() and OEMCrypto_LoadRenewal() in v16.
• Three new optional fields have been added to OEMCrypto_BuildInformation() output JSON: git_commit and build_timestamp, and ree information.
• OEMCrypto_GenerateCertificateKeyPair() documentation has been improved to be clearer.
• New function OEMCrypto_FactoryInstallBCCSignature() added to OEMCrypto API. Not implemented in OPK.
• OPK can be used with license servers that send more than MAX_NUM_KEYS in the license response. The client-side value of MAX_NUM_KEYS must be changed in odk/include/odk_target.h to match the server's value. This is only intended for closed network systems.

Known issues

• CdmOtaKeyboxTest.BasicTest may fail due to server issues
• The ODK renewal clock is not correctly checked for all circumstances. This will be changed in v19 since the existing implementation is already in production devices.

Version 18.1

OEMCrypto V18.0 consisted of header files only. This release includes tests and OPK. There have been minor API changes since v18.0, so the version number has been bumped to 18.1

In general, new v18 OEMCrypto features have been implemented in the OPK; since those have been covered already in the published v18 headers, they will not be discussed in detail here.

This OPK release includes OEMCrypto v18 changes outlined in the document "WV Modular DRM Version 18.1 Delta". In addition, quite a few OPK-specific changes have been added since the last release. Major changes are described in more detail below in individual sections, followed by a consolidated list of minor changes.

OEMCrypto Unit Tests

The unit tests have been updated to test all v18.1 functionality.

We have also refactored the unit tests into several files grouped by category.

Previously, the unit tests modifed the GTEST_FILTER in the file oec_device_features.cpp in order to skip tests of functionality. For example keybox tests are skipped for devices that use Provisioning 4.0. We have begun replacing the modification of the GTEST_FILTER with the GTest macro GTEST_SKIP. Previously, skipped tests would not show up on the list of running tests in stdout. Now, any skipped test will start to run, and then a message will explain why it is being skipped. A list of skipped tests will be listed to stdout at the end of the test run.

The seed corpus for the oemcrypto fuzz tests has been updated using the updated unit tests.

REE-side hooks

In oemcrypto/opk/serialization/ree/GEN_oemcrypto_api.c, new ifdef checks have been added in OEMCrypto_Initialize, OEMCrypto_Terminate, OEMCrypto_DecryptCENC, and OEMCrypto_LoadLicense. Depending on the macros, liboemcrypto can be compiled with hooks that execute before, after, or instead of the listed OEMCrypto functions (or some combination of the three). If a hook macro is defined, the default behavior is to call that hook function instead of calling into the TEE -- to do both, at least one more macro must be defined. For more detail, see GEN_oemcrypto_api.c directly.

For example, defining the macro OPK_PRE_HOOK_OEMCRYPTO_DECRYPTCENC will execute OPK_PreHook_OEMCrypto_DecryptCENC() instead of calling into the TEE. The same arguments will be passed to this function, which needs a custom implementation. One use case for this is custom decryption hardware that is accessible from the REE and can accept opaque decryption key handles intended for the TEE. The above macro can be used to execute the hook function instead of calling the TEE, and the hook function can pass the key handle and encrypted content to the decrypt hardware directly, bypassing the TEE.

Another example is in OEMCrypto_Initialize(). Defining the macro OPK_PRE_HOOK_OEMCRYPTO_INITIALIZE will execute a call to OPK_Prehook_OEMCrypto_Initialize() instead of calling into the TEE. Defining another macro OPK_HOOK_AND_USE_TA_OEMCRYPTO_INITIALIZE will include the call to the TEE after the pre-hook. The implementer is free to define custom REE-side initialization logic, and continue to let the TA finish its initialization as well.

One more use case: OEMCrypto_LoadLicense(). Some implementers have requested the ability to call a custom function after LoadLicense() returns in order to parse the license response and control output restrictions accordingly from the REE (HDCP, watermarking, etc). To do this, define OPK_POST_HOOK_OEMCRYPTO_LOAD_LICENSE and OPK_HOOK_AND_USE_TA_OEMCRYPTO_LOAD_LICENSE at build time and provide a function implementation for OPK_Posthook_OEMCrypto_LoadLicense(). The post hook function will execute after OEMCrypto_LoadLicense() comes back from the TEE and will use the same function arguments.

If no macros are defined, there is no change to GEN_oemcrypto_api.c and all OEMCrypto calls will be forwarded to the TEE without hooks.

Configuration macros

Previously, a platform-specific port needed to define hard coded values in the implementation of wtpi_config_interface.h, as well as macro definitions in wtpi_config_macros.h. These values defined which features were available in the build, but they were difficult to modify for a new build, and it was often unclear what configuration values were enabled for a particular build.

These have been replaced with a single header file consisting of only macro definitions. For a full list of these configuration macros with default values, see oemcrypto/opk/oemcrypto_ta/wtpi_reference/config/default.h.

Each platform-specific port needs to provide configuration values in a file called opk_config.h. The OPK code looks for this file at compilation time. To provide flexibility at build time, these macro definitions should be #ifndef checked. This way, macros can be defined in the cflags to override the default values if desired (eg build a version that only changes the provisioning method by setting the OPK_CONFIG_PROVISIONING_METHOD macro in the cflags). The OP-TEE, Trusty, and Linux reference ports all have opk_config.h files that can be used as examples.

As part of the OEMCrypto v18 changes, OEMCrypto_BuildInformation() now outputs JSON-formatted text. If the OPK is built in debug mode, the build information will also include all of the configuration macro values as a new JSON field. The intent is to improve the debugging experience by providing as much configuration information as possible. With the changes to OEMCrypto_BuildInformation(), the WTPI_BUILD_INFO macro is no longer required.

OP-TEE port changes

• Add implementations for provisioning 4.0 WTPI functions. This requires the third party library open-dice.
• Pre-allocate crypto handles for DecryptCENC. Since this is a performance-sensitive path, allocate once up front instead of per DecryptCENC call.
• Reduce compiler warnings.
• Add support for RSA CAST receiver signing.
• Add QEMUv8 target.
• Move der_parse and related files into the wtpi_impl directory.
• Bugfix: Randomly generated ECC key in v17.1 sometimes was smaller than the expected keysize. Fixed to include leading zeroes if needed.
• Bugfix: WPTI_GenerateRandomCertificateKeyPair() was implemented incorrectly. It did not return the correct minimum size, used the wrong mbedtls key type, and did not free allocated resources. Fixed all three issues. Please note that on 64-bit targets, WPTI_GenerateRandomCertificateKeyPair() will exhaust the default memory pool that OP-TEE uses for mbedtls. We suggest increasing MPI_MEMPOOL_SIZE from 12k to 14k in optee_os/lib/libutee/tee_api_arith_mpi.c to avoid this.

Trusty port changes

In v17.1, the Trusty port did not compile against the OPK. This has been fixed in v18, with the code moved one directory deeper to a folder named reference.

Implementers looking to create a port based on this reference code are encouraged to copy the reference folder and modify it, instead of modifying the existing code directly.

The Trusty port still requires a full download of AOSP Trusty, and must be built into the Trusty kernel as a user module. In the future we plan to support standalone TA builds that can be compiled or sideloaded into Trusty OS.

At this time, there is still no easy way to test builds of the Trusty port without hardware. QEMU support is planned for a future release.

Linux testing port

A new folder has been created under oemcrypto/opk/ports for an implementation that can run on Linux. Please note that this is a testing-only insecure implementation, as all code executes in the REE.

The oemcrypto_unittests and wtpi_unittests applications are the same. The "TA" is a Linux application that spins a while loop until it receives a message, then executes that call. The transport interface between liboemcrypto and this fake TA uses Linux shmem APIs to pass messages back and forth.

Again, this is not to be used in any kind of production release. The fake TA is only intended as an easier way to test the REE-TEE code path without a trusted OS.

Other changes

• Provisioning 4 WTPI functions moved to wtpi_provisioning_4_interface.h. Some new functions added such as WTPI_GetSignedCsrPayload()
• Provisioning 4 WTPI tests improved to test correctness of BCC and CoseSign1 payloads, but requires new third party library COSE-C to do so.
• WTPI unit tests can be skipped based on configuration values. Currently provisioning 4 WTPI functions are skipped if the configured provisioning method is different.
• Calling an OEMCrypto function with shared buffer arguments could fail if the underlying buffer was larger than the available shared memory. This would occur before reaching the TEE in the serialization code, and would return the default OEMCrypto_ERROR_UNKNOWN_FAILURE error. Now it returns OEMCrypto_ERROR_BUFFER_TOO_LARGE.
• Fixed a memory leak in the asymmetric key table management code, where key handles were not freed at session termination.
• Fixed a bug in the serialization code, where uint8_t iv[16] parameters were not passed correctly through to the TEE, eg in AES operations. A NULL input would always show up as a valid pointer to the TEE. This is now fixed and NULL inputs show up as NULL in the TEE.

Known bugs

• In the OP-TEE port, WTPI unit tests that use randomly generated ECC keys occasionally (1/100) fail. The exact cause is unknown, but it appears to be due to an edge case in the implementation of WPTI_GenerateRandomCertificateKeyPair().
• The OPK does not support Cast Receiver functionality when using Provisioning 4.0.
• The OPK does not yet support MediaCAS functionality.

Version 17.2

This release contains the first version of OPK to support MediaCAS, an end-to-end demo of OEMCrypto CAS functionality, several bug fixes in OPK and a few updates to the OEMCrypto unit tests and fuzz tests.

MediaCAS support has been added to OPK. OPK_Pack_LoadCasECMKeys_Request(), OPK_Unpack_LoadCasECMKeys_Request(), OPK_Pack_LoadCasECMKeys_Response(), OPK_Unpack_LoadCasECMKeys_Response() are moved out of the auto-generated serialization code and are added to the special cases, to allow implementor to pack customized data. CAS-specific WTPI functions along with a reference implementation have been added.

A new cas directory is added to the ports/linux project. This contains an end-to-end demo of OEMCrypto CAS functionality. The OEMCrypto CAS test client communicates with the Linux tee_simulator_cas via liboemcrypto.so and libtuner.so. tee_simulator_cas loads CAS keys and performs descrambling.

All CAS specific code in OPK is guarded by the compiler flag SUPPORT_CAS.

Several other updates and fixes to OPK in this release include:

• strnlen() is removed from OPK to avoid issue caused by the terminating '\0'.
• Explicit call to builtin_add_overflow() is removed and oemcrypto_overflow wrappers are used instead.
• Added non-NULL checks in WTPI_UnwrapValidateAndInstallKeybox(), OEMCrypto_OPK_SerializationVersion(), and OPKI_GetFromObjectTable().
• Validated the wrapped key size to be non-zero.
• Set OP-TEE serialized request size to the maximum size expected.
• HMACs are compared in constant time.
• Fixed pointer arithmetic with size_t to avoid unexpected truncation of the calculated address.
• No-op for zero-sized subsample instead of aborting OPK.

This release also contains a few updates to the OEMCrypto unit tests and fuzz tests:

• Reduced clock skew in flaky duration tests.
• Removed device ID check since it is not required for v17.
• Added a test for zero subsample size.
• Cleaned up fuzz helper classes and added more fuzz test coverage.

OPK Version 17.1.1

This release fixes a flaw in the OPK code that could allow content that requires HDCP 2 to output over a display connection that only supports HDCP 1. This bug would only be triggered if the WTPI implementation reports the minor version number of HDCP 1 connections. If your implementation of WTPI_CurrentHDCPCapability() ever returns HDCP_V1_0, HDCP_V1_1, HDCP_V1_2, HDCP_V1_3, or HDCP_V1_4, your device is vulnerable and you should take this patch urgently. If your implementation of WTPI_CurrentHDCPCapability() only ever returns HDCP_V1 for HDCP 1 connections or does not support HDCP 1, then your device is not affected. You will not need to change your WTPI implementation to apply this patch.

This release also fixes the value of maximum_minor_version in ODK.

Version 17.1

This release contains a major change to the build process for the OP-TEE port, a new ODK minor version, handling for v16.4.x licenses with clear key control block, provisioning 4.0 in the wtpi_reference code, and various small changes.

The build process for the OP-TEE port has been simplified. Previously, the OPK components were compiled with their own makefiles, compiler flags, and toolchain; a platform-specific build system would then need to link those components into the final application. Now, a list of all OPK files is provided in the new tee-sources.mk file for inclusion in the target platform's build system. This guarantees that the OPK code will be compiled with the same build flags and toolchain as the rest of the TA. The OP-TEE port has been modified to use this new list of source files, and the generated makefiles from previous versions have been removed.

The ODK has been updated to v17.1. A new function has been added, ODK_PrepareCoreRenewedProvisioningRequest(), for use with renewing deleted or compromised keyboxes. An out of bounds buffer error was fixed in CreateCoreLicenseResponse().

A unit test has been added to test against the issue where certain 16.4.x SDK versions return a clear key control block (KCB) in the license response. An OEMCrypto v17.1+ implementation should be able to handle the clear KCB in the 16.4.x response and load the license correctly.

Provisioning 4.0 is now supported in oemcrypto_ta and the WTPI reference code. The WTPI_GetProvisioningMethod() config function should return OEMCrypto_BootCertificateChain to enable this.

WTPI_ED25519Sign() has been removed from the WTPI layer.

All oemcrypto_unittests now pass for the OP-TEE port running on NXP iMX8. Provisioning 4.0 is not yet supported on the OP-TEE port.

Please note that no changes have been made to the Trusty port code. As a result, the Trusty port may not compile against the latest changes to the rest of OPK.

Version 17 plus test updates and OPK v17

Add makefiles to partner visible git repo.

Version 17 plus test updates and OPK v17

This release contains the first partner release version of OPK, which is also the first version of OPK to support OEMCrypto v17. OPK v17 represents a considerable upgrade from the previous beta releases and makes many significant changes to the WTPI. This release includes sample ports to both the OP-TEE and Trusty TEE OSes. The Trusty port has been tested on the Pixel 6 and the OP-TEE port has been tested on the NXP iMX8 reference board. See their respective README.md files for platform-specific instructions and an explanation of any failing tests.

This release of OPK still uses Provisioning 2.0 (keyboxes). Provisioning 4.0 has not yet been tested, and support for it is incomplete. We expect there to be another release with updates to support Provisioning 4.0 in the near future. Our intention is to continue to support both Provisioning 2.0 and 4.0. Devices that plan to use Provisioning 4.0 must support ECC and have enough entropy to generate ephemeral keys on the device.

Beyond OPK, this release contains several small updates to OEMCrypto and ODK:

• ODK has been updated to use version 17 core messages by default.
• ERROR_INVALID_RSA_KEY has been renamed to ERROR_INVALID_KEY in order to make it clearer that this error also applies when the key is an elliptic curve key.
• The deprecated SRM update functions have been removed from the OEMCrypto header.

This release also contains several updates to the OEMCrypto unit tests:

• The fuzz tests have been updated to be compatible with OEMCrypto v17.
• A test has been added that verifies the device can load at least as many DRM keys as promised by its resource rating tier.
• A test has been added to verify that loading invalid usage entries fails.
• An issue in TestLoadLicenseForOutOfRangeSubStringOffSetAndLengths where the test attempted to load the license before encrypting and sigining it has been addressed.
• An issue where some tests were not including a nonce in all license requests has been fixed.

Version 17

Initial release of OEMCrypto v17 unit tests and documentation. See https://developers.google.com/widevine/drm/client/oemcrypto/v17/delta for changes since v16.

Version 16.4 plus opk beta 2

Second beta release of the OEMCrypto Porting Kit (OPK), supporting OEMCrypto v16.

The following changes are included with this update:

• Add makefiles to build OEMCrypto TA and host apps for OP-TEE. See oemcrypto/opk/ports/optee/README.md for information on how to build with make
• Update missing and outdated files such as odk_message.h and OEMCryptoCENCCommon.h
• Rename WTPI interface files with common WTPI prefix
• Add more WTPI unit tests for crypto functions
• Replace DER parsing code in OEMCrypto TA OPTEE port with mbedtls implementation
• Update oemcrypto unittests

Using the default make settings and an external OP-TEE repository setup, the OEMCrypto TA port is now buildable for QEMU. Slight changes to environment variables will enable STM32MP1 and NXP iMX8 targets. Keep in mind that the performance capabilities of QEMU and the STM32MP1 platforms do not meet the timing requirements for many oemcrypto unittests; so far we have only passed all tests on the NXP hardware.

This update does not include any Trusty port code.

Version 16.4 plus opk beta

Initial beta release of the OEMCrypto Porting Kit (OPK), supporting OEMCrypto v16.

Version 16.4 doc updates

Documentation updates. All headers have been updated so that documentation may be extracted using Doxygen. Documentation can now be found at https://developers.google.com/widevine/drm/client/oemcrypto

Version 16.4 plus extra tests

We have added several new tests to the OEMCrypto test suite in order to identify and fix certain types of security issues that are being discovered and disclosed by security researchers. Widevine strongly recommends these additional security tests, in order to minimize the risk and exposure from external security research.

Most of the new tests are checking for buffer overflow and off-by-one errors. They verify that OEMCrypto correctly handles the case where input buffers are larger than output buffers; total subsamples are larger than samples; and message buffers are much larger than required. OEMCrypto is expected to accept bad input and fail gracefully. Failing these tests is an indication that there might be a security risk.

Because buffer overflow bugs might crash the device or cause a seg fault, these tests might fail and then stop running. For this reason, you cannot assume that your device is passing all of the tests if you don't see FAIL in the output. Instead, you should look for a summary at the end of the test suite output saying that all the tests passed. See the README.md in oemcrypto/test for more details.

Version 16.4

Public release for OEMCrypto API and ODK library version 16.4.