Source release 16.2.0

CHANGELOG.md

@@ -2,6 +2,184 @@
 
 [TOC]
 
+## 16.2.0 (2020-04-10)
+
+**Note:** CE CDM 16.2.0 is the first release of the CE CDM 16 series. It is
+numbered 16.2 to reflect that it supports and requires OEMCrypto v16.2.
+
+Features:
+  - CE CDM 16.2.0 supports and requires OEMCrypto v16.2. The OEMCrypto header
+    files, documentation, Reference OEMCrypto implementation, and tests have
+    been updated to v16.2. For a full list of new features in OEMCrypto v16,
+    please see the
+    [Widevine Modular DRM Version 16 Delta document][oec-16-delta].
+    - The way that license durations and renewal times are handled has changed
+      significantly in OEMCrypto v16. Partners should be sure they are familiar
+      with the new behavior, which is described in the
+      [License Duration and Renewal][license-duration-doc] document.
+    - OEMCrypto v16 *does not* support updating a device directly from OEMCrypto
+      v13 or earlier to v16, due to OEMCrypto v16 dropping
+      backwards-compatibility support for the old Usage Table format.
+    - OEMCrypto v16 is much more lenient about the rate at which nonces can be
+      generated, which can now be as high as 200 nonces per second. But is much
+      stricter about the total number of nonces in flight per session, which is
+      now limited to just 1.
+  - Starting with CE CDM 16.2, the Widevine CE CDM no longer supports the 'cens'
+    and 'cbc1' schemas of ISO-CENC. Only 'cenc' and 'cbcs' are supported.
+    - Attempting to decrypt in AES-CTR mode with a nonzero pattern will now
+      return an error instead of invoking the 'cens' schema.
+    - Attempting to decrypt in AES-CBC mode with a `(0,0)` pattern will now
+      perform "full-sample" 'cbcs' decryption (the same as using a `(10,0)`
+      pattern) instead of invoking the 'cbc1' schema.
+  - The `Cdm::decrypt()` methods have been significantly reworked. These methods
+    previously took individual subsamples, one per call to the decrypt method.
+    Instead, it is now possible to pass one or more full samples to
+    `Cdm::decrypt()`. These full samples will be passed to OEMCrypto using the
+    new v16.2 version of `OEMCrypto_DecryptCENC()`, which also accepts multiple
+    full samples.
+    - It is no longer possible to pass partial samples to `Cdm::decrypt()`.
+      Callers *must* pass full samples in for decryption.
+    - For best performance, Widevine recommends that integrators not pass more
+      samples into `Cdm::decrypt()` than their OEMCrypto integration can handle.
+      - For instance, if you need to decrypt 4 samples and your OEMCrypto
+        integration only accepts a maximum of 3 samples per
+        `OEMCrypto_DecryptCENC()` call, it is more efficient to call
+        `Cdm::decrypt()` with 3 samples and then again with 1 sample than to
+        call `Cdm::decrypt()` with 4 samples.
+      - The Widevine CE CDM does not know how much data OEMCrypto can accept and
+        will attempt to pass as much data to OEMCrypto as you give it. If you
+        *do* pass more data to `Cdm::decrypt()` than your OEMCrypto integration
+        can handle, the Widevine CE CDM will progressively break the data up
+        into smaller and smaller pieces until OEMCrypto is able to accept it, a
+        process that has some performance cost.
+  - The Widevine CE CDM once again supports OpenSSL. The default is still to
+    build with the included copy of BoringSSL. But integration partners that
+    prefer to use OpenSSL and have their own OpenSSL builds can link with
+    OpenSSL instead by overriding the platform build variable
+    `privacy_crypto_impl` and setting it to the value `openssl`.
+  - All the platform build properties have been consolidated into one GYPI file,
+    `platform_properties.gypi`. These are all the variables that integration
+    partners may need to override to adapt the CE CDM to their platform.
+    Variables defined in the build system outside `platform_properties.gypi`
+    may not work correctly when overridden and should not be overridden in
+    partners' `settings.gypi` files.
+  - The Widevine CE CDM is now smarter about which usage data entries to evict
+    when the table fills up, using a Least-Recently-Used list and metadata about
+    which licenses have expired to choose which entries to evict.
+  - When subsamples were rejected by OEMCrypto with
+    `OEMCrypto_ERROR_BUFFER_TOO_LARGE` because they were too large, previous
+    Widevine CE CDM releases would break the subsamples up into 100KiB chunks.
+    Widevine CE CDM 16.2 will now break them up into larger chunks, up to the
+    "Minimum subsample buffer size" for the device's reported Resource Rating
+    Tier.
+  - The method `Cdm::update()` can now return `kNeedsDeviceCertificate` if the
+    licensing server requires that the device reprovision before it will send
+    licenses to the device.
+  - The method `Cdm::removeUsageTable()` has been removed, as it would no longer
+    do anything on OEMCrypto v16. Most users of this method should have already
+    migrated to `Cdm::deleteUsageRecord()` or `Cdm::deleteAllUsageRecords()`.
+  - The Widevine CE CDM now exposes metrics about its performance through the
+    method `Cdm::getMetrics()`. These metrics are not intended for integration
+    partner consumption but can be reported back to Google.
+  - `build.py` now works correctly in Python 2 or Python 3 and provides more
+    useful error messages.
+  - Additional tests have been added to catch more error conditions.
+
+[oec-16-delta]: ./oemcrypto/docs/Widevine_Modular_DRM_Version_16_Delta.pdf
+[license-duration-doc]: ./oemcrypto/docs/License_Duration_and_Renewal.pdf
+
+Documentation:
+  - Additional errors have been marked as "recoverable." Recovery paths for them
+    have been documented in the [Integration Guide][integration-guide-16.2].
+    - `kNeedsDeviceCertificate`
+    - `kNeedsServiceCertificate`
+  - The comments for `Cdm::setServiceCertificate()` and
+    `Cdm::parseAndLoadServiceCertificateResponse()` have been made more
+    consistent.
+  - The documentation has been updated to reflect that Widevine does not
+    recommend using the compiler flags `-Wall` and `-Werror` when building the
+    Widevine CE CDM, even though our default build files use these flags. We
+    use these flags to help us catch mistakes internally, but due to differences
+    in the sensitivity of different compiler versions, using them when building
+    with your own cross-compiling toolchain often triggers harmless warnings
+    that are treated as errors.
+  - The [Widevine CE CDM Integration Guide][integration-guide-16.2] and
+    [OEMCrypto Version Compatibility][oec-version-compat] document have been
+    updated to the latest versions.
+  - In addition to the [OEMCrypto v16.2 Specification][oec-16], OEMCrypto v16.2
+    comes with several supplementary documents:
+    - [License Duration and Renewal][license-duration-doc]
+    - [OEMCrypto State Diagrams][oec-state-diagrams]
+    - [Widevine Core Message Serialization][core-message-doc]
+
+[integration-guide-16.2]: ./Widevine_CE_CDM_IntegrationGuide_16.2.0.pdf
+[oec-16]: ./oemcrypto/docs/WidevineModularDRMSecurityIntegrationGuideforCENC_v16.pdf
+[oec-state-diagrams]: ./oemcrypto/docs/OEMCrypto_State_Diagrams.pdf
+[core-message-doc]: ./oemcrypto/docs/Widevine_Core_Message_Serialization.pdf
+
+Dependency Updates:
+  - The bundled version of BoringSSL has been updated to commit
+    [`0064c290d139b928e93a83900efe1367bc18dd03`][boringssl-0064c2].
+  - The bundled version of GYP has been updated to commit
+    [`fcd686f1880fa52a1ee78d3e98af1b88cb334528`][gyp-fcd686] in order to support
+    Python 3.
+
+[boringssl-0064c2]: https://boringssl.googlesource.com/boringssl/+/0064c290d139b928e93a83900efe1367bc18dd03
+[gyp-fcd686]: https://chromium.googlesource.com/external/gyp/+/fcd686f1880fa52a1ee78d3e98af1b88cb334528
+
+Bugfixes:
+  - Fixed a major bug that would cause sessions to enter an unusable state where
+    a segfault was inevitable if any errors occurred during usage table
+    initialization. This included errors arising from OEMCrypto choosing not to
+    implement the Usage Table API, which is technically optional.
+  - The method `onDeferredComplete` was still present on the `IEventListener`
+    interface but would never be called due to changes in CDM provisioning in
+    version 15.0.0. This method has now been removed.
+  - To avoid potential thread-safety issues, the CE CDM now uses the C++11
+    randomness classes instead of `rand()`.
+  - Cleaned up many log messages to be more useful.
+  - The Widevine CE CDM now follows a more consistent coding style. Several
+    files have been reformatted to fit this style, even where there are no other
+    changes.
+  - Some unit tests have been made more robust against crashing in error cases.
+  - Several unit tests were previously setting the service certificate more
+    frequently than was necessary, which had lead to confusion about the proper
+    way to use the CE CDM. These tests have now been changed to only set the
+    service certificate after initialization.
+  - Fixed issues where the CDM would think it had emptied the usage table when
+    it had not.
+  - The CDM will now perform fewer disk operations when deleting many usage
+    entries at once.
+  - Fixed many issues where the OEMCrypto tests would pass on the reference
+    implementation but fail on valid third-party implementations due to the test
+    being over-strict.
+  - Fixed an issue that could cause the Widevine CE CDM to delete unintended
+    files from the storage when deleting files with a wildcard.
+  - Made the CE CDM unit tests more robust against network communication errors.
+  - Fixed an issue where some unit tests were using 1023 bytes per kibibyte.
+  - Fixed an issue that could cause out-of-bounds memory access in one of the
+    OEMCrypto unit tests.
+  - Fixed several small bugs that could theoretically cause segfaults.
+
+Removing Unsupported Versions:
+  - Widevine has removed the tags and branches for several old, unsupported CE
+    CDM releases from the partner repository. Widevine has always only supported
+    the most recent OEMCrypto version plus the two versions before it. The
+    Widevine CE CDM partner repository will now only contain supported releases.
+  - New clones of the Widevine partner repository will only contain the
+    supported tags and branches. Existing clones will continue to contain them,
+    due to the way Git works. Partners that want to clean up these old
+    references from their local clones can follow these steps:
+    - If you are running Git 2.17 or newer, just run
+      `git fetch --prune --prune-tags`. Note that this will also delete any
+      local tags you have created.
+    - If you are running an older version of Git or do not want to use
+      `--prune-tags` due to the above limitations, then:
+      - To prune old branches, run `git fetch --prune`.
+      - To prune old tags, run `git tag -l | xargs git tag -d && git fetch -t`.
+        Note that, just like `--prune-tags`, this command will delete any local
+        tags you have created.
+
 ## 15.3.0 (2020-02-11)
 
 Bugfixes: