Qwilt URL Signing

Introduction

URL signing ensures the integrity of the URL or specified parts of it, preventing tampering by anyone without the secret key used to generate the signature. Additionally, URL signing can limit the URL's validity, for example by setting an expiration on the signature or specifying the allowed client IP.

As a content publisher, you can use Qwilt URL Signing to safeguard against unauthorized access to your content that is delivered through the Qwilt CDN.

This document describes the Qwilt URL signing solution for Self Service Media Delivery.

How Does it Work?

Implementing Qwilt URL Signing requires collaboration and secret sharing between the signing party (the content publisher) and the validating party (Qwilt CDN, the content distributor).

The content publisher embeds a JWT token into the client request as either a first path segment of the URL or as a query parameter. This JWT token carries crucial information about the request, such as the request URL path, the expiration time of the signature, and the valid client IP.

Qwilt URL Signing leverages JWT (JSON Web Token), a JSON-based open standard (RFC 7519) for creating signed access tokens that assert claims. Learn more about JWT.

The JWT token contains claims such as the URL components used in the signature and the signature's expiration time, which together determine the validity of the signed URL and define the conditions for request acceptance. These claims are encoded into the JWT payload.

When the content publisher receives a client request for content, the content publisher signs the request to secure the JWT payload before responding to the client. Once signed, the URL in the request cannot be altered without invalidating the signature.

When the CDN receives the request, it attempts to validate the signed request using the secret key. It validates the claims, such as the request URL path and expiration timestamp. When the validation is successful, the CDN continues processing the request. If the validation fails, the request is rejected with response code 403.

Adaptive Bitrate (ABR) Delivery

In an Adaptive Bitrate (ABR) content delivery scenario:

• The content publisher adds the JWT token to the first path segment of the initial request (master manifest).

• The JWT specifies the portion of the URL that is shared across all expected subsequent requests, which are derived from the master manifests.

  For example, in a request like: https://www.example.com/qsig=<JWT token>/videos/movie123/master.m3u8, only this portion is signed: /videos/movie123/.

  Once signed, this portion of the URL cannot be altered without invalidating the signature.

• Assuming the use of relative paths in the manifest files, the token is inherited and sent with subsequent requests during the ABR session.

Workflow Overview

These are steps required to implement Qwilt URL signing for a Media Delivery site.

PREREQUISITES
These are global settings that apply to URL signing in general.

1. Generate the secret keys.
2. Share the secret keys with Qwilt CDN. To do so, add the keyset to the site configuration.
3. Decide on a token insertion method and set it in the site configuration. Learn about token insertion methods.

URL SIGNING
A signature is applied to a particular request URL. The following steps are implemented per request:

1. Content publisher: Generate the JWT. Use the HS256 algorithm and the secret key (not base64 encoded) to hash it. Learn how to create the JWT token.
2. Content publisher: Concatenate a JWT into the request URL using the defined token insertion method. Learn how to inject the token into the request URL.
3. Qwilt CDN: When a request is received, use the HS256 algorithm and the shared secret key to verify that the token is valid (e.g. expiration). If there is a match, the CDN then checks if the claims defined in the token are valid. If they are, the request is accepted. If not, it is rejected with the 403 response.

Secret Keys

Qwilt URL signing requires secret sharing between the signing party (the content publisher) and the validating party (Qwilt). Qwilt URL signing supports multiple keys. Each key is mapped to a Key ID (KID). The signed client request includes the KID in the JWT payload.

After you generate the secret key, you share it with Qwilt CDN by creating a keyset and adding it to the site configuration.

This article describes Key Management via the Delivery Services UI. Alternatively, you can perform Key Management tasks with the Keys Manager API.

Create a Keyset

In the Media Delivery Site Configuration UI, create the list of shared secret keys and their mapped identifiers (kid JWT Claim) to be used by both the signing (content publisher) and validating (Qwilt CDN) parties.

Learn how to Create a Keyset.

Add the Keyset to the Site Configuration

When implementing Qwilt URL signing, you add the relevant keyset to the Site Configuration.

Add the keyset to the site configuration by configuring the URL Signing rule.

You may modify the keyset at any time, by adding or removing keys and republishing the site. After you republish the site, Qwilt CDN uses the updated keyset to validate client requests to the site.

Likewise, you may associate a different keyset with the site. Again, the change is activated only after you republish the site.

Change a Secret Key

As part of key lifecycle management, you may want to change the secret key. You can do this at any time.
We recommend adding the new key, starting to use it, and then deleting the old key.

1. Create a new secret key.
2. Add it to the keyset associated with the site. Make sure to assign a unique key ID (KID).
3. Republish the Media Delivery site.
   When the keyset associated with a site contains multiple keys, you can choose any of them to sign URLs.
