Integrating Axinom DRM Key Service with AWS MediaLive/MediaPackage

It is possible to integrate Axinom Key Service Secure Packager and Encoder Key Exchange (SPEKE) with Amazon Web Services MediaLive and MediaPackage. The following article provides you step-by-step guidelines for doing so.

note

Please note that this MediaPackage guide is tested against Media Package v1 and may not work with v2.

Start

API Gateway Setup

This is the main point of integration with Axinom Key Service. The API Gateway is configured to provide an endpoint that proxies key requests between various AWS media services (such as MediaPackage and MediaConvert) and Axinom Key Service. Information is exchanged according to the SPEKE specification.

For information on SPEKE, see the AWS documentation: https://docs.aws.amazon.com/speke/latest/documentation/what-is-speke.html

Open the AWS API Gateway console: https://console.aws.amazon.com/apigateway
Create a new API:
1. Choose Get Started and OK (if creating the first API) or Create API (if creating a subsequent API).
2. When you get to choose the API type, select the Rest API
3. Set general API settings:
  - Protocol: REST.
  - API creation method: New API.
  - API name: "Axinom Key Server SPEKE".
  - Endpoint type: Regional.
4. Choose Create API.
Add a POST method to the API:
1. Select Resources -> Methods -> Create Method.
2. Configure the POST method:
  1. Method type : POST
  2. Integration type: HTTP.
  3. Use HTTP Proxy integration: yes.
  4. HTTP method: POST.
  5. Endpoint URL: https://key-server-management.axprod.net/api/SpekeV2?overrideKeyIds=true (this is the Axinom Key Service SPEKE V2 endpoint, with "key override" enabled). Should there be a need to use the older SPEKEv1 protocol, make sure the set the SPEKEv1 URL here. Refer to SPEKE V1 for further details.
  6. Content Handling: Passthrough.
  7. Use Default Timeout: yes.
  8. Choose Save.
Add an authorization header to the POST method:
1. Go to the POST - Method Execution pane and choose Integration Request.
2. Click Edit
3. Expand URL request headers parameters and choose Add request header parameters.
4. Specify the Basic HTTP authentication header using your Axinom Key Service Management API credentials:
  - Name: "Authorization".
  - Mapped from: 'Basic <credentials>', where <credentials> is the base64 encoding of your Tenant ID and key service Management Key value as GUID strings joined by a colon. The single quotes must be included.
    
    :
    
    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 MjAyODcxOGYtMWVkZC00ODJhLWI2YjUtODA2N2U5M2NmYmZhOmUwYjgxYjM0LWRkODItNDg5Ny04OWYyLWJkZjMyZDcwMjNmNw=='`.
5. Save the changes.
Test the API configuration:
1. For testing purposes only you have to add X-Speke-Version: 2.0 header. Remember to remove it after this test.
2. Choose TEST in the POST - Method Execution pane.
3. Paste a valid SPEKE request inside the Request Body box. You can find a valid SPEKE V2 request from here
4. Choose 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 there’s an issue with authentication then Axinom Key Service returns 401 Unauthorized. In that case, re-check the authorization header.
Remember to remove the X-Speke-Version header you have added for the test. Because Media Package will automatically add the X-Speke-Version header to it’s request and having duplicate headers will cause errors.
Deploy the API:
1. Select Resources -> Actions -> Deploy API.
2. Deployment stage: [New Stage].
3. Stage name: "TestStage".
4. Choose Deploy.
  - If the configuration is later changed, the API should be redeployed for the update to be visible to other services.
5. Note down the API Invoke URL. This is provided to AWS media services as the key service URL.

IAM (Identity and Access Management) Setup

Before configuring MediaPackage, it is necessary to create an IAM role that allows MediaPackage to call the API Gateway.

Open the AWS IAM console: https://console.aws.amazon.com/iam
Create a new role:
1. Choose Roles from the left menu.
2. Choose Create role.
3. Select AWS service entity type -> MediaConvert service -> MediaConvert use case (we use a modified MediaConvert role since MediaPackage doesn’t have a suitable default role).
4. Choose Next: Permissions.
5. Provide role information:
  1. Role name: "MediaPackageRole".
  2. Role description: "Allows MediaPackage to call API Gateway on your behalf."
  3. Choose Create role.
