AWS Media Services integration

The purpose of this guide is to help you integrate AWS MediaPackage and MediaConvert with the Cloud DRM service. Cloud DRM supports the CPIX 2.3 specification, which enables secure encryption of your content.

---

Overview

To integrated Cloud DRM with AWS Media Servies for securing your content you must perform two steps:

1. Set up key delivery, using:
   1. AWS Lambda, or
   2. direct API
2. Configure AWS Media Package and/or Media Convert

---

SPEKE

The Cloud DRM service uses SPEKE API for delivering keys to the origin that encrypts the video streams. SPEKE is an XML exchange protocol that uses the CPIX XML scheme.

SPEKE specification: https://docs.aws.amazon.com/speke/latest/documentation/speke-api-specification.html

In a SPEKE request, the origin requests ContentKey and Protection Headers from the DRM systems identified by global GUIDs. Cloud DRM supports the following three DRM systems:

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

GUIDs above should be passed in the systemId attribute of the DRMSystem element of a SPEKE request.

We provide a simple Lambda code that can be used for integrating AWS Media Services (Media Convert or Media Package) with our SPEKE endpoint. For different origins, including on-premise solutions, the SPEKE API should be called directly. SPEKE API returns a set of fields, including a content key and PSSH (Protection System Specific Header) necessary to encrypt streams.

SPEKE endpoint URL is available in the Video Kit console as SPEKE API URL.

Parameters:

1. BrandGuid - a querystring parameter - an identifier of your application (you should also use it for the license acquisition as described above). This identifier is created by Insys VT and identifies the video service.
2. Authorization: Bearer - an HTTP header - an access token from the OAuth endpoint.

Cloud DRM SPEKE API requires OAuth authentication. OAuth endpoint: https://auth.drm.cloud/oauth/token

In order to get an Access Token for communicating with the SPEKE endpoint, you should send the following parameters to the OAuth endpoint:

• grant_type querystring parameter with value client_credentials
• scope querystring parameter - available in web console
• uthorization: Basic HTTP header containing base64 of <AppClientId>:<AppClientSecret> - available in Video Kit console
• empty body

The Access_token value from the response should be used as the Authorization: Bearer header in the SPEKE requests.

---

AWS MediaConvert & MediaPackage for Live

What is a SpekeGateway?

Insys SpekeGateway is a serverless service that adds the authorization layer in the communication between AWS Media Services and Cloud DRM KMS. The services are built with API Gateway and Lambda Function as presented on the diagram below. API Gateway takes local requests from Media Services and forwards them to Cloud DRM, including the appropriate OAUTH headers, by using Lambda. The service should be deployed on the same customer account where Media Services are used.

Deployment using AWS console

Cloudformation Template URL https://insysvt-solutions-euw1.s3.eu-west-1.amazonaws.com/solutions/spekegateway/2.1.0/cloudformation.yaml

When using AWS Media Services for content encryption, you do not need to handle SPEKE requests and responses directly. AWS Media Package or AWS Media Convert generate SPEKE XMLs and consume responses. AWS Media Package and AWS Media Convert only need the URL to API Gateway that passes SPEKE requests to Cloud DRM.

Here is the list of the parameters with mock-up test values and information where you can find your configuration values:

Key name	Example value	Your value
AuthenticationMethod	(leave as is)	(leave as is)
ClientId	26SPEKE0AuthAppIDabcdefghi	Client_Id from Video Kit console
ClientSecret	52SPEKE0AuthAppSecretabcdefeghijklmnopqrstuvwxyz1111	Client_Secret from Video Kit console
TokenUrl	https://auth.drm.cloud/oauth/token	https://auth.drm.cloud/oauth/token
ApiKey	(leave as is)	(leave as is)
SpekeUrl	https://tenantname.api.drm.cloud/kms/speke?tenantId=abcdef-1234-5678-90ab-cdef1234	SPEKE API URL from Video Kit console
GatewayType	(leave as is)	(leave as is)
EnableGatewayLogging	(leave as is)	(leave as is)
LambdaLoggingLevel	(leave as is)	(leave as is)

Deployment steps

1. Go to the Cloudformation console using your web browser.
2. Click the Create stack button and choose the With new resources (standard) option from the list.

3. In the Create stack form, choose the Amazon S3 URL for the Template Source option and enter the link to the Cloudformation template provided by Insys VT into the input field.

4. On the next page, fill up the stack details:

