# Content encryption and DRM in AWS Elemental MediaConvert
<a name="implementing-digital-rights-management-drm"></a>

Protect your content from unauthorized use through encryption. Digital rights management (DRM) systems provide keys to AWS Elemental MediaConvert for content encryption, and licenses to supported players and other consumers for decryption.

The following sections provide guidance on how to choose and implement content encryption using SPEKE for MediaConvert.

**Topics**
+ [Container and DRM system support with SPEKE](encryption-choosing-speke-version.md)
+ [Deploying SPEKE](encryption-deploying-speke.md)
+ [SPEKE encryption parameters](speke-encryption-parameters.md)
+ [SPEKE v2.0 presets](drm-content-speke-v2-presets.md)
+ [Using encrypted content keys with DRM](drm-content-key-encryption.md)
+ [Troubleshooting DRM encryption](troubleshooting-encryption.md)
+ [Requirements](encryption-requirements.md)

# Container and DRM system support with SPEKE
<a name="encryption-choosing-speke-version"></a>

MediaConvert supports both [SPEKE Version 1.0](https://docs.aws.amazon.com/speke/latest/documentation/the-speke-api.html) and [SPEKE Version 2.0](https://docs.aws.amazon.com/speke/latest/documentation/the-speke-api-v2.html). For more information, see the [SPEKE partner and customer guide](https://docs.aws.amazon.com/speke/latest/documentation/speke-api-specification.html).

**SPEKE v1.0 Supported containers and DRM systems**

The following table lists the different containers and digital rights management (DRM) systems that SPEKE Version 1.0 supports.


**SPEKE v1.0 DRM support**  

|  |  |  |  | 
| --- |--- |--- |--- |
| Output group type | Apple Fairplay | Google Widevine | Microsoft PlayReady | 
| DASH | Not supported | Supported | Supported | 
| Apple HLS | Supported | Not supported | Not supported | 
| Microsoft Smooth | Not supported | Not supported | Supported | 
| CMAF DASH and CMAF HLS | Supported | Supported | Supported | 

**SPEKE v2.0 Supported containers and DRM systems**

The following table lists the different containers and digital rights management (DRM) systems that SPEKE Version 2.0 supports.


**SPEKE v2.0 DRM support**  

|  |  |  |  | 
| --- |--- |--- |--- |
| Output group type | Apple Fairplay | Google Widevine | Microsoft PlayReady | 
| DASH | Not supported | Supported | Supported | 
| Apple HLS | Supported (Sample-AES) | Supported | Supported | 
| Microsoft Smooth | Not supported | Not supported | Not supported | 
| CMAF DASH and CMAF HLS | Supported (CBCS) | Supported (CBCS and CENC) | Supported (CBCS and CENC) | 

**Supported DRM system IDs**

The following table lists the different DRM [system IDs](https://dashif.org/identifiers/content_protection/) that MediaConvert supports.


|  |  |  |  | 
| --- |--- |--- |--- |
| System IDs – Support matrix for DRM system | Apple FairPlay | Google Widevine | Microsoft PlayReady | 
|  System ID | 94ce86fb-07ff-4f43-adb8-93d2fa968ca2 | edef8ba9-79d6-4ace-a3c8-27dcd51d21ed | 9a04f079-9840-4286-ab92-e65be0885f95 | 

# Deploying SPEKE
<a name="encryption-deploying-speke"></a>

Your digital rights management (DRM) system provider can help you get set up to use DRM encryption in MediaConvert. Generally, the provider gives you a SPEKE gateway to deploy in your AWS account in the same AWS Region where MediaConvert is running.

If you must build your own API Gateway to connect MediaConvert to your key service, you can use the [SPEKE Reference Server](https://github.com/awslabs/speke-reference-server) available on GitHub as a starting point.

# SPEKE encryption parameters
<a name="speke-encryption-parameters"></a>

When you request encryption, you provide input parameters that allow the service to locate your DRM solution provider's key server, to authenticate you as a user and to request the proper encoding keys. Some options are available only for particular output groups.

Enter the SPEKE encryption parameters as follows: 
+ For **Resource ID**, enter an identifier for the content. The service sends this to the key server to identify the current endpoint. How unique you make this depends on how fine-grained you want access controls to be. The service does not allow you to use the same ID for two simultaneous encryption processes. The resource ID is also known as the content ID. 

  The following example shows a resource ID.

  ```
  MovieNight20171126093045
  ```
+  For **System ID**, enter unique identifiers for your streaming protocol and DRM system. The number of system IDs that you can specify varies depending on the output group type:
  + CMAF – For **System IDs signaled in DASH**, specify at least one and up to three IDs. For **System ID signaled in HLS**, specify one ID.
  + DASH – For **System ID**, specify at least one and up to two IDs.
  + Apple HLS – For **System ID**, specify one ID.

  If you provide more than one system ID in a single field, enter them on separate lines, and don't separate them with commas or any other punctuation. 

  For a list of common system IDs, see [DASH-IF System IDs](https://dashif.org/identifiers/content_protection/). If you don't know your IDs, request them from your DRM solution provider.
+ For **URL**, enter the URL of the API Gateway proxy that you set up to talk to your key server. The API Gateway proxy must reside in the same AWS Region as MediaConvert.

  The following example shows a URL. 

  ```
  https://1wm2dx1f33.execute-api.us-west-2.amazonaws.com/SpekeSample/copyProtection
  ```
+ (Optional) For **Certificate ARN**, enter a 2048 RSA certificate ARN to use for content key encryption. Use this option only if your DRM key provider supports content key encryption. If you use this and your key provider doesn't support it, the request fails.

  To enter a certificate ARN here, you must have already imported the corresponding certificate into AWS Certificate Manager, entered the certificate ARN from ACM into the MediaConvert **Certificates** pane, and associated it with MediaConvert. For more information, see [Using encrypted content keys with DRM](drm-content-key-encryption.md). 

  The following example shows a certificate ARN.

  ```
  arn:aws:acm:region:123456789012:certificate/97b4deb6-8983-4e39-918e-ef1378924e1e
  ```

**To encrypt content using SPEKE v1.0 by using the MediaConvert console:**

  1. Set up your transcoding job as usual. For more information, see [Tutorial: Configuring job settings](setting-up-a-job.md).

  1. On the **Create job** page, in the **Job** pane on the left, under **Output groups**, choose an output group that you want to enable encryption for.

  1. Turn on **DRM encryption**.

  1. For **CMAF** and **Apple HLS** output groups, choose the encryption method. Make sure that you choose an encryption method that works with the DRM system that you use.

     For **DASH ISO** and **MS Smooth** output groups, you don't specify the encryption method. MediaConvert always uses AES-CTR (AES-128) encryption with these output groups.

  1. For **CMAF** and **Apple HLS** output groups, choose the source for the content encryption key. For **Key provider type**, choose **SPEKE** to encrypt using a key provided by your DRM solution provider, or choose **Static key** to enter your own key.

     For **DASH ISO** and **MS Smooth** output groups, you don't specify the source for the content encryption key. With these output groups, MediaConvert does DRM only with a SPEKE-compliant key provider.
     + For **SPEKE**, fill in the encryption parameter fields.
     + For **Static Key**, see [Static key encryption parameters](#static-key-encryption-parameters) below.

## Additional configuration options for Apple HLS and CMAF
<a name="additional-encryption-parameters"></a>
+ (Optional) For **Constant initialization vector** enter a 128-bit, 16-byte hex value represented by a 32-character string, to be used with the key for encrypting content.

## Static key encryption parameters
<a name="static-key-encryption-parameters"></a>

The following options are for static key encryption:
+ **Static key value** – A valid string for encrypting content.
+ **URL** – The URL to include in the manifest so that player devices can decrypt the content.

# SPEKE v2.0 presets
<a name="drm-content-speke-v2-presets"></a>

SPEKE Version 2.0 supports the use of multiple, distinct encryption keys for audio and video tracks. MediaConvert uses **presets** to configure the encryption. The MediaConvert API defines these presets. The presets map encryption keys to specific audio or video tracks, based on the number of channels for audio tracks, and based on the video resolution for video tracks. MediaConvert uses specific combinations of audio and video encryption presets to support three different encryption scenarios:
+ [Scenario 1: Unencrypted tracks and encrypted tracks](#drm-content-speke-v2-presets-unencrypted-and-encrypted-tracks)
+ [Scenario 2: Single encryption key for all audio and video tracks](#drm-content-speke-v2-presets-single-encryption-key-for-all-tracks)
+ [Scenario 3: Multiple encryption keys for audio and video tracks](#drm-content-speke-v2-presets-multiple-encryption-keys-for-audio-and-video-tracks)

## Scenario 1: Unencrypted tracks and encrypted tracks
<a name="drm-content-speke-v2-presets-unencrypted-and-encrypted-tracks"></a>

You can choose *not* to encrypt the audio or the video tracks by selecting the **UNENCRYPTED** preset in the **Video encryption preset** or the **Audio encryption preset** menus. You can’t select **UNENCRYPTED** for both audio and video presets, because doing so would mean that you don’t intend to encrypt any of the tracks at all. Also, you can’t combine **UNENCRYPTED** and **SHARED** presets for audio and video, because **SHARED** is a special preset. For more information, see [Scenario 2: Single encryption key for all audio and video tracks](#drm-content-speke-v2-presets-single-encryption-key-for-all-tracks). 

The following list describes valid combinations of **UNENCRYPTED** presets:
+ **UNENCRYPTED** for audio tracks, and any video preset with a name that starts with `PRESET_VIDEO_`
+ **UNENCRYPTED** for video tracks, and any audio preset with a name that starts with `PRESET_AUDIO_`

## Scenario 2: Single encryption key for all audio and video tracks
<a name="drm-content-speke-v2-presets-single-encryption-key-for-all-tracks"></a>

The SPEKE Version 2.0 **SHARED** preset uses a single encryption key for all audio and video tracks, as in SPEKE Version 1.0. When you select the **SHARED** preset, select it for both audio and video encryption.

## Scenario 3: Multiple encryption keys for audio and video tracks
<a name="drm-content-speke-v2-presets-multiple-encryption-keys-for-audio-and-video-tracks"></a>

When you use a preset with a name that starts with `PRESET_VIDEO_` or `PRESET_AUDIO_`, MediaConvert encrypts the audio tracks and video tracks with the number of encryption keys that the specific preset defines. The following tables show how many keys MediaConvert requests from the key server and how those keys map to tracks. If no track matches the criteria for a particular key, MediaConvert does not use that key to encrypt any track.

MediaConvert encrypts I-frame only trickplay tracks with the key corresponding to their resolution. 

In the following table, the **Key name** value is the value of the `ContentKeyUsageRule@IntendedTrackType` attribute that MediaConvert uses in the CPIX document. This is sent to the SPEKE server for a specific content key.


**Video encryption presets**  
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediaconvert/latest/ug/drm-content-speke-v2-presets.html)

In the following table, the **Key name** value is the value of the `ContentKeyUsageRule@IntendedTrackType` attribute that MediaConvert uses in the CPIX document. This is sent to the SPEKE server for a specific content key.


**Audio encryption presets**  
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediaconvert/latest/ug/drm-content-speke-v2-presets.html)

Now you know how MediaConvert supports SPEKE Version 2.0 presets for unencrypted tracks and encrypted tracks. With these presets, you can use a single encryption key for all audio and video tracks, and multiple encryption keys for audio and video tracks. 

# Using encrypted content keys with DRM
<a name="drm-content-key-encryption"></a>

For the most secure DRM encryption solution, use encrypted content keys in addition to encrypted content. To use encrypted content keys, you must import suitable certificates into AWS Certificate Manager (ACM), and then prepare them for use with AWS Elemental MediaConvert. For information about ACM, see the [AWS Certificate Manager User Guide](https://docs.aws.amazon.com/acm/latest/userguide/). 

Run AWS Certificate Manager in the same Region as you run AWS Elemental MediaConvert.

**To prepare a certificate for DRM content key encryption**

1. Obtain a 2048 RSA, SHA-512-signed certificate. 

1. Open the ACM console at [https://console.aws.amazon.com/acm/](https://console.aws.amazon.com/acm/).

1. Import the certificate into ACM according to the instructions at [Importing certificates into AWS Certificate Manager](https://docs.aws.amazon.com/acm/latest/userguide/import-certificate.html). Note the resulting certificate ARN because you will need it later.

   For use in DRM encryption, your certificate must have a status of **Issued** in ACM.

1. Open the MediaConvert console at [https://console.aws.amazon.com/mediaconvert/](https://console.aws.amazon.com/mediaconvert/).

1. In the navigation pane, under **Certificates**, enter your certificate ARN, and then choose **Associate certificate**. 

**To find certificates that are associated with AWS Elemental MediaConvert**

In the ACM console, list and display your certificates to find the ones that you have associated with MediaConvert. In the **Details** section of the certificate's description, you can see the MediaConvert association and retrieve the certificate ARN. For more information, see [List ACM–managed certificates](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-list.html) and [Describe ACM certificates](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-describe.html). 

**To use a certificate in AWS Elemental MediaConvert**

When you use DRM encryption, provide one of your associated certificate ARNs in the SPEKE encryption parameters. This enables content key encryption. You can use the same certificate ARN for multiple jobs. For information, see [Container and DRM system support with SPEKE](encryption-choosing-speke-version.md). 

**To renew a certificate**

To renew a certificate that you have associated with AWS Elemental MediaConvert, reimport it in AWS Certificate Manager. The certificate renews without any disruption of its use in MediaConvert. 

**To delete a certificate**

To delete a certificate from AWS Certificate Manager, you must first dissociate it from any other service. To dissociate a certificate from AWS Elemental MediaConvert, copy its certificate ARN from ACM, navigate to the MediaConvert **Certificates** pane, enter the certificate ARN, and then choose **Dissociate certificate**. 

# Troubleshooting DRM encryption
<a name="troubleshooting-encryption"></a>

If the DRM system key server is unavailable when AWS Elemental MediaConvert requests keys, the console displays the following message: Key Server Unavailable. 

Content key encryption adds another layer of complexity to your jobs. If you run into problems on a job that has content key encryption enabled, remove the certificate ARN from your job settings and troubleshoot the job using clear key delivery. When you have that working, reenter the certificate ARN, and then try the job again. 

If you contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/) for troubleshooting purposes, have the following information available:
+ Region that the job was run in
+ Job ID
+ Account ID
+ Name of your DRM solution provider
+ Any other details about the problem that you are having that might assist with troubleshooting

# Requirements
<a name="encryption-requirements"></a>

When implementing content encryption for MediaConvert, refer to the following limitations and requirements:
+ Use the AWS Secure Packager and Encoder Key Exchange (SPEKE) API to facilitate integration with a digital rights management (DRM) system provider. For information about SPEKE, see [What is Secure Packager and Encoder Key Exchange?](https://docs.aws.amazon.com/speke/latest/documentation/what-is-speke.html)
+ Your DRM system provider must support SPEKE. For a list of DRM providers that support SPEKE, see the [Get on board with a DRM platform provider](https://docs.aws.amazon.com/speke/latest/documentation/customer-onboarding.html#choose-drm-provider) topic in the *SPEKE partner and customer guide*. Your DRM provider can help you set up DRM encryption use in MediaConvert.