4. After you shift to signing with the new KID, you can delete the key you no longer want to use from the keyset and republish the Media Delivery site. After you republish, the deleted key is no longer supported by the CDN.

Token Insertion Methods

There are two locations in the client request where the signature token can be placed. Each location supports different capabilities for different scenarios. The default token insertion method is First Path Segment.

To set the token insertion method:

1. Decide on the token insertion method.

2. Set the insertion method in the Media Delivery site configuration when configuring the URL Signing rule.

First Path Segment

This method is recommended for ABR content delivery. (It is also suitable for non-ABR scenarios.)

As a content publisher, you add the token to the first path segment of the initial request (master manifest). Assuming the usage of relative paths in the manifest files, the token is inherited and sent in subsequent requests of the ABR session.

Example:
https://www.example.com/qsig=<JWT token>/videos/movie123/master.m3u8

Note that in case of a cache miss, the CDN removes the token first path segment before sending the request towards the origin.

URI Parameter

This method is best suited for non-ABR content delivery, although it can also be applied to ABR scenarios in some cases.

Example:
https://www.example.com/path/to/file/master.m3u8?qsig=<JWT token>

Cache-Miss Behavior

In the event of a validated client request for content that is not in the cache (a cache miss), the CDN issues a request towards the origin server to serve the client and populate the cache with the requested content.

After the client request is validated, the signature token is removed from the request and sent towards the origin. Note that the origin should be configured to expect signature-less requests.

Generate the JWT (JSON Web Token)

The JWT is used to authenticate and authorize access to protected resources.

Required JWT Structure

A JWT token is comprised of the header, the payload, and the signature. Note that the header requirements are specific to Qwilt URL Signing, and that while the header is an integral part of JWT, the header itself is omitted from the request URL.

JWT Header Configuration

The Qwilt URL Signing implementation makes a non-typical use of the JWT header. The JWT header is used only to define the hashing algorithm. For the Qwilt URL Signing, it must be "alg": "HS256" base 64 URL encoded. Note that we do not pass the header with the request URL. It is a static header that is assumed by both the signing and validating parties.

The required JTW header:

{"alg":"HS256"}

Construct the JWT Payload

The JWT payload is a JSON object that includes the claims about the entity.

Supported JWT Claims

This section describes the list of signature parameters supported by the CDN For Self Service users.

The signature parameters, represented as JWT claims, determine the validity of the signature and define the conditions under which a request is accepted. These claims are subsequently encoded into the JWT payload.

• Expiration: Limits the time that a signature is valid. A request arriving past the set expiration time is rejected.

• Client IP: Triggers validation of the client IP address. A mismatch between the request source IP and the client IP set in the signature causes the request to be rejected.

  Caution!

  Use the Client IP claim with caution. Client IP validation may yield unexpected results with network configurations like NAT (Network Address Translation) or Clients with IPv4/IPv6 Dual Stack, for example, where the IP address seen and signed by the Content Provider may differ from the IP address seen by the CDN when the request is received and would therefore be rejected with a 403 Response.

• Secret Key (mandatory parameter): The key ID of the shared secret key. Each shared secret key, used for both signing and validation, has an associated key ID. The key ID tells the validating party which secret key was used during the signing process, ensuring the correct key is used for validation.

• Content Path (mandatory parameter): Specifies the content to which the signature authorizes access. The content path parameter can specify a full path to a single content object, or a partial path that encompasses multiple content objects. Learn more about the Content Path parameter.

Content Path

The Content Path parameter is mandatory. It specifies the content to which the signature authorizes access.

The Content Path parameter can specify a full path to a single content object, or a partial path that encompasses multiple content objects.

Defining a partial path allows access to multiple items using a single signature. This is relevant to the ABR scenario, where we want to allow access to multiple items that represent small fragments of the content object using a single signature. In this case, the content path parameter specifies the part of the path that is common to all the ABR session requests.

Another use case for partial path extraction is when you want to sign a specific path and allow any query parameters without signing each variation individually. In this case, only the path is signed, so requests to that path are validated regardless of the query parameters in the request URI.

Extraction Methods

The extraction method can be selected per request, via the typ JWT claim.
Qwilt URL signing supports one Full Path method and three Partial Path methods.

*Any other value will cause request rejection.

Full Path

typ = 'all'
This method extracts the full path including the file name and the query string. With this method, the signature is valid exclusively for the specific request it was originally produced for. This method is more suitable for progressive content delivery, and less suited to ABR content delivery.

Partial Path

Qwilt URL signing supports three partial path extraction methods:

• In-Token Regex Match and Hash
• In-Token Regex Match
• In-Token Segments Count

Use any of these methods to extract the relevant parts of the path, potentially including the query string, to support signing part of a URI.

