Generic Integration Guide for DRM.cloud KMS

The KMS API of the Cloud DRM Service provides encryption keys to the headend (packager) for encrypting content. The Cloud DRM Service can be integrated with several packagers using plug-ins, as described in the Integrations section. For more advanced scenarios, you can use our documented KMS API to obtain encryption keys manually or using custom scripts, as described below.

This guide provides a general workflow for integrating DRM.cloud's Key Management Services (KMS) using CPIX, SPEKE, or SPEKE2 APIs.

Overview of the Integration Process

The integration involves the following steps:

Obtain DRM.cloud Credentials
Acquire Keys from DRM.cloud KMS
Use DRM Keys in Your Packager
Verify the Setup

Step 1: Obtain DRM.cloud Credentials

To integrate with DRM.cloud, you can authenticate using Basic Auth or OAuth, depending on what your packager supports.

Basic Auth

Navigate to the Cloud Video Kit web console.
Go to DRM -> Configuration -> KMS -> Authentication.
Retrieve your Basic Auth Credentials:
- Login: basic_auth_login
- Password: basic_auth_password

Note: If you cannot find Basic Auth credentials in the Cloud Video Kit, please contact support team to enable this option.

OAuth

Alternatively, you can use OAuth for authentication:

In the Cloud Video Kit web console, go to DRM -> Configuration -> KMS -> Authentication.
Retrieve the following credentials:
- Client ID: client_id
- Client Secret: client_secret

Both authentication methods provide secure access to DRM.cloud services. Choose the method based on your packager’s compatibility.

Step 2: Acquire Keys from DRM.cloud KMS

Below steps assume using OAuth token authentication. For Basic Auth: in an Authorization header add value "Authorization: Basic [AUTH]" where [AUTH] is your Basic Auth credentials (Base64-encoded login:password).

1. Obtain an Access Token

To interact with the KMS, first request an access token:

Request:

POST: https://auth.drm.cloud/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
client_id=<basic_auth_login>
client_secret=<basic_auth_password>

Response:

{
  "access_token": "eyJraWQiOiJMSjhZb...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Save the access_token for use in subsequent requests.

2. Request Content Keys and Protection Headers

Make a POST request to the DRM.cloud SPEKE or CPIX endpoint using the acquired access_token.

Endpoint: Replace https://<api-url>/kms/cpix?tenantId=<tenantId> with a URL found in Cloud Video Kit web console at DRM -> KMS.

Request:

curl -X 'POST' \
  'https://{api-url}/kms/cpix?tenantId={tenant-id}' \
  -H 'accept: application/xml' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/xml' \
  --raw -i \
  -d '<cpix:CPIX xmlns:pskc="urn:ietf:params:xml:ns:keyprov:pskc" xmlns:speke="urn:aws:amazon:com:speke" xmlns:cpix="urn:dashif:org:cpix" contentId="{content-id}">
  <cpix:ContentKeyList>
    <cpix:ContentKey kid="5b220272-c6e0-478f-b12a-ac875385fe8a"/>
  </cpix:ContentKeyList>
  <cpix:DRMSystemList>
    <cpix:DRMSystem kid="5b220272-c6e0-478f-b12a-ac875385fe8a" systemId="94ce86fb-07ff-4f43-adb8-93d2fa968ca2">
    <cpix:URIExtXKey/>
    <speke:KeyFormat/>
    <speke:KeyFormatVersions/>
    </cpix:DRMSystem>
    <cpix:DRMSystem kid="5b220272-c6e0-478f-b12a-ac875385fe8a" systemId="edef8ba9-79d6-4ace-a3c8-27dcd51d21ed">
    <cpix:PSSH/>
    </cpix:DRMSystem>
    <cpix:DRMSystem kid="5b220272-c6e0-478f-b12a-ac875385fe8a" systemId="9a04f079-9840-4286-ab92-e65be0885f95">
    <cpix:PSSH/>
    </cpix:DRMSystem>
  </cpix:DRMSystemList>
</cpix:CPIX>'

SystemIDs are constant for each of all three major DRM providers:

System	GUID
Widevine	edef8ba9-79d6-4ace-a3c8-27dcd51d21ed
FairPlay	94ce86fb-07ff-4f43-adb8-93d2fa968ca2
PlayReady	9a04f079-9840-4286-ab92-e65be0885f95

Response: DRM.cloud responds with a CPIX XML containing content keys, PSSH, and Protection

<cpix:CPIX xmlns:pskc="urn:ietf:params:xml:ns:keyprov:pskc" xmlns:speke="urn:aws:amazon:com:speke" xmlns:cpix="urn:dashif:org:cpix">
  <cpix:ContentKeyList>
    <cpix:ContentKey kid="5b220272-c6e0-478f-b12a-ac875385fe8a" explicitIV="wM8K3NLlTdq5h7I1NDq/qg==">
    <cpix:Data>
        <pskc:Secret>
        <pskc:PlainValue>TN4jZ6rr84bIxdhI/pFV8Q==</pskc:PlainValue>
        </pskc:Secret>
    </cpix:Data>
    </cpix:ContentKey>
  </cpix:ContentKeyList>
  <cpix:DRMSystemList>
    <cpix:DRMSystem kid="5b220272-c6e0-478f-b12a-ac875385fe8a" systemId="94ce86fb-07ff-4f43-adb8-93d2fa968ca2">
    <cpix:HLSSignalingData playlist="media">I0VYVC1YLUtFWTpNRVRIT0Q9U0FNUExFLUFFUyxVUkk9InNrZDovL2RybS5vcnMuYXQvYWNxdWlyZS1saWNlbnNlL2ZhaXJwbGF5P0JyYW5kR3VpZD0zMTlmMmNhOS0wZDBjLTRlNWItYmI3MC03MmVmYWU2MWRhZDcmS0lEPTViMjIwMjcyLWM2ZTAtNDc4Zi1iMTJhLWFjODc1Mzg1ZmU4YSZJVj1jMGNmMGFkY2QyZTU0ZGRhYjk4N2IyMzUzNDNhYmZhYSIsS0VZRk9STUFUPSJjb20uYXBwbGUuc3RyZWFtaW5na2V5ZGVsaXZlcnkiLEtFWUZPUk1BVFZFUlNJT05TPSIxIixJVj0weGMwY2YwYWRjZDJlNTRkZGFiOTg3YjIzNTM0M2FiZmFh</cpix:HLSSignalingData>
    </cpix:DRMSystem>
    <cpix:DRMSystem kid="5b220272-c6e0-478f-b12a-ac875385fe8a" systemId="edef8ba9-79d6-4ace-a3c8-27dcd51d21ed">
    <cpix:PSSH>AAAAZ3Bzc2gAAAAA7e+LqXnWSs6jyCfc1R0h7QAAAEcIARIQWyICcsbgR4+xKqyHU4X+ihoFaW5zeXMiJDViMjIwMjcyLWM2ZTAtNDc4Zi1iMTJhLWFjODc1Mzg1ZmU4YSoCU0QyAA==</cpix:PSSH>
    </cpix:DRMSystem>
    <cpix:DRMSystem kid="5b220272-c6e0-478f-b12a-ac875385fe8a" systemId="9a04f079-9840-4286-ab92-e65be0885f95">
    <cpix:PSSH>AAADTHBzc2gAAAAAmgTweZhAQoarkuZb4IhflQAAAywsAwAAAQABACIDPABXAFIATQBIAEUAQQBEAEUAUgAgAHgAbQBsAG4AcwA9ACIAaAB0AHQAcAA6AC8ALwBzAGMAaABlAG0AYQBzAC4AbQBpAGMAcgBvAHMAbwBmAHQALgBjAG8AbQAvAEQAUgBNAC8AMgAwADAANwAvADAAMwAvAFAAbABhAHkAUgBlAGEAZAB5AEgAZQBhAGQAZQByACIAIAB2AGUAcgBzAGkAbwBuAD0AIgA0AC4AMAAuADAALgAwACIAPgA8AEQAQQBUAEEAPgA8AFAAUgBPAFQARQBDAFQASQBOAEYATwA+ADwASwBFAFkATABFAE4APgAxADYAPAAvAEsARQBZAEwARQBOAD4APABBAEwARwBJAEQAPgBBAEUAUwBDAFQAUgA8AC8AQQBMAEcASQBEAD4APAAvAFAAUgBPAFQARQBDAFQASQBOAEYATwA+ADwASwBJAEQAPgBjAGcASQBpAFcAKwBEAEcAagAwAGUAeABLAHEAeQBIAFUANABYACsAaQBnAD0APQA8AC8ASwBJAEQAPgA8AEwAQQBfAFUAUgBMAD4AaAB0AHQAcABzADoALwAvAGQAcgBtAC4AbwByAHMALgBhAHQALwBhAGMAcQB1AGkAcgBlAC0AbABpAGMAZQBuAHMAZQAvAHAAbABhAHkAcgBlAGEAZAB5AD8AQgByAGEAbgBkAEcAdQBpAGQAPQAzADEAOQBmADIAYwBhADkALQAwAGQAMABjAC0ANABlADUAYgAtAGIAYgA3ADAALQA3ADIAZQBmAGEAZQA2ADEAZABhAGQANwA8AC8ATABBAF8AVQBSAEwAPgA8AEQAUwBfAEkARAA+AGUAZgBBAEUAbQBrAEMAWQBoAGsASwByAGsAdQBaAGIANABJAGgAZgBsAFEAPQA9ADwALwBEAFMAXwBJAEQAPgA8AEMASABFAEMASwBTAFUATQA+AGEAegBiAHcANwB3AFgAMgBUAEUAZwA9ADwALwBDAEgARQBDAEsAUwBVAE0APgA8AC8ARABBAFQAQQA+ADwALwBXAFIATQBIAEUAQQBEAEUAUgA+AA==</cpix:PSSH>
    <cpix:SmoothStreamingProtectionHeaderData>LAMAAAEAAQAiAzwAVwBSAE0ASABFAEEARABFAFIAIAB4AG0AbABuAHMAPQAiAGgAdAB0AHAAOgAvAC8AcwBjAGgAZQBtAGEAcwAuAG0AaQBjAHIAbwBzAG8AZgB0AC4AYwBvAG0ALwBEAFIATQAvADIAMAAwADcALwAwADMALwBQAGwAYQB5AFIAZQBhAGQAeQBIAGUAYQBkAGUAcgAiACAAdgBlAHIAcwBpAG8AbgA9ACIANAAuADAALgAwAC4AMAAiAD4APABEAEEAVABBAD4APABQAFIATwBUAEUAQwBUAEkATgBGAE8APgA8AEsARQBZAEwARQBOAD4AMQA2ADwALwBLAEUAWQBMAEUATgA+ADwAQQBMAEcASQBEAD4AQQBFAFMAQwBUAFIAPAAvAEEATABHAEkARAA+ADwALwBQAFIATwBUAEUAQwBUAEkATgBGAE8APgA8AEsASQBEAD4AYwBnAEkAaQBXACsARABHAGoAMABlAHgASwBxAHkASABVADQAWAArAGkAZwA9AD0APAAvAEsASQBEAD4APABMAEEAXwBVAFIATAA+AGgAdAB0AHAAcwA6AC8ALwBkAHIAbQAuAG8AcgBzAC4AYQB0AC8AYQBjAHEAdQBpAHIAZQAtAGwAaQBjAGUAbgBzAGUALwBwAGwAYQB5AHIAZQBhAGQAeQA/AEIAcgBhAG4AZABHAHUAaQBkAD0AMwAxADkAZgAyAGMAYQA5AC0AMABkADAAYwAtADQAZQA1AGIALQBiAGIANwAwAC0ANwAyAGUAZgBhAGUANgAxAGQAYQBkADcAPAAvAEwAQQBfAFUAUgBMAD4APABEAFMAXwBJAEQAPgBlAGYAQQBFAG0AawBDAFkAaABrAEsAcgBrAHUAWgBiADQASQBoAGYAbABRAD0APQA8AC8ARABTAF8ASQBEAD4APABDAEgARQBDAEsAUwBVAE0APgBhAHoAYgB3ADcAdwBYADIAVABFAGcAPQA8AC8AQwBIAEUAQwBLAFMAVQBNAD4APAAvAEQAQQBUAEEAPgA8AC8AVwBSAE0ASABFAEEARABFAFIAPgA=</cpix:SmoothStreamingProtectionHeaderData>
    </cpix:DRMSystem>
  </cpix:DRMSystemList>
</cpix:CPIX>

Understanding values obtained from SPEKE / CPIX

ContentKey (one or more) - AES128 secret encryption key that should be used to encrypt the content. This value should be kept secret and never revealed outside the KMS and packager
PSSH - Protection System Specific Header - header that should be placed in content manifest. This header contain public information for the player to trigger license acquisition proces for given DRM system

Step 3: Use DRM Keys in Your Packager

Parse the CPIX response to extract the following:
- Content Keys: The <pskc:PlainValue> contains the encryption key.
- PSSH Data: Found in <cpix:PSSH>.
- Smooth Streaming Protection Headers: Available in <cpix:SmoothStreamingProtectionHeaderData>.
Configure your packager to use these keys:
- Provide the content keys and PSSH data to your packager.
- Set the appropriate DRM system identifiers (systemId).
Reference your packager’s documentation for specific configuration details.

Step 4: Verify the Setup

Test Encrypted Playback Use a DRM-compatible player to test your encrypted content playback.
Debugging
- Check for errors in your packager logs.
- Use network monitoring tools to confirm communication with DRM.cloud endpoints.
- Verify key delivery through DRM.cloud's monitoring tools.

This general guide applies to most DRM packagers using the CPIX, SPEKE, or SPEKE2 APIs. For further assistance, contact DRM.cloud support.

Overview of the Integration Process​

Step 1: Obtain DRM.cloud Credentials​

Basic Auth​

OAuth​

Step 2: Acquire Keys from DRM.cloud KMS​

1. Obtain an Access Token​

2. Request Content Keys and Protection Headers​

Understanding values obtained from SPEKE / CPIX​

Step 3: Use DRM Keys in Your Packager​

Step 4: Verify the Setup​