If you are using Contego/Conax products, please refer to the documentation available at https://doc.integra.nagra.com/.

See also

OTT DRM Signaling generated by SSP key server.

This page lists the key server interfaces that are supported in SSP and provides some insights about how to use them to integrate an OTT packager/encryptor with SSP.

1. NAGRA Encoder KSS

This API has been defined by NAGRA to ease the integration of its key server. This API is supported by previous versions of NAGRA key server products, in addition to the key services included with SSP.

1.1. Packager Authentication

When deployed in AWS, this API requires an SSP Authentication token with CKM privilege associated to it. This token is not mandatory when deployed on-premise.

1.2. DRM Support

This API supports PlayReady, Widevine, FairPlay, and NAGRA PRM (CONNECT and software PRM flavors).

1.3. Key Handling and Key Rotation

This interface allows an OTT packager to retrieve, purge, and upload content keys into SSP key server in either of two ways:

  • The packager includes only the content identifier in the request. In this case, the SSP key server will generate the key ID and key value.
  • The packager includes the content identifier, key identifier, and key value in the request. In this case, the SSP key server will store this data so that it is accessible later for license delivery.

NAGRA Encoder KSS supports a different key and key ID per encryption method for the same content ID.

Key rotation for live is supported over this API. The packager can optionally specify a timestamp to indicate the time validity of each key. Subsequent keys must be requested in advance to enable temporal license pre-delivery.

1.4. API Specification

NAGRA Encoder-KSS API specification is available from here.

2. Harmonic KMS

Harmonic KMS is a variant of the NAGRA Encoder KSS API that is implemented by certain Harmonic products.

In terms of packager authentication, DRM support, and key rotation support, please refer to the previous point.

2.1. API Specification

Harmonic KMS API specification is available from here.

3. Conax Key Server API

This API has been incorporated in SSP as part of the multi-DRM convergence between SSP and Contego products.

Wowza Streaming Engine can be easily integrated with SSP through a custom module provided by NAGRA that integrates SSP key server over this API.

3.1. Packager Authentication

Content key exchanges are authorized using an HTTP basic authentication schema. Each HTTP request must include an Authorization header containing the user name and password encoded in Base64, separated by colon (":") and prefixed with "Basic".

The username and password must be exchanged between NAGRA and the operator prior to starting integration using this API.

SSL is mandatory when using HTTP basic authentication over public networks.

3.2. DRM Support

This API supports PlayReady, Widevine, FairPlay, and NAGRA PRM (CONNECT and software PRM flavors).

The API allows the packager to specify the subset of DRMs for which the content key is being requested.

3.3. Key Handling and Key Rotation

This API requires that the packager sends the content identifier in the request. The key server will generate the key identifier and key value.

Key upload mode is not supported.

Key rotation is not supported using this API.

4. Widevine DRM Common Encryption API

This API is promoted by Google to ease the integration of Widevine DRM using tools like Shaka packager and player.

4.1. Packager Authentication

Content key exchanges are signed with a credential (key and IV) pre-shared between the packager and the key server (similar to the Widevine proxy credentials).

SSL is mandatory for encryption. Payload encryption using a session key is not supported by NAGRA key server.

4.2. DRM Support

SSP key server supports PlayReady and Widevine using Widevine DRM Common Encryption API.

4.3. Key Handling and Key Rotation

Widevine Common Encryption mandates that the packager sends the content ID in the request. No key IDs or values can be included. It is the key server's responsibility to generate the key ID and key values for each request.

Key rotation is supported by NAGRA Key Server over this API.

4.4. API Specification

Widevine Common Encryption API specification is available from here.

5. AWS Elemental SPEKE

SPEKE is an API promoted by AWS Elemental to integrate key servers with AWS Media Services. It is a subset of DASH-IF CPIX.

This interface is only available for SSP AWS deployments.

5.1. Packager Authentication

AWS Elemental proposes an AWS cloud-based architecture where the encryptor requests content keys from the DRM key provider using AWS IAM roles and AWS API Gateway.

The procedure is as follows:

  1. The operator who wants to integrate SSP key server using SPEKE request the AWS API Gateway resource name (ARN in AWS parlance) deployed in the corresponding AWS region from NAGRA.
  2. The operator generates an IAM role to allow access to that NAGRA API Gateway and shares this role's ARN with NAGRA.
  3. NAGRA CloudOps updates the SSP API Gateway configuration with the role's ARN.
  4. The operator can then send key requests from AWS Media Services to the SSP key server over the SPEKE interface.

5.2. DRM Support

This API supports PlayReady, Widevine, FairPlay, and NAGRA PRM (CONNECT and software PRM flavors). The same key ID applies to all DRMs specified in a single request.