In-Token Regex Match and Hash

typ = 'rgh'
You can use this method when the content directory structure is varied, and one regex is inadequate to extract every partial path in the service.
The regex extraction and build rules can be changed by the signing party, per request and passed in the rgx and rgb JWT claims.

The partial path is hashed and inserted into the hsh JWT claim.

Content Path Parameters

An Extraction Rule is a regular expression that sets a match condition for both the full path and the query string of a URL.

It may use regex extraction groups that will later be used in the build rule.

If the extraction rule is not a match, the request is rejected with response code 443.

A Build Rule is a string that defines the use of the extractions from the regex extraction rule (e.g. path segments, URI parameters) in order to build the partial path. The partial path is then hashed and inserted into the hsh JWT claim.

Both the signing and validating parties perform the extraction, building, and hashing actions to produce the partial-path hash. The hash product must match for the request to be validated. This method is suitable for ABR scenarios where the structure of the content path is uniform throughout the service library and the relevant partial path elements (and possibly URI parameters) require a regex for their extraction.

For example:
If this is the publisher URL structure:
/<series-name>/<other-stuff>/season=<season-id>/<episode name>/<segment-or-manifest-file-name>

And the content publisher would like to sign the URL based on series name, season-id, and episode name, they could define the following extraction and build rules.

Extraction Rule:
^/([^/]+)/.*season=(\d+)/([^/]+)/.*

Build Rule:
“Title=$1--Season=$2--Episode=$3”

As a result, for a request containing this URL path:
/MacGyver/other-stuff/season=1/ep5/seg1.ts

The build string for the hash would be:
“Title=MacGyver--Season=1--Episode=ep5”

In-Token Regex Match

typ = 'rgm'
This method is the same as the In-Token Regex Match and Hash method except that only the regex matching is performed. The validating party verifies that the regex in the rgx JWT claim matches the request path and query string. No partial path is built or hashed for comparison.

This method is suitable when the regex rule is tailored to identify a single title only.

Content Path Parameters

In-Token Segments Count

typ = 'sgn'
This method is suitable when the relevant partial path is a group of adjacent segments from the original request path (not including the query string).

The signing party signals to the validating party what part of the request path is signed with the (mandatory) segment count (cnt) and (optional) segment offset (off) JWT claims.

The partial path should include the slash (‘/’) before each segment and exclude the delimiter at its end (which can be either the end of the path, a slash delimiter, or a URI-param delimiter). Once the partial path is extracted it is hashed and inserted in the hsh JWT claim.

As with the other methods, during validation, if the hash product matches, the request is validated.

Examples
The following table illustrates the partial path (the portion of the full path marked in blue) to be hashed, based on the (mandatory) segment count (cnt) and (optional) segment offset (off) settings.

The cnt value indicates the number of path segments to be extracted from the requested path.

The off value indicates the offset, or the number of path segments to skip (from the beginning of the path) before extracting the number of segments indicated by the cnt claim. The default is '0.' If the off claim is absent, the offset is considered as '0.'

Content Path Parameters

Insert the Token into the Request URL

Concatenate a JWT into the request URL using the set insertion method.

The token string is comprised of two parts from the JWT encoded product: the JWT Payload and the Signature.

When inserted into the request, the token is prefixed by the token name and the equal sign. The token name is "qsig."

Format:
qsig=<jwt payload><signature>

For example:
qsig=eyJraWQiOjAsInR5cCI6InNnbiIsImNudCI6MiwiZXhwIjoxNTU4MzMxNTEyLCJ oc2giOiI5MzUwZjY4MjNlODk5ZDgyYzY2MzQ3YjNkNjFmYzY0YSJ9.SImVd1VIQYJlr ksJe7nd44TqsSAzR80tG3LAsjZt5fg

Examples

In this section, we'll walk through the signing procedure for each of the supported extraction methods, using the following URL structure as an example:

http://www.example.com/<series-name>/<episode-name>/master.m3u8

In this URL structure, the combination of series-name and episode-name serves as a unique identifier for the content and will be present in all subsequent requests of the ABR session.

We'll use the following specific content URL example, based on the above structure.

http://www.example.com/MacGyver/ep5/master.m3u8

Full Path Example

In this section, we'll walk through the signing procedure for the Full Path (typ = 'all') extraction method.

In-Token Regex Match and Hash Example

In this section, we'll walk through the signing procedure for the In-Token Regex Match and Hash (typ = 'rgh') extraction method.

In-Token Regex Match Example

In this section, we'll walk through the signing procedure for the In-Token Regex Match (typ = 'rgm') extraction method.

In-Token Segments Count Example

In this section, we'll walk through the signing procedure for the In-Token Segments Count (typ = 'sgn') extraction method.