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.

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

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:

{
  "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",
  "ticket_ttl_s": 60,
  "upstream_timeout_ms": 10000,
  "max_body": 65536
}

keys.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.

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

$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.