open-standards/wai/wai-key-proxy/README.md

# wai-key-proxy

A signing proxy in front of any licence server, and the key server it hands clear keys to.
It is the service of [`extensions/key-release.md`](../extensions/key-release.md).

For every licence request it answers, the proxy signs a receipt: a release or a refusal. The
decision is computed from signed inputs, so anyone holding the receipts recomputes it: the
viewer's entitlement (signed by the operator's entitlement authority and bound to a key the
viewer's device holds), the device's signature over the request, the content's commitment
list (signed by whoever holds the content keys, and derived from the CPIX document the keys
came in), the proxy's clock and the receipts before it. A licensor checks that keys went only
to entitled, unexpired sessions from the log, not from a statement.

The proxy holds no content key:

- each `key_commit` it signs is copied from the key holder's commitment list;
- a content protection system's licence carries the key encrypted for the client's
  decryption module, and the proxy forwards it unchanged;
- a key the client gets in the clear (an HLS key file, a Clear Key licence) is never relayed:
  the proxy answers 307 with a release ticket, and the key server, run by the key holder,
  redeems the ticket once.

A refused request never reaches the licence server.

## Run it

```sh
cargo build --release
B=target/release/wai-key-proxy

$B keygen holder.key          # the key holder's signing key; prints its public key
$B keygen authority.key       # the entitlement authority's
$B keygen proxy.key           # the proxy's

# A commitment list from the CPIX document the packager and the key server exchanged:
$B list title.cpix.xml svod:premium holder.key https://packager.example title.wkl1

$B serve proxy.json           # the proxy
$B keyserver keys.json        # the key server, for HLS key files and Clear Key
```

`proxy.json`:

```json
{
  "listen": "127.0.0.1:9710",
  "admin_listen": "127.0.0.1:9711",
  "signer_key": "/var/lib/wai-key-proxy/proxy.key",
  "signer_id": "https://keys.operator.example",
  "authorities": ["<entitlement authority public key, hex>"],
  "lists": ["/var/lib/wai-key-proxy/lists/title.wkl1"],
  "routes": [
    {"name": "title.a", "content_id": "title-0001", "delivery": "drm",
     "system_id": "<the content protection system's DASH-IF system ID>",
     "upstream": "http://127.0.0.1:9720/licence",
     "upstream_headers": {"<a header the licence server expects>": "<its value>"}},
    {"name": "title.hls", "content_id": "title-0001", "delivery": "hls-key-uri",
     "key_url": "https://keys.operator.example/v1/key"}
  ],
  "log": "/var/lib/wai-key-proxy/receipts.jsonl",
  "revocations": "/var/lib/wai-key-proxy/revocations.txt",
  "list_dir": "/var/lib/wai-key-proxy/lists.d",
  "checkpoint_every": 10000,
  "ticket_ttl_s": 60,
  "upstream_timeout_ms": 10000,
  "max_body": 65536
}
```

`"attesters"`, optional, lists the keys trusted to sign output statements of class 2
(key-release §14.2), as `"authorities"` lists the entitlement authorities. An entitlement of
version 2 states rules (§14): a limit on sessions streaming at once, which the proxy counts
from the releases in its own log, and a least output level, which a request meets by presenting
a signed output statement in `WAI-Key-Output`. A request the records cannot decide is answered
403 with a receipt whose decision is `UndecidedOutput` or `UndecidedStreams`; nothing is
released. `verify` reads the attesters from the environment variable `WAI_KEY_ATTESTERS`,
written as its other key lists are. The proxy reads no platform's output-protection signal:
a statement is a signed claim of its class.

`"revocations"`, optional, is the file of the revocations the proxy holds (key-release §16), one
`WKR1` a line in hexadecimal. An entitlement authority's revocation names a session, or a group of
entitlements that state rules, from an instant on: every request under them decided at or after
it is refused `DeniedRevoked`, before anything is forwarded. `POST /v1/revocations` on
`admin_listen`, the record's bytes as the body, adds one: `201` with its identity when it holds,
is by a trusted authority and its instant is after the proxy's clock; `422` when it does not hold
or its authority is not trusted; `409` (`revocation_late`) when its instant is not after the clock,
so that no receipt already signed is one it would change. It is made durable and held under the
log's lock, and read back on a restart. `GET /v1/revocations` there answers those held; `verify`
reads them from the file the environment variable `WAI_KEY_REVOCATIONS` names. A proxy with no
`"revocations"` holds none and answers `POST /v1/revocations` `404`.

A content's lists are one list or one chain (key-release §4.6): a first list and lists of version
3 each extending the one before, in `"lists"` in any order. A live content's next span is given
while the proxy runs by `POST /v1/lists` on `admin_listen`, the list's bytes as the body: `201` with
its identity when it holds and extends its content's chain's last list (or is the first list of a
content that has none); `409` (`list_chain_invalid`) when it does not; `422` when it does not hold
or a route of its content cannot carry one of its keys (§3.3). It is written to `"list_dir"`, made
durable and held under the log's lock, and read back on a restart; from then on a request's
receipt names it, and its keys are released. A proxy with no `"list_dir"` answers `404`.

`"checkpoint_every"`, optional, signs a checkpoint of the log (key-release §17) after that many
receipts since the last; `POST /v1/checkpoint` on `admin_listen` signs one now (`201` with it, or
`409` while a granted request is at the licence server and its receipt not yet written). A
checkpoint is a line of the log holding what later decisions read of the receipts before it, so
the proxy goes on from it: it holds in memory only the checkpoint and the receipts after it, a
restart reads the log from its last checkpoint, and `GET /v1/receipts/<identity>` reads an
earlier receipt from the file. `verify` reads a log with checkpoints as it is written, and a log
cut at a checkpoint from there.

The key provider (key-release §15) is `wai-key-release provider provider.json`: the key
holder's service a packager asks for content keys. It answers `POST /v1/provider/keys`, a CPIX
document that names keys and carries none, with the same keys' document, signs the commitment
list derived from that answer and a receipt of the exchange, and serves both at their
identities. Its keys come from one key source (key-release §15.3): `"seed"`, a file whose seed
derives test keys, which show the API end to end and nothing about how a provider in service
makes keys; or `"secret"`, a file holding a secret of 32 bytes (64 hexadecimal digits, mode 0600)
under which each key is the keyed derivation, so nobody makes the keys without that file. A
content may state `"schedule"`, `{"origin", "length", "count"}` in seconds: its key periods, and
a request for a period outside them is refused `DeniedPeriodUnknown` with a receipt. The keys
travel in the clear inside the answer, so it is carried over TLS. `provider.json`:

```json
{
  "listen": "127.0.0.1:9730",
  "signer_key": "/var/lib/wai-key-proxy/holder.key",
  "signer_id": "https://keys.holder.example",
  "requesters": ["<a packager's public key, hex>"],
  "contents": [{"content_id": "channel-0007", "required_entitlement": "live:sports",
                "schedule": {"origin": 1792886400, "length": 3600, "count": 8760}}],
  "secret": "/var/lib/wai-key-proxy/provider.secret",
  "log": "/var/lib/wai-key-proxy/provider.jsonl"
}
```

`keys.json`:

```json
{
  "listen": "127.0.0.1:9712",
  "cpix": ["/var/lib/wai-key-server/title.cpix.xml"],
  "proxies": ["<proxy public key, hex>"],
  "redeemed": "/var/lib/wai-key-server/redeemed.txt"
}
```

The proxy refuses to start on a route whose delivery cannot carry a listed key's scheme
(§3.3), on a list whose signature does not verify, on a log written by another proxy key, and
on a log another process holds.

A licence server reached over TLS is reached through a local forwarder that originates TLS
(`upstream` is `http://`): a reverse proxy listening on `127.0.0.1` whose upstream is the
licence server's `https://` address. The proxy carries no TLS stack of its own; the reverse
proxy in front of it terminates the client's TLS.

## Requests

A client sends the licence challenge (or nothing, for an HLS key file) to
`/v1/licence/<route>` with the header fields of §6.2: `WAI-Key-Ids`, `WAI-Key-Kind`,
`WAI-Key-Time`, `WAI-Key-Entitlement`, `WAI-Key-Proof` and, for a renewal, `WAI-Key-Renews`.
`wai-key-proxy sign-request` writes them for a test or a tool; a player computes the proof with
the Web Cryptography API (Ed25519 and SHA-256).

| answer | when |
|---|---|
| 200 (or the licence server's status), the licence | a content protection system's licence was granted and forwarded |
| 307 to the key server with `wai-ticket` | a clear key was granted |
| 403 and the receipt, `application/json` | refused; nothing was forwarded |
| 400, 404 | the request names no key or no route; it has no receipt |

Every decided request names its receipt in `WAI-Key-Receipt`, readable at
`/v1/receipts/<identity>`. `/v1/lists` and `/v1/health` describe the proxy; the whole log is on
`admin_listen` at `/v1/log`, which is not public, beside `/v1/revocations`.

`GET /metrics` answers the proxy's counters in the text exposition format (`../wai-metrics`):
requests by route, method and status (`wai_key_proxy_requests_total`), receipts made durable by
decision and delivery (`wai_key_proxy_receipts_total`), granted requests forwarded by the class of
the licence server's answer (`wai_key_proxy_upstream_total`), the receipts in the log, the requests
at the licence server now and the proofs of granted requests whose receipts are not yet in the log.
No route name, content, key, device, entitlement or client is a label. It is the operator's, and
answers on `admin_listen` when the proxy has one, the public listener then answering `404`. A proxy
with no `admin_listen` answers it on `listen`, where a request that came through the reverse proxy
in front, one carrying `X-Forwarded-For` or another of the fields a front sets, is answered `404`,
and a reverse proxy that sets none of them is configured not to pass the path on. `admin_listen` is
not public, and answers whatever fields a request carries.

## Check a log

```sh
$B verify receipts.jsonl <authorities,hex> <proxies,hex> title.wkl1 ...
```

runs the reference verifier of §10 over the log. The independent verifier of the conformance
corpus is `live-conformance/key_release_verify.py`.

## Tests

`cargo test` runs the proxy, the key server and a fixture licence server on loopback:
releases, refusals that never reach the licence server, a replay sent while the first request
is still being forwarded, offline licences and renewals, a licence server's refusal, tickets
redeemed once, no key byte in the log, a restart that keeps the replay and renewal history,
the whole log under the reference verifier, and `GET /metrics` read strictly as the text format,
counting those receipts and naming none of their routes, contents, keys or devices, on the
listener that is not public when there is one. `bash smoke.sh` runs the release binary as an
operator would.