Integrating Axinom DRM Key Service with AWS MediaConvert

Introduction

This guide is aimed at Axinom’s customers who want to create DRM encrypted content with AWS MediaConvert. It demonstrates how to encode a video and apply DRM protection to it.

note

This document outlines the steps for integrating with the SPEKE V1 protocol. As of November 2024, AWS has introduced support for the SPEKE V2 protocol in MediaConvert, which we recommend using due to its enhanced capabilities, including multi-key encryption for improved content security. For more details, please refer to our SPEKE V2 documentation.

Pre-Requisites

The prerequisites for integrating Axinom DRM Key Service with AWS MediaConvert are:

Access to Amazon Web Services (AWS)
A video file in the mp4 format in an AWS S3 bucket

Logging in to the AWS Console

Setting up the AWS API Gateway

The API Gateway is the main point of integration with Axinom Key Service. The API Gateway is configured to provide an endpoint that proxies key requests from various AWS media services (such as MediaConvert and MediaPackage) to Axinom Key Service. Information is exchanged according to the Secure Packager and Encoder Key Exchange (SPEKE) specification. For information on SPEKE, see AWS documentation at https://docs.aws.amazon.com/speke/latest/documentation/what-is-speke.html.

Open the AWS API Gateway console at https://console.aws.amazon.com/apigateway.
Create a new API:
1. To create an initial API, click Create API -> REST API and then Build.
2. Set general API settings:
  - API creation method: New API.
  - API name: "Axinom Key Service SPEKE".
  - Endpoint type: Regional.
3. Click Create API.
4. Click Create Method.
Method Type - Post
Configure the POST method:
1. Integration type: HTTP.
2. Use HTTP Proxy integration: yes.
3. HTTP method: POST.
4. Endpoint URL: https://key-server-management.axprod.net/api/Speke. You can find the URL valid to your tenant from My Mosaic.(This is the Axinom Key Service SPEKE endpoint).
  
  note
  To start using SPEKE V2, be sure to update the endpoint in your configuration to: https://key-server-management.axprod.net/api/SpekeV2.
  1. Content Handling: Passthrough.
  2. Use Default Timeout: yes.
  3. Click Create Method.
Add an authorization header to the POST method:
1. Go to the POST - Method Execution pane and choose Integration Request.
2. Click Edit.
3. Click URL request headers parameters.
4. Specify the Basic HTTP authentication header using your Axinom Key Service Management API credentials:
  - Name: Authorization.
  - Mapped from: 'Basic <credentials>', where <credentials> are the Base64-encoded Tenant ID and Management Key GUID strings joined by a colon. The single quotes must be included.
    
    Example:
    
    If the Tenant ID is 2028718f-1edd-482a-b6b5-8067e93cfbfa and the Management Key is e0b81b34-dd82-4897-89f2-bdf32d7023f7 then the resulting "Mapped from" value should be 'Basic MjAyODcxOGYtMWVkZC00ODJhLWI2YjUtODA2N2U5M2NmYmZhOmUwYjgxYjM 0LWRkODItNDg5Ny04OWYyLWJkZjMyZDcwMjNmNw=='.
5. Save the changes.
Test the API configuration:
1. Go to TEST.
2. Paste a valid SPEKE request inside the Request Body box.
  
  An example of a valid SPEKE request
```
<?xml version="1.0" encoding="UTF-8"?>
<cpix:CPIX id="Test" xmlns:cpix="urn:dashif:org:cpix" xmlns:pskc="urn:ietf:params:xml:ns:keyprov:pskc" xmlns:speke="urn:aws:amazon:com:speke">
	<cpix:ContentKeyList>
		<cpix:ContentKey kid="c158dedd-2d45-43b7-a7ac-aed65511a884"/>
	</cpix:ContentKeyList>
	<cpix:DRMSystemList>
		<cpix:DRMSystem kid="c158dedd-2d45-43b7-a7ac-aed65511a884" systemId="edef8ba9-79d6-4ace-a3c8-27dcd51d21ed">
			<cpix:ContentProtectionData />
			<speke:ProtectionHeader />
			<cpix:PSSH />
			<cpix:URIExtXKey />
			<speke:KeyFormat />
			<speke:KeyFormatVersions />
		</cpix:DRMSystem>
	</cpix:DRMSystemList>
</cpix:CPIX>
```
3. Click Test.
  - If the configuration is correct and a valid SPEKE request was provided, Axinom Key Service returns 200 OK with the SPEKE response in the response body.
  - If an authentication error occurred, Axinom Key Service returns 401 Unauthorized. In that case, check that the authorization header contains a valid Base64-encoded string, as explained in the above step.
4. Click Deploy API.
5. Deployment stage: [New Stage].
6. Stage name: "TestStage".
7. Choose Deploy.
  - If the configuration is later changed, the API must be redeployed for the update to be enabled to other services.
