This page briefly describes the options that Media CDN provides to
help prevent unauthorized distribution of your content.

Media CDN offers the following options to help protect
your content from unauthorized distribution.

- **Tokens** (recommended approach): Media CDN uses tokens to
  help protect content.

  A token is a medium of exchanging signed requests, such as a signed cookie,
  a URI with query parameters, or a path component. Valid tokens presented by
  viewers are used to authenticate access to your content. A viewer with an
  invalid token or a missing token is prevented from accessing your content.

  You can choose to use either single-token or dual-token authentication.
  Tokens are required for dual-token authentication.

  When dual-token authentication is used, Media CDN uses two
  tokens, a short-duration token and a long-duration token.

  Google recommends tokens for new integrations because they offer the
  following advantages:
  - Provide compatibility with non-Google content delivery networks (CDNs).
  - Support path-only signing.
  - Enable signing multiple headers.
  - Offer granular access control and revocation.
  - Minimize the impact of compromised tokens.
  - Can embed arbitrary data and session IDs.
- **Signatures**: Media CDN uses a single signature to help
  protect content. Signatures let you do full URL signing, including the host
  and protocol.

You can use both options together to help protect your content.

## How dual-token authentication works

Dual-token authentication uses two tokens to authenticate requests to your
content: a short-duration token for playback initiation, and a long-duration
token for the remainder of the playback session.

