HLS AES encryption secures your video content during streaming by encrypting video segments using the Advanced Encryption Standard (AES-128) algorithm. This symmetric encryption method uses the same key for both encryption (performed by the server) and decryption (performed by the viewer’s player).

When encryption is enabled, the HLS playlist (m3u8 file) contains an EXT-X-KEY tag that provides the information required for the player to decrypt the content:

#EXT-X-KEY:METHOD=AES-128,URI="https://keypathURI/hls_aes.key",IV=0x00000000000000000000000000000000

During playback, the player first retrieves the decryption key from the URI specified in the playlist and then uses it to decode the video segments.

Implementation Requirements

Before implementing HLS AES encryption, make sure that:

• Your original videos have been uploaded to your Object Storage bucket
• Media Processing is enabled for your account
• You understand the Media Processing API request workflow

Step 1: Generate and Configure RSA Keys

To securely transmit the AES encryption key in API requests, you must encrypt it with RSA. This requires generating an RSA key pair and registering your private key with Atomile.

Generate an RSA Key Pair

Run the following commands to generate RSA private and public keys:

# Generate a 2048-bit private key
openssl genrsa -out private.key 2048

# Extract the public key from the private key
openssl rsa -in private.key -pubout -out pub.key

Store both key files securely. The public key is used to encrypt your AES key, and the private key is used by the Atomile backend to decrypt it.

Register Your RSA Private Key

1. Encode your private key file in Base64 format.
2. Provide the encoded key to the Atomile support team for backend configuration.
3. For detailed instructions, refer to the relevant private key registration guide provided by Atomile.

Step 2: Prepare Encryption Parameters

When creating the encryption request, construct the fops parameter as follows:

<op>/<Format>
  /hlsKey/<hlsKey>
  /hlsKeyUrl/<hlsKeyUrl>
|saveas/<Urlsafe_Base64_Encode(bucket:filekey)>

Generate the hlsKey Parameter

The hlsKey is your AES encryption key. It must be RSA-encrypted before being included in the API request.

1. Generate a 16-byte (128-bit) random value to use as the AES key.
2. Encrypt the value using your RSA public key with OAEP padding.
3. Base64-encode the result using URL-safe characters.

Example using the AES key value 01234566543210abcdef888888abcdef:

# Generate a random 16-byte hex key if needed
openssl rand -hex 16

# Encrypt the key with RSA-OAEP and encode it for API transmission
echo -n "01234566543210abcdef888888abcdef" | openssl rsautl -encrypt -pubin -inkey pub.key -oaep | openssl base64 -A | tr "+/" "-_"

The output string is the encrypted value of the hlsKey parameter.

Set the hlsKeyUrl Parameter

The hlsKeyUrl parameter specifies where the player retrieves the decryption key. You can use one of the following methods:

1. Your own key server: Provide the URL of your key management system
2. Object Storage: Upload the key file to your bucket and use its accessible URL

To create a key file for the second option:

# Create a binary key file from the hex key
echo -ne "\x01\x23\x45\x66\x54\x32\x10\xab\xcd\xef\x88\x88\x88\xab\xcd\xef" > key.hex

After uploading this file to your bucket, use its accessible URL as the hlsKeyUrl value. For example:

https://bucketname.s3-cn-north-1.wcsapi.com/key.hex

Step 3: Run the Encryption Process

After preparing the parameters, send the API request to encrypt your video content.

Example API Request

This example encrypts a file named test_hls.m3u8 stored in the vod-test001 bucket:

curl -v -X POST \
  -d "bucket=Urlsafe_Base64_Encode(vod-test001)&key=Urlsafe_Base64_Encode(test_hls.m3u8)&fops=Urlsafe_Base64_Encode(avthumb/m3u8/hlsKey/encrypted_hlsKey/hlsKeyUrl/https://bucketname.s3-cn-north-1.wcsapi.com/key.hex|saveas/Urlsafe_Base64_Encode(vod-test001:hls_aes_.m3u8))&force=1&separate=1" \
  -H "Authorization: AccessKey:EncodeSign" \
  --url "http://mgrDomain/fops"

After transcoding completes successfully, the encrypted video is stored in the specified bucket. The resulting HLS manifest (m3u8 file) contains the EXT-X-KEY tag, indicating that the content is encrypted and specifying where the player can retrieve the key.

Security Considerations

• Keep your RSA private key secure at all times.
• Consider applying access controls to the key URL to prevent unauthorized access.
• For high-security use cases, implement token-based authentication for key delivery.