Nagra-CMAF - 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 |
|---|---|---|---|
nv-authorizations | JWT | 0..1 | 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. Supported values :
| YES |
profile/streamingMode | Streaming mode. | |
profile/emi | EMI. |
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.
1.2.2. Scheduled key
The scheduled key is optional.
Either the packager provides the 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 or HLS 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.
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 |
|---|---|---|---|---|
Empty | 16426 (CBCS) / Empty | Empty | CMAF signaling for all DRMs: HLS - FPS, PRM, WV DASH - PR, PRM, WV | IV returned in response |
Subset of FPS, PR, PRM, WV | CMAF signaling for the subset given in the request | |||
Other values | Request is rejected | |||
HLS | 16426 (CBCS) / Empty | Empty | CMAF signaling for FPS, PRM, WV | IV returned in response |
Subset of FPS, PRM, WV | CMAF signaling for the subset given in the request | |||
Other values | Request is rejected | |||
DASH | 16426 (CBCS) / Empty | Empty | CMAF signaling for PRM, PR, WV | IV returned in response |
Subset of PRM, PR, WV | CMAF signaling for the subset given in the request | |||
Other values | Request is rejected |