• Stack Name - e.g. insys-spekegateway
• AuthenticationMethod - OAUTH or X-API-KEY, please leave OAUTH
• ClientId and ClientSecret - Parameters required to authenticate with the Cloud DRM (provided by Insys VT)
• TokenUrl - Authentication endpoint
• ApiKey - X-API-KEY alternative authentication method
• SpekeUrl - Cloud DRM SPEKE endpoint for Live and VOD (provided by Insys VT)
• GatewayType - Choose the gateway type. "Private" is available only in VPC, "Regional" is available only in the deployed region, and "Edge Optimized" is deployed over the CloudFront network.
• EnableGatewayLogging - Set this value to true if you want to store the logs from the ApiGateway in CloudWatch Logs (requires properly configured IAM Role for Cloudwatch Logs in API Gateway settings)
• LambdaLoggingLevel - DISABLED, INFO or DEBUG

5. Go to the next page and check if all parameters are correct. At the bottom of the page, check all the boxes and click the Create Stack button.

6. Cloudformation will create a new stack with all required resources. Wait until the process is finished.

7. Check the output parameters of the created stack. Note down the parameters - they will be necessary in the Media Services configuration.

---

AWS MediaPackage for VOD

Packaging groups

Create a Packaging group configuration with your chosen name:

Next, edit the configuration for the packaging group. Add two configurations for the DASH and HLS outputs.

DASH with Widevine and PlayReady

• Id: your chosen name for the Dash configuration
• Package type: DASH-ISO
• Encryption: Enable it to be able to use the DRM.
• Key Server URL: Enter the value of VodSpekeInvokeUrl that you can find in Clouformation’s Output Parameter of SpekeGateway stack (e.g. https://9zruxldlha.execute-api.ap-southeast-2.amazonaws.com/LATEST/vod)
• Role ARN: Enter the value of the MediaPackageVodRole parameter that you can find in Clouformation’s Output Parameter of SpekeGateway stack (e.g. arn:aws:iam::1234567890:role/speke-gateway-MediaPackageVodRole)
• System IDs: IDs for the selected DRM system. For Widevine, it is edef8ba9-79d6-4ace-a3c8-27dcd51d21ed. For PlayReady it is 9a04f079-9840-4286-ab92-e65be0885f95. It's a common practice to add both Widevine and PlayReady to DASH stream.

Example of sample configuration for the DASH endpoint:

HLS with FairPlay

• Id: Your chosen name for the HLS configuration
• Package type: Apple HLS
• Encryption: Enable it to be able to use the DRM.
• Encryption method: sample AES
• Key Server URL: Enter the value of VodSpekeInvokeUrl that you can find in Clouformation’s Output Parameter of the SpekeGateway stack (e.g. https://9zruxldlha.execute-api.ap-southeast-2.amazonaws.com/LATEST/vod)
• Role ARN: Enter the value of the MediaPackageVodRole parameter that you can find Clouformation’s Output Parameter of the SpekeGateway stack (e.g. arn:aws:iam::1234567890:role/speke-gateway-MediaPackageVodRole)
• System IDs: IDs for the selected DRM system. For FairPlay, it is 94ce86fb-07ff-4f43-adb8-93d2fa968ca2 (lower case)

Here is an example of sample configuration for the HLS endpoint:

Ingesting assets in AWS MediaPackage

In order to ingest the asset from the S3 bucket, you need to create a smil file describing the asset. Here is an example of a smil file:

<?xml version="1.0" encoding="utf-8"?>
<smil>
  <body>
    <switch>
      <video src="06000000-a9fe-0a58-0a37-08dcff18b8d4_360p.mp4" includeAudio="false" />
      <video src="06000000-a9fe-0a58-0a37-08dcff18b8d4_576p.mp4" includeAudio="false" />
      <video src="06000000-a9fe-0a58-0a37-08dcff18b8d4_720p.mp4" includeAudio="false" />
      <video src="06000000-a9fe-0a58-0a37-08dcff18b8d4_1080p.mp4" systemLanguage="eng" audioName="audio" />
    </switch>
  </body>
</smil>

You need to have an smil file for every asset that you want to package:

Go to the Assets tab and proceed to Ingest Asset.

• S3 bucket name: bucket with the desired source material
• IAM role: ARN of IAM role that has read access to the provided S3 bucket
• Filename: an smil file describing the asset
• Id: an identifier for the asset
• Resource Id: It can be a random guid.
• Packaging group: Choose the previously created packaging group.

You need to have an smil file for every asset that you want to package: