whitebox/README.md

White-box API

Summary

This repo contains the Widevine 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. 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:

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 to implement all the crypto operations and uses 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:

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:

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:

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:

bazel test "//impl/your-implementation"