5.3. Key Handling and Key Rotation

In SPEKE, the packager provides the content ID and key ID in the request. The key server generates the key value for that content ID and key ID pair.

SPEKE supports key rotation.

  • In CPIX, a ContentKeyPeriod can use either an index or start and end timestamps. SPEKE only supports ContentKeyPeriod@index to track the key period.
  • In AWS Elemental MediaPackage, the operator can configure a key rotation period in seconds. In this case, MediaPackage will trigger a new key request every period with a different key ID and increment the value of the ContentKeyPeriod@index in each request.
  • The packager must not send multiple key IDs in a single request to NAGRA key server over SPEKE.

Overriding the key ID in the key server is not supported.

5.4. API Specification

AWS Elemental SPEKE specification is available from here.

6. DASH-IF Content Protection Information eXchange

Content Protection Information eXchange (CPIX) is an API promoted by the DASH-IF forum that aims to standardize the exchange of keys and DRM information used for encrypting and protecting content.

SSP supports CPIX v2.3.

6.1. Packager Authentication

When SSP is deployed in the public cloud, this API requires an SSP Authentication token with CKM privilege associated to it. This token is not mandatory when deployed on-premise.

The token must be sent as an HTTP header named "nv-authorizations" with every request.

6.2. DRM Support

This API supports PlayReady, Widevine, FairPlay, and NAGRA PRM (CONNECT and software PRM flavors).

6.3. Key Handling and Key Rotation

SSP supports the following sub-set of the CPIX specfication:

  • Content Key delivery to one single Entity within a CPIX document (where the "contentId" attribute within a CPIX element must contain the identifier of the video asset)
  • Both Encryptor Consumer and Encryptor Producer workflows
  • On-demand and Live content preparation, including key rotation for live
  • Optionally, usage of commonEncryptionScheme tag to segment content keys per encryption scheme (CPIX v2.3).

The following use cases are currently not supported:

  • CPIX document encryption (partial or complete).
  • CPIX document signature.
  • Content Key delivery to several entities.
  • The same contentId value cannot be used for both VoD and Live.

6.3.1. Encryptor Consumer Workflow

The OTT packager acting as encryptor pulls the content keys and DRM signaling from the SSP key server as follows:

  • The Encryptor provides the Content ID, the target DRM(s), and Content Key Id(s) in the request.
  • The SSP Key Server generates the required Content Key(s) and IV value(s) and returns them in the response along with the requested DRM signaling.

6.3.2. Encryptor Producer Workflow

The OTT packager acting as encryptor pushes the content key(s) to the SSP key server:

  • The Encryptor provides the Content ID, the target DRM(s), and Content Key Id(s) in the request (and IV if FPS is requested).
  • The SSP Key Server then generates the required DRM signaling and returns it in the response.

6.3.3. Content Key Rotation

A CPIX document can contain protection information for multiple crypto periods, or for period of time for content encrypted using key rotation.

In this case, the request must contain one or multiple ContentKeyPeriod elements. Each element must include start and end attributes. (The SSP key server does not support index based ContentKeyPeriod.)

The SSP Key Server generates a response providing the requested information (keys and DRM signaling) per ContentKeyPeriod in the request.

6.3.4. Key ID override

In a CPIX document, the key ID is mandatory, whether it is a request from the packager or a response from the key server.

This means that the packager needs to generate the content key identifiers and maintain their relationship with the content identifiers.

In cases where this relationship cannot be persisted in the packager, the SSP key server can be configured to override the content key identifier. When this configuration is active, the key server ignores the key ID sent by the packager in the request. It generates its own key ID and returns it with the response. This key ID is persisted by the key server and it will be returned for subsequent requests for the same content.

This behaviour applies to the "encryptor consumer workflow" with or without key rotation and key per track.

Key ID override behaviour will not be applied by default – it has to be activated via tenant configuration. Please contact your NAGRA support team for this purpose.

6.3.5. Key per track

CPIX supports the exchange of different keys per content track (e.g., audio, SD, HD). This can be used to increase the security of the OTT solution:

  • Protect the video stream with a different key from the audio
  • Limit HD stream decryption to devices with a certain security level or enforce stricter output control rules for HD content than SD content.

The feature is supported by SSP Key Server for both Encryptor Consumer and Encryptor Producer workflows. In both cases, the CPIX document indicates the target of the content key using CPIX ContentKeyUsageRule and LabelFilter or intendedTrackType elements.

6.3.6. Segment keys by encryption scheme

Starting from CPIX 2.3, the commonEncryptionScheme attribute can be used to assign different keys for the same content based on the encryption scheme (cenc, cbcs).