To use dual-token authentication, you configure your application server to
issue short-duration tokens to user agents. Then, you configure
Media CDN to respond to the short-duration tokens.
You can place the token in a query parameter of your choosing, or place the
token in a cookie. For more information, see
[Use dual-token authentication](https://docs.cloud.google.com/media-cdn/docs/use-dual-token-authentication.md.txt).

Short-duration tokens generated by your application server help protect primary
manifests (sometimes called *multivariant playlists*). The
expiration of the signed request is short enough to request a primary manifest,
but not to watch all of the content contained within a manifest.

When Media CDN receives a request with an authorized short-duration
token, it generates a signed long-duration token. You can use the token in
either a single-named query parameter or in a cookie. The long-duration token
supports viewing a full-length program. The signed long-duration tokens
generated by Media CDN use Ed25519 signatures that are signed with
Google-owned and managed keys associated with an
[`EdgeCacheKeyset` resource](https://docs.cloud.google.com/media-cdn/docs/reference/rest/v1/projects.locations.edgeCacheKeysets.md.txt).

You can customize the expiration time of short- and long-duration tokens. As a
best practice, Google recommends that you configure the expiration time of
short-duration tokens generated on your application server to one minute. You
must set the expiration time of long-duration tokens that Media CDN
generates to a duration greater than your content length, up to a maximum of one
day.

### Request flow for dual-token authentication

<br />

The following describes the request flow:

1. A viewer requests metadata from your application server for media they want
   to view. Your application server returns the URI of the primary manifest
   signed with a short-duration token.

2. Your player application requests the primary manifest from
   Media CDN. The request includes the short-duration token as a
   value of a URI query parameter in the single-named query parameter format.

3. Media CDN verifies the short-duration token and the token's
   signed parameters.

   1. If the token is valid, Media CDN creates a long-duration signature token. Media CDN returns the token either in a Set-Cookie header, or by modifying manifest and segment URIs in the primary manifest to include the token.
   2. If the token isn't valid, Media CDN responds with an **`HTTP 403 Forbidden`** response.
4. The player application receives the primary manifest from
   Media CDN, then requests the media playlist or the media
   segments referenced in the primary manifest. The request must include the
   long-duration token, either as a signed cookie or as a URI parameter.

5. Media CDN verifies the long-duration signature token:

   1. If the long-duration token is valid for the specific request, then Media CDN serves the requested content.
   2. If the long-duration token isn't valid (due to either an expired token or an invalid path), then Media CDN responds with an **`HTTP 403 Forbidden`** response.
6. The process repeats until media playback ends or the long-duration signature
   expires.

### Supported token formats for dual-token signed requests

Media CDN dual-token signed requests support multiple formats,
depending on the token type.

**Short-duration signed requests**

For short-duration signed requests, Media CDN
supports tokens signed with Ed25519 signatures by default. You can also use
symmetric-key hash-based message authentication codes (HMACs) for compatibility
with existing application code and other CDNs.

To use HMACs, you use [Secret Manager](https://docs.cloud.google.com/secret-manager/docs/overview.md.txt)
to store the HMAC secret. Then you grant access to the Media CDN
service account to access the stored secret. As a best practice, Google recommends
using asymmetric signing with Ed25519 signatures for security and performance.

The Media CDN service account is owned by the
Media CDN project, and isn't displayed in your project's list of
service accounts. The service account grants access only to
Media CDN resources in the projects that you explicitly allow.

The service account has the following format:

    service-PROJECT_NUMBER@gcp-sa-mediaedgefill.iam.gserviceaccount.com

Where <var translate="no">PROJECT_NUMBER</var> is your project number.

To activate the service Media CDN service account, create at least
one Media CDN resource, such as `EdgeCacheOrigin`.

**Long-duration signed requests**

For long-duration signed requests, Media CDN uses Ed25519
signatures that are signed with Google-owned and managed keys
associated with an
[`EdgeCacheKeyset` resource](https://docs.cloud.google.com/media-cdn/docs/reference/rest/v1/projects.locations.edgeCacheKeysets.md.txt).

Media CDN supports a single token format for long-duration tokens,
which can be used in either a single-named query parameter for HLS streams, or
in a cookie.

## How signed requests work

A signed request uses signatures or tokens to verify that every viewer is
authenticated to access content. You can configure Media CDN so
that the access is scoped to any of the following:

- Either an exact URI or URI prefix for a limited time
- A specific client
- For signed requests using tokens, up to five paths with wildcards

To use signed requests, you generate keys to sign and verify signatures. You
then configure routes, which let you optimize behavior based on the type of
content, client attributes, and your freshness requirements. Signed requests can
be enforced on a per-route basis, which helps you protect specific endpoints.

Each Media CDN service can use a collection of multiple keys.
The collection of keys is also known as a *keyset*. Keysets let you
rotate keys and distribute private keys across your own infrastructure without
interruption.

You can configure Media CDN to use either signed requests or
tokens to help protect content.

For signed requests using tokens, you can place the token in either of the
following:

- In a query parameter of your choosing
- In a cookie

For more information, see [Generate tokens](https://docs.cloud.google.com/media-cdn/docs/generate-tokens.md.txt).

For signed requests using signatures, you can use any of the following formats:

- **An exact URI with query parameters** : You specify a `URLPrefix` with the exact URI and append the same query parameters to multiple URIs.
- **A URI prefix with query parameters** : You specify a `URLPrefix` with a URI prefix and append the same query parameters to multiple URIs.
- **A path component**: You specify a path component, which lets relative manifest URIs inherit the signed URI component.
- **A signed cookie**: You specify a URI prefix in a cookie, which allows access to any URI with the prefix that you specified.

For more information, see [Generate signatures](https://docs.cloud.google.com/media-cdn/docs/generate-signatures.md.txt).

## Considerations

The following sections discuss various factors to consider to help
prevent the unauthorized distribution of your content.

### Security considerations

Media CDN validates all requests that match a route configured with a
`cdnPolicy.signedRequestMode` of `REQUIRE_SIGNATURES` or `REQUIRE_TOKENS`.

We recommend that you validate requests at your origin. Although
Media CDN rejects invalid and unsigned requests for a route that
requires signatures, clients might find a way to access your origin directly. An
additional layer of validation helps provide a defense-in-depth approach to
protecting your content.

The following table explains scenarios when Media CDN validates
a request:

| Request has signature | Signature valid? | signedRequestMode | Behavior | Status code |
|---|---|---|---|---|
| No | N/A | `REQUIRE_SIGNATURES` or `REQUIRE_TOKENS` | Requests without signatures or tokens are treated as if the signature is invalid. | HTTP `403` |
| Yes | No | `REQUIRE_SIGNATURES` or `REQUIRE_TOKENS` | A signature or token is considered invalid if it has expired or has a mismatched URL or incorrect key. Invalid signatures or tokens are rejected at the CDN edge. | HTTP `403` |
| Yes | Yes | `REQUIRE_SIGNATURES` or `REQUIRE_TOKENS` | A signature or a token is validated, and the response is served with content from a cache or the origin. | HTTP `200` |
| Yes | Yes | None or `DISABLED` | No validation is performed, and a response is served to the user directly. | HTTP `200` |
| Yes | No | None or `DISABLED` | No validation is performed, and a response is served to the user directly. | HTTP `200` |

When your application detects an invalid signature, make sure that your
application responds with an `HTTP 403 (Forbidden)` status code.
`HTTP 403` status codes aren't cacheable.

If your application sends a cacheable status code to an invalid
request, valid future requests might be incorrectly rejected.

### URI limits

Most modern HTTP clients support URIs up to 8000 characters long. However, some
legacy or niche devices may have stricter limits. In general, a signed URI adds
about 125 characters to the request URI, which includes the following:

- If all field names are used, approximately 67 characters for each field (such as **`Expires=`** and **`KeyName=`**).
- For the Unix timestamp, 10 characters
- For the **`KeyName`**, five characters
- For the base64-encoded **`Signature`** value, 43 characters

As a best practice, keep URIs less than 2000 characters long using query
parameters as tokens. Shorter URIs prevent devices from sending truncated URIs
to Media CDN.

### Legacy video streaming devices

Some legacy video streaming devices may not fully support attaching cookies to
manifest or media segment requests. If you have devices with known issues
handling HTTP cookies, configure Media CDN to use query parameters
for signed requests and dual-token exchange.

### Consent and privacy compliance

You're solely responsible for any consent and privacy compliance required when
using cookies to exchange short-duration tokens. When Media CDN is
configured to use dual-token signed requests, Google issues and manages the
cookies used for long-duration tokens.

## Billing

To learn more about how [Secret Manager](https://docs.cloud.google.com/secret-manager/docs/overview.md.txt)
is billed, see [Pricing](https://cloud.google.com/secret-manager/pricing).

Media CDN fetches for secrets are cached internally, significantly
reducing the rate of secret fetches from Secret Manager. The reduced
fetches also significantly reduce the rates of accesses that
Secret Manager observes and bills you for.

For more information on secret caching in Media CDN, see
[Keys overview](https://docs.cloud.google.com/media-cdn/docs/keys-overview.md.txt).