77f7ef98c0
This is the initial code drop of the reference implementation and test cases for the Widevine Whitebox API. In this drop, the full reference implementation for the AEAD white-box is provided and all test cases verifying the top-level behave have are enabled. Since the implementations can vary so much the testing is mostly left to verifying the return codes for specific parameter conditions. A full reference implementation for the license white-box is provided, however not all tests are implemented or enabled. A number of tests have been disabled as they required a loaded license and test licenses are still being worked on. The two license white-box API functions that are the further from competition are ProcessLicenseResponse() and MaskedDecryt(). ProcessLicenseResponse() is still being worked on and MaskedDecrypt() is waiting on Decrypt() to be fully functional. Most tests focus on verifying return code for specific parameter conditions, but as test licenses are created, tests looking to test the internal behaviour of license management will be added to ProcessLicenseResponse(), Decrypt(), and MaskedDecrypt().
151 lines
4.4 KiB
Markdown
151 lines
4.4 KiB
Markdown
# White-box API
|
|
|
|
## Summary
|
|
|
|
This repo contains the [Widevine](https://www.widevine.com) white-box API and
|
|
reference implementation, allowing for all CDMs to share a single white-box
|
|
implementation abstracted behind an API tailored for Widevine's use-cases.
|
|
|
|
This repo focuses on implementing the Widevine API, dependencies on any actual
|
|
white-box implementations should be treated as an external dependency and not
|
|
stored in this repo (e.g. any source or libraries should not be checked into
|
|
this repo).
|
|
|
|
## Building and Dependencies
|
|
|
|
In this repo we use [Bazel](https://bazel.build). This was done as Bazel is
|
|
open-source and widely available, making it easier for us to collaborate with
|
|
external partners, and develop independent of any final integration. It is not
|
|
expected nor required that integrators use Bazel.
|
|
|
|
The Bazel workspace is set to pull in any and all external dependencies, making
|
|
the project as self-contained as possible. To make the reference implementation
|
|
easy to integrate into our first target (Alcatraz) paths to dependencies have
|
|
been aliased to match Chromium paths.
|
|
|
|
To build the full repo and run all tests, from within or below the repo root
|
|
(the directory containing the `WORKSPACE` file), run:
|
|
|
|
```bash
|
|
bazel build "//..."
|
|
bazel test "//..."
|
|
```
|
|
|
|
## API
|
|
|
|
The API is defined in the `//api` directory. There are two white-box APIs
|
|
defined, each focused on different use-cases.
|
|
|
|
__License White-box__
|
|
|
|
The license white-box is designed to handle content keys. It is designed
|
|
to consume a Widevine license, extract the context keys, load them into the
|
|
underlying white-box, and only use them when the content policy allows (e.g.
|
|
`SW_SECURE_DECODE` can only be used by `WB_License_MaskedDecrypt()`).
|
|
|
|
__Aead White-box__
|
|
|
|
The Aead white-box is designed to encrypt/decrypt local data using
|
|
authenticated encryption, allowing for offline licenses to be locked-per-device
|
|
and avoid sensitive data from sitting exposed in runtime memory.
|
|
|
|
## Testing
|
|
|
|
Each white-box comes with a collection of conformance tests used to verify an
|
|
implementation's adherence to the API. The tests are defined in `//api` and
|
|
are designed so that by providing an implementation for `//api/test_data.h`,
|
|
the tests can be shared across multiple implementations. See "Creating A
|
|
Custom Implementation" for more information on how to do this.
|
|
|
|
## Reference Implementation
|
|
|
|
A reference implementation has been provided in `//impl/reference`. It uses
|
|
[boringssl](https://boringssl.googlesource.com/boringssl) to implement all the
|
|
crypto operations and uses
|
|
[Protocol Buffers](https://developers.google.com/protocol-buffers) to parse the
|
|
license request and license response.
|
|
|
|
This reference implementation was created for the sole purpose of developing the
|
|
conformance tests and to act as a mock in test. It should only be used in
|
|
test/debug scenarios.
|
|
|
|
## Creating A Custom Implementation
|
|
|
|
To create a custom implementation, create a new directory in `//impl`. Create
|
|
a `BUILD` file and define these two targets:
|
|
|
|
```python
|
|
cc_library(
|
|
name = "aead_whitebox",
|
|
srcs = [],
|
|
visibility = ["//visibility:public"],
|
|
deps = [
|
|
"//api:aead_whitebox",
|
|
"//api:result",
|
|
],
|
|
)
|
|
|
|
cc_library(
|
|
name = "license_whitebox",
|
|
srcs = [],
|
|
visibility = ["//visibility:public"],
|
|
deps = [
|
|
"//api:license_whitebox",
|
|
"//api:result",
|
|
],
|
|
)
|
|
```
|
|
|
|
You'll need to update the `aead_whitebox` and `license_whitebox` targets with
|
|
the source files you use (`srcs`) and the targets your depend on (`deps`).
|
|
|
|
To build your implementation, from within or below the repo root (the directory
|
|
containing the `WORKSPACE` file), run:
|
|
|
|
```bash
|
|
bazel build "//impl/your-implementation"
|
|
```
|
|
|
|
To link the conformance tests against your implementation, you'll need to
|
|
implement `//api/test_data.h` and define the following targets in your `BUILD`
|
|
file:
|
|
|
|
```python
|
|
cc_library(
|
|
name = "test_data",
|
|
src = [
|
|
"test_data.cc",
|
|
],
|
|
deps = [
|
|
"//api:test_data",
|
|
],
|
|
)
|
|
|
|
cc_test(
|
|
name = "aead_whitebox_test",
|
|
size = "small",
|
|
deps = [
|
|
":aead_whitebox",
|
|
":test_data",
|
|
"//api:aead_whitebox_test",
|
|
],
|
|
)
|
|
|
|
cc_test(
|
|
name = "license_whitebox_test",
|
|
size = "small",
|
|
deps = [
|
|
":license_whitebox",
|
|
":test_data",
|
|
"//api:license_whitebox_test",
|
|
],
|
|
)
|
|
```
|
|
|
|
To run the tests, from within or below the repo root (the directory containing
|
|
the `WORKSPACE` file), run:
|
|
|
|
```bash
|
|
bazel test "//impl/your-implementation"
|
|
```
|