Configure the role:
1. Select the new MediaPackageRole from the list of existing roles.
2. Choose the Trust relationships tab.
  1. Choose Edit trust relationships.
  2. Replace "mediaconvert.amazonaws.com" in the JSON with "mediapackage.amazonaws.com".
  3. Choose Update Trust Policy.
3. Choose the Permissions tab.
  1. Detach the AmazonS3FullAccess policy. For this demo, MediaPackage doesn’t need S3 access.
Note down the MediaPackageRole Role ARN. It is used in the following steps.

MediaPackage Setup

MediaPackage takes a live stream sent by the MediaLive service (configured in the next section) and then packages it as DASH and CMAF content while obtaining keys from Axinom Key Service via the previously configured API Gateway proxy service.

Encrypted DASH content is created for playback with Widevine and PlayReady DRM; encrypted CMAF (HLS + fMP4) for playback with FairPlay. Clear versions of both types of content are also created.

Open the AWS MediaPackage console: https://console.aws.amazon.com/mediapackage
Create a new channel:
1. Choose Next step in the Create a new channel pane.
2. Configure the channel:
  - ID: "MediaPackage-Channel01"
  - Input type: Apple HLS
  - Choose Create. A channel with two inputs is created.
    
    note
    Note down the URL, username and password of both inputs. They are used later when configuring MediaLive.
Add an endpoint for clear DASH content:
1. Choose Add endpoints.
2. Configure the endpoint:
  - ID: "DASH-Clear".
  - Manifest Name: "Manifest".
  - Packager settings -> Type: select DASH-ISO.
  - Package encryption -> select No encryption.
3. Choose Save.
Add an endpoint for the encrypted DASH content:
1. Choose Add/edit endpoints.
2. Choose Add.
3. Configure the endpoint:
  - ID: "DASH-Encrypted".
  - Manifest Name: "Manifest".
  - Packager settings -> Type: select DASH-ISO.
  - Package encryption -> select Encrypt content and provide the following:
    - Resource ID: "EncryptionTest" (an arbitrary value that MediaPackage uses for generating content key IDs).
    - System ID is a DRM system-specific identifier, see DRM systems.
    - URL: <API Gateway Invoke URL for Axinom Key Service> (the value from the API Gateway setup).
    - Role ARN: <IAM MediaPackage role ARN> (the value from the IAM setup).
  - Disable key rotation to simplify license token generation for testing purposes:
    - Expand Additional configuration and unselect Key rotation interval (sec).
4. Choose Save.
Add an endpoint for clear CMAF content:
1. Choose Add/edit endpoints.
2. Choose Add.
3. Configure the endpoint:
  - ID: "CMAF-Clear".
  - Manifest Name: "Manifest".
  - Packager settings -> Type: select Common Media Application Format (CMAF).
  - HLS manifest -> ID: "CMAF-Clear".
  - Package encryption -> select No encryption.
4. Choose Save.
Add an endpoint for the encrypted CMAF content:
1. Choose Add/edit endpoints.
2. Choose Add.
3. Configure the endpoint:
  - ID: "CMAF-Encrypted".
  - Manifest Name: "Manifest".
  - Packager settings -> Type: select Common Media Application Format (CMAF).
  - HLS manifest -> ID: "CMAF-Encrypted".
  - Package encryption -> select Encrypt content and provide the following:
    - Resource ID: "EncryptionTest" (an arbitrary value that MediaPackage uses for generating content key IDs).
    - System IDs: "94CE86FB-07FF-4F43-ADB8-93D2FA968CA2" (FairPlay System ID).
    - URL: <API Gateway Invoke URL for Axinom Key Service> (the value from the API Gateway setup).
    - Role ARN: <IAM MediaPackage role ARN> (the value from the IAM setup).
  - Disable key rotation to simplify license token generation for testing purposes:
    - Expand Additional configuration and unselect Key rotation interval (sec).
4. Choose Save.
Note down the endpoints URLs. These are used when testing playback.

MediaLive Setup

Now the MediaLive service can be configured to ingest a live stream and send it to the MediaPackage service for packaging. In this demo, we take a clear live HLS stream from an external source and package it into two live DASH streams: one clear and one encrypted.

Open the AWS MediaLive console: https://console.aws.amazon.com/medialive
Create a new channel:
1. Choose Create channel in the Get started pane.
2. Channel name: "MediaLive-Channel01".
3. Create MediaLive IAM role for the channel:
  1. Select Create role from template (alternatively, select a suitable existing role).
  2. Choose Create IAM role.
