android/libwvdrmengine/oemcrypto/CHANGELOG.md

# Widevine OEMCrypto, ODK, and OPK Changelog

[TOC]

## [Version 18.1][v18.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.

## [OPK Version 17.1.1][v17.1+opk-v17.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][v17.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][v17+test-updates+opk+mk]

Add makefiles to partner visible git repo.

## [Version 17 plus test updates and OPK v17][v17+test-updates+opk]

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][v17-initial-release]

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][v16.4+opk-beta2]

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][v16.4+opk-beta]

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

## [Version 16.4 doc updates][v16.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][v16.4+extra-test]

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][v16.4]

Public release for OEMCrypto API and ODK library version 16.4.



[v16.4]: https://widevine-partner.googlesource.com/oemcrypto/+/refs/tags/v16.4
[v16.4+extra-test]: https://widevine-partner.googlesource.com/oemcrypto/+/refs/tags/v16.4+extra-tests
[v16.4+doc-updates]: https://widevine-partner.googlesource.com/oemcrypto/+/refs/tags/v16.4+doc-updates
[v16.4+opk-beta]: https://widevine-partner.googlesource.com/oemcrypto/+/refs/tags/v16.4+opk-beta
[v16.4+opk-beta2]: https://widevine-partner.googlesource.com/oemcrypto/+/refs/tags/v16.4+opk-beta2
[v17-initial-release]: https://widevine-partner.googlesource.com/oemcrypto/+/refs/tags/v17-initial-release
[v17+test-updates+opk]: https://widevine-partner.googlesource.com/oemcrypto/+/refs/tags/v17+test-updates+opk
[v17+test-updates+opk+mk]: https://widevine-partner.googlesource.com/oemcrypto/+/refs/tags/v17+test-updates+opk+mk
[v17.1]: https://widevine-partner.googlesource.com/oemcrypto/+/refs/tags/v17.1
[v17.1+opk-v17.1.1]: https://widevine-partner.googlesource.com/oemcrypto/+/refs/tags/v17.1+opk-v17.1.1
[v18.1]: https://widevine-partner.googlesource.com/oemcrypto/+/refs/tags/v18.1