# 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"
```