Nagra KSS - API details
1. Request description
1.1. Authentication header
One HTTP header can be set in order to authenticate the tenant:
Header name | Type | Mult | Description |
|---|---|---|---|
|
|
| The SSP authorization token (AuthN) with CKM prilivege. It is mandatory when CKM is deployed in the cloud (AWS deployments). It is optional in case of an on-premise deployment. And an error will be raised when the token :
|
1.2. Request body
The input parameter structure is:
Field name | Mult | Description | Required | |
|---|---|---|---|---|
drmContent | 1 | Content management and security profile information. | YES | |
scheduledKey | 0..1 | The key provided by the encryptor. If missing, the key is generated and managed by the system. | ||
drmList | 0..1 | The list of DRM systems that shall be addressed by this request. | ||
1.2.1. DRM content
The DRM content is mandatory.
Parameter name | Description | Required |
|---|---|---|
drmContentId | DRM content ID. | YES |
profile/distributionMode | Distribution mode. Possible values :
| YES |
profile/streamingMode | Streaming mode. Possible values :
| YES |
profile/emi | EMI. Mandatory in case of CUSTOM streaming mode. Supported EMIs:
|
It allows the encryptor to provide the content ID allocated by the CMS and also security profile used for the management of the keys, the signaling or some associated credentials.
If the EMI is not provided then a default value from the system configuration will be used.
A default value exists for each known streaming mode (DASH and HLS).
If the streaming mode is set as CUSTOM then the EMI is mandatory and a signaling containing private data specific to DRM is returned.
1.2.2. Scheduled key
The scheduled key is optional.
Either the packager provides key ID, key value (and IV) or the application generates them
The timestamp is optional to drive the key rotation
If the timestamp is not set, then the application uses current UTC time
It allows several options:
If scheduled key is not provided, the key rotation mechanism will be used to determine whether or not to generate a new key or to consider the last one. If a new key shall be generated then the current time will be used as the time for which this key is active.
If scheduled key is provided but with no content key, then the time provided will be assumed to be the time for which the returned key shall be active. The key rotation mechanism will be used to determine a valid key. This is the method to use for pre-generate keys to be deliver in pre-delivery.
If scheduled key is provided with a content key by the encryptor, then it will take this key as is and the key rotation mechanism will not be applied.
1.2.3. DRM list
The DRM list is optional, it is the list of DRM system IDs.
It allows the encryptor to provide a predefined set of DRM systems for which the signaling shall be provided.
The application conveys this list of DRM system IDs (optional) to a list of configured DRM (accessed by a signaling URL).
The DRM metadata field of a DRM is for future use and will be used to convey usage rules and access conditions specific to both a content and a DRM system.
2. Response Description
The output parameter structure is:
Parameter name | Field type | Multiplicity | Description |
|---|---|---|---|
status | KeyAndSignalizationStatusType | 1 | The global status of the request. |
errorMessage | xsd:string | 0..1 | Any additional information related to the status in case of errors. |
contentKey | ContentKeyType | 0..1 | The content key to be used to protect the content. It includes the key ID, key value and (optional) IV. It is omitted in case the request failed or if it was provided in the request. |
drmSignalization | DrmSignalizationType | 0..1 | The signaling information according to the provided streaming mode. |
The content key is provided by the key server only if it manages the keys itself, on the opposite when the encryptor provides a key, the application will not provide it in return but still stores it.
One signalization block will be provided for each addressed DRM. This block holds the DRM system id and either DASH, HLS or Custom signaling information (defined by the security profile).
When DASH is required, either a manifest section (XML fragment) or a PSSH box data or both can be provided to be inserted in the manifest/MPD or content.
When HLS is required, then a key URI will be provided to be inserted in a playlist.
When CUSTOM streaming mode (such as progressive download) is required, the signaling is specific to the requested DRM system.
In case an error occurs, then no content key and no signaling will be provided.
3. Relations between the streaming mode, EMI, DRM list and the responses
Streaming mode | EMI | DRM list | Response | IV in Response |
|---|---|---|---|---|
CUSTOM | Empty | Any | Request is rejected | |
Other values | Empty | FPS, WV, PR, PRM | IV returned in response | |
HLS | Empty | Empty | PRM signaling only Assigns EMI AES-128 | IV returned in response |
16425 (SAMPLE_AES) | Empty | FPS, PRM, WV | ||
Subset of FPS, WV, PRM | Subset of FPS, WV, PRM | |||
Other values | Empty | FPS, PRM Assigns given EMI | ||
Subset of FPS, WV, PRM | Subset of FPS, WV, PRM | |||
PR | The key Id, key value, and the IV are generated/saved and returned in the response but not the signalization. | |||
DASH | Empty | Empty | PRM, WV, PR Assigns EMI CENC | IV returned in response |
Subset of PRM, WV, PR | Subset of PRM, WV, PR Assigns EMI CENC | |||
16420 (AESCTR) | Empty | PRM, WV, PR | ||
Subset of PRM, WV, PR | Subset of PRM, WV, PR | |||
Other values | Empty | PRM only | ||
PR | The key Id, key value, and the IV are generated/saved and returned in the response but not the signalization. |