8. Note down the API Invoke URL. This will be provided to AWS media services as the key service URL.

Setting up the Identity and Access Management Role

Before configuring MediaPackage, it is necessary to create an Identity and Access Management (IAM) role that allows MediaPackage to call the API Gateway.

Open the AWS IAM console at https://console.aws.amazon.com/iam.
Create a new role:
1. Choose Roles from the left menu.
2. Click Create role.
3. Select AWS service entity type -> MediaConvert service -> MediaConvert use case.
4. Click Next -> Next.
5. Provide role information:
  1. Role name: "MediaConvertRole".
  2. Click Create role.

Setting up MediaConvert

MediaConvert allows encoding Video on Demand (VOD) content while applying DRM protection to it. This chapter shows how to create a simple DRM-protected MediaConvert job with an mp4 video input.

Open the AWS MediaConvert console at https://console.aws.amazon.com/mediaconvert.
Create a new MediaConvert job by clicking Create job on the right side:
1. In the Input pane, click "Browse" and choose an input file from an S3 bucket.
  1. From the S3 bucket menu, choose the location of the input file by clicking the drop-down arrows. Once the file is chosen, click Choose.
2. In the Create job pane, in the Output groups section, click add to add an output group. Output groups are different files that are present once the job finishes. Most output groups are audio or video files.
  1. From the list in the Add output group, choose the preferred output group and then click Select. In this example we are selecting "DASH ISO".
3. In the group settings of the relavent output group next to the Destination value, click Browse and select a destination for the output of the convert job.
4. Add DRM information by clicking the small slider next to DRM encryption and fill in the following fields.
  1. For DASH ISO you need to pass a Resource ID, System ID and Key provider URL.
    1. Resource ID is an arbitrary value that MediaPackage uses to generate content key IDs. Enter any value, e.g. "SampleResourceID". It will be passed in the CPIX document on the root element in the attribute "id".
    2. System ID is a DRM system-specific identifier, see DRM systems. AWS MediaConvert does not allow more than two entries.
    3. Key provider URL****Key provider URL- use the Invoke URL created in the Setting up the AWS API Gateway.
      note
      If 'CMAF' is used with the encryption method 'AES-CBC subsample', the optional 'protectionScheme' parameter in the Key Service URL must be set to 'cbcs'.
      https://key-server-management.axprod.net/api/Speke?protectionScheme=cbcs
    4. Other settings can be left to defaults.
  2. For Apple HLS you need to select the "Encryption method" from the drop down in the DRM encryption section. Select "Sample AES" from the drop down where "AES-128" method cannot be used with Fairplay.
    1. Initialization Vector is a drop-down for you to decide whether you need to include the 128-bit encryption initialization vector in the HLS and DASH manifests.
    2. Constant initialization vector is an optional value. You can provide a 128-bit, 16-byte hex value represented by a 32-character text string. If this parameter is not set then the Initialization Vector will follow the segment number by default.
5. At the bottom of the page, in the Outputs, click Add output. Having separate outputs for audio and video is a standard practice in the streamed media that many players require.
  1. Add name modifiers to the outputs. One should be for video and the other for audio.
6. In the Output groups section, click Output 1.
  1. Since this will be the video output, remove the audio part from Output 1. In the Encoding settings, click Audio 1 and then click Remove audio.
  2. Make sure Bitrate (bits/S) is defined. You can use "5000000", for example.
7. In the Output groups section, click Output 2.
  1. Since this will be the audio output, remove the video part in the Output 2 by selecting Video in the Encoding settings of Output 2 and clicking Remove video.
8. In the Job settings, click Settings and add the IAM role by clicking the drop-down labeled IAM role and choose the role created in Setting up the Identity and Access Management Role.
To create an encoding job, click Create in the bottom-right of the page.
1. The page that opens displays the "SUBMITTED" job status. Wait for some time and reload the page by clicking the Refresh button. The time that it takes for the MediaConvert job to complete depends on the size of the input file.
  1. Wait for the job to finish. The job is finished when the status changes to "COMPLETE".
2. To view the output of the job, click the DASH ISO link in the Outputs pane.
3. In the Output folder, there should be the output files and the .mpd manifest.
4. Test the playback of the encrypted DASH content with any player that has been integrated with Axinom DRM. For example, you can use Axinom VTB service, accessible at https://vtb.axinom.com/.
  1. Host the output files and the manifest file at a location that can be accessed via a network connection, either locally or from the Internet. Provide an Axinom DRM License Server Message (license token) in the Token field in the Axinom VTB service. For more information on the license token (JWT), refer to the Axinom DRM License Service Message document.

Introduction​

Pre-Requisites​

Logging in to the AWS Console​

Setting up the AWS API Gateway​

Setting up the Identity and Access Management Role​

Setting up MediaConvert​