4. Add channel inputs:
  1. In the Input attachments section of the Channel pane, choose Add.
  2. Choose Create input in the Attach input pane.
  3. Configure the input:
    - Input name: "MediaLive-Input".
    - Input type: select HLS.
    - Input source A URL: "https://cph-p2p-msl.akamaized.net/hls/live/2000341/test/master.m3u8".
    - Input source B URL: "https://cph-p2p-msl.akamaized.net/hls/live/2000341/test/master.m3u8".
      
      note
      It is recommended to provide your own input sources. The example sources may or may not be available.
      
      note
      As tested during the creation of this guide, the HLS input type expects MPEG2-TS content and does not work with fMP4 HLS input.
  4. Choose Create.
  5. Select MediaLive-Input as the Input in the Attach input pane.
  6. Choose Confirm.
5. Add channel outputs:
  1. In the Output groups section of the Channel pane, choose Add.
  2. Output group type: choose HLS.
  3. Choose Confirm.
  4. Configure HLS group destination A (refer to the values of the first MediaPackage input noted down previously):
    1. URL: <MediaPackage-Channel01 Input #1 URL>.
    2. Expand Credentials.
    3. Username: <MediaPackage-Channel01 Input #1 Username>.
    4. Select Create parameter in the Password section.
    5. Name: "MediaPackage-Channel01-Credentials01".
    6. Password value: <MediaPackage-Channel01 Input #1 Password>.
    7. Choose Create parameter.
  5. Configure HLS group destination B (refer to the values of the second MediaPackage input noted down previously):
    1. URL: <MediaPackage-Channel01 Input #2 URL>.
    2. Expand Credentials.
    3. Username: <MediaPackage-Channel01 Input #2 Username>.
    4. Select Create parameter in the Password section.
    5. Name: "MediaPackage-Channel01-Credentials02".
    6. Password value: <MediaPackage-Channel01 Input #2 Password>.
    7. Choose Create parameter.
  6. Configure HLS settings:
    - Choose HLS webdav in the CDN Settings section (this is required for sending content to MediaPackage).
6. Choose Create channel.
Choose Start to start the channel and wait until it’s in the Running state.

note
When the Running state is reached it may take an additional minute before the stream is available.

Playback Test

Playback can be tested on the Axinom Video Test Bench website.

Open the VTB site: https://vtb.axinom.com. Use a suitable browser for the content being tested:
- Playback of clear content doesn’t have browser restrictions.
- To play the encrypted DASH content with Widevine, use Chrome or Firefox.
- To play the encrypted DASH content with PlayReady, use Edge or IE.
- To play the encrypted CMAF content (FairPlay-protected), use Safari.
Test DASH-Clear playback:
1. Select Shaka player.
  
  note
  For DASH content, we recommend Shaka player because the latest Dash.js players were unable to play some of the content produced in this demo.
2. Stream URL: <MediaPackage DASH-Clear endpoint URL>.
3. Leave rest of the fields blank.
4. Choose Load stream. The video should play.
Test DASH-Encrypted playback:
1. Select Shaka player.
2. Stream URL: <MediaPackage DASH-Encrypted endpoint URL>.
3. Token: <Your license token>.
  
  note
  Make sure that the token specifies the Key ID(s) generated by AWS MediaPackage.
4. Set the license service:
  - For Widevine playback: "https://drm-widevine-licensing.axprod.net/AcquireLicense".
  - For PlayReady playback: "https://drm-playready-licensing.axprod.net/AcquireLicense".
5. Choose Load stream. Video should play.
Test the CMAF-Clear playback:
1. Select the FairPlay player (Safari only). Alternatively, clear CMAF also plays in Shaka.
2. Stream URL: <MediaPackage CMAF-Clear endpoint URL>.
3. Leave rest of the fields blank.
4. Choose Load stream. The video should play.
Test the CMAF-Encrypted playback:
1. Select the FairPlay player (Safari only).
2. Stream URL: <MediaPackage CMAF-Encrypted endpoint URL>.
3. Token: <Your license token>.
4. FPS Certificate URL: <the URL to your FairPlay application certificate>.
5. License service: "https://drm-fairplay-licensing.axprod.net/AcquireLicense".
6. Choose Load stream. The video should play.

Start​

API Gateway Setup​

IAM (Identity and Access Management) Setup​

MediaPackage Setup​

MediaLive Setup​

Playback Test​