Skip to main content

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​

Log in to the AWS Management Console at https://console.aws.amazon.com.

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.

  1. Open the AWS API Gateway console at https://console.aws.amazon.com/apigateway.

  2. 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.

        GatewayAPI-General

    3. Click Create API.

    4. Click Create Method.

      GatewayAPI-createMethod-2

  3. Method Type - Post

  4. 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. Integration Timeout: keep the default value(29000).

        GatewayAPI-ConfigurePost

      3. Click Create Method.

  5. Add an authorization header to the POST method:

    1. Go to the POST - Method Execution pane and choose Integration Request.

    2. Click Edit.

      GeneralAPI-POSTmethodExecution

    3. Click URL request headers parameters and then click Add request header parameter

    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. (you can use our Base64 conversion tool for this.)

        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=='.

        GatewayAPI-AddHeaders2

    5. Save the changes.

  6. 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>
      note

      • If you are using SPEKE V2, you can get a sample SPEKE 2.0 request from here.

      • For SPEKE 2.0 to work, you need to add the following HTTP Header to your request:

           X-Speke-Version: 2.0

        This header must inlcude in the Headers under the Test section.

    3. Click Test.

      GatewayAPI-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 under URL request headers parameters, contains a valid Base64-encoded string as explained.

    4. Click Deploy API.

      GeneralAPI-DeployAPI

    5. Deployment stage: [New Stage].

    6. Stage name: "TestStage".

      GeneralAPI-DeployAPI-2

    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.

      GatewayAPI-InvokeURL-2

Setting up the Identity and Access Management Role​

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

  1. Open the AWS IAM console at https://console.aws.amazon.com/iam.
  2. 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.

      IAM-MediaConvertTemplate

    4. Click Next -> Next.

    5. Provide role information:

      1. Role name: "MediaConvertRole".

        IAM-CreateRole1

      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.

  1. Open the AWS MediaConvert console at https://console.aws.amazon.com/mediaconvert.

  2. Create a new MediaConvert job by clicking Get started under Create a job section.

    Convert-GetStarted

    1. In the Input pane, click Browse and choose an input file from an S3 bucket.

      Convert-InputField

      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.

        Convert-ChooseLocation

    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.

      Convert-OutputGroup

      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.

        Convert-AddOutputGroup

    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.

      Convert-AddDestination

    4. Add DRM information by clicking the small slider next to DRM encryption and fill in the following fields.

      1. If you choose DASH ISO as the output group in the previous step, 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- use the Invoke URL created in the Setting up the AWS API Gateway.

          note

          If you are using SPEKE V2, SPEKE version as SPEKE v2.0 from the drop down

        4. Other settings can be left to defaults.

          Convert-AddDRM

      2. If you choose Apple HLS as the output group in the previous step, 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.

        Convert-AddEncryptionMethod

        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.

      3. If you choose CMAF as the output group in the previous step, with the encryption method 'AES-CBC subsample', the optional 'protectionScheme' parameter in the Key Service URL must be set to 'cbcs' as below. This Key Service URL is needed when setting up the API Gateway.(Step 4 under Setting up the AWS API Gateway)

          https://key-server-management.axprod.net/api/Speke?protectionScheme=cbcs

    5. At the bottom of the page, you can see two default outputs for audio and video in the Outputs section. Having separate outputs for audio and video is a standard practice in the streamed media that many players require.

      1. If you want to add another output, click Add output and add a "Name modifier". Convert-OutputsWindow

    6. In the Output groups section, click H.264,_0utput1.

      Convert-Output1Select

      1. You can select Video codec, and other video settings here.
      2. Make sure Bitrate (bits/s) is defined. You can use "5000000", for example.

      Convert-BitRate

    7. In the Output groups section, click AAC_output2 and select the audio settings.

      Convert-Output2Select

    8. In the Job settings section, click AWS integration and add the IAM role by clicking the drop-down labeled Service role and choose the role created in Setting up the Identity and Access Management Role.

      Convert-AddIAM

  3. To create an encoding job, click Create in the bottom-right of the page.

    Convert-CreateFinalJob

    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.

      Convert-JobWait

      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.

      Convert-OpenOutput

    3. In the Output folder, there should be the output files and the .mpd manifest.

      Convert-S3Output

    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.