Encryption Settings

This topic contains details for encoding settings related to encryption of videos.

Overview

Zencoder can perform AES encryption of video files. Our implementation is designed to be compatible with HTTP Live Streaming (HLS) outputs, but can be used to encrypt any video file similarly. When used for segmented outputs, only the segment files will be encrypted (leaving the manifest/playlist files readable, as expected). For HLS outputs, the necessary key/IV data will be added to the M3U8 manifest file, and encryption key files will be included with the other deliverable files if applicable.

Encryption is turned on when encryption_key, encryption_key_url, encryption_method, or encryption_key_rotation_period are specified.

Note that the way that you should specify encryption depends on how the player you are using expects to receive the key. For example, VideoJS expects raw bytes (not a hex string), and in this case you want to use encryption_key_url rather than encryption_key, which must be passed to Zencoder as a hex string.

encryption_method

encryption_method:String

API Versions: V2

Parent: outputs

Valid Values: "none", "aes-128-cbc", "aes-128-ctr", "aes-256-cbc", or "aes-256-ctr"

Compatible Job Types: vod

Example: aes-128-cbc

Description:

Set the encryption method to use for encrypting.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "type": "segmented",
      "encryption_method": "aes-128-cbc"
    }
  ]
}

encryption_key

encryption_key:String

API Versions: V2

Parent: outputs

Valid Values: A hexadecimal string of 16 octets (32 chars long, optional "0x" prefix)

Compatible Job Types: vod

Example: a5f6a7d6ef5d6a7a02a23dd35dd56a63

Description:

Set a single encryption key to use rather than having Zencoder generate one. Passing an encryption key is not compatible with key rotation. Zencoder will generate and return the encryption keys if using key rotation.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "type": "segmented",
      "encryption_key": "a5f6a7d6ef5d6a7a02a23dd35dd56a63"
    }
  ]
}

encryption_key_url

encryption_key_url:String

API Versions: V2

Parent: outputs

Valid Values: A URL to a file containing a 16-byte binary key

Compatible Job Types: vod

Example: http://example.com/encryption.key

Description:

Set a single encryption key to use rather than having Zencoder generate one. Specified as a URL to a file containing a 16-byte binary key.

This will be included as the URL to the key file in HLS manifests and no encryption key files will be included with the output. If the encryption_key is not also specified, Zencoder will attempt to download this file and use it to encrypt the output.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "type": "segmented",
      "encryption_key_url": "http://example.com/encryption.key"
    }
  ]
}

encryption_key_rotation_period

encryption_key_rotation_period:Number

API Versions: V2

Parent: outputs

Valid Values: A number greater than 0

Compatible Job Types: vod

Example: 10

Description:

When Zencoder is generating encryption keys, use a different key for each set of segments, rotating to a new key after this many segments.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "type": "segmented",
      "encryption_key_rotation_period": 10
    }
  ]
}

encryption_key_url_prefix

encryption_key_url_prefix:String

API Versions: V2

Parent: outputs

Valid Values: A URL or relative path

Compatible Job Types: vod

Example: keys/

Description:

When an encryption_key_url is not specified, prepend this to the encryption key filenames before including them in the manifest. Otherwise the keys are assumed to be accessible from the same path as the manifest file. If a question mark is used in the string the prefix it will be used as-is, otherwise a slash will be added to the end of the prefix (unless it already ends with a slash).

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "type": "segmented",
      "encryption_key_url_prefix": "keys/"
    }
  ]
}

encryption_iv

encryption_iv:String

API Versions: V2

Parent: outputs

Valid Values: A hexadecimal string of 16 octets (32 chars long, optional "0x" prefix)

Compatible Job Types: vod

Example: a5f6a7d6ef5d6a7a02a23dd35dd56a63

Description:

Set an initialization vector to use when encrypting, as a 16-octet hexadecimal string. On segmented outputs if this is not specified, the segments will be encrypted with incrementing IV values, starting at zero (consistent with HLS specifications).

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "type": "segmented",
      "encryption_iv": "a5f6a7d6ef5d6a7a02a23dd35dd56a63"
    }
  ]
}

encryption_password

encryption_password:String

API Versions: V2

Parent: outputs

Valid Values: A string

Compatible Job Types: vod

Example: super-secret-password

Description:

Sets a password to use for generating an initialization vector. Not supported for segmented outputs. Non-segmented outputs require either encryption_iv or encryption_password.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "type": "segmented",
      "encryption_password": "super-secret-password"
    }
  ]
}