HLS AES Encryption

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

When encrypted, your HLS playlist (m3u8 file) contains an EXT-X-KEY tag that provides the necessary information for players 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 before it can begin decoding the video segments.

Implementation Requirements

Before implementing HLS AES encryption, ensure:

• Your original videos are uploaded to your Object Storage bucket
• Your account has Media Processing functionality enabled
• You understand the Media Processing API request process

Step 1: Generate and Configure RSA Keys

To securely transmit the AES encryption key in API requests, you must encrypt it with RSA encryption. This involves generating a key pair and registering your private key with our system.

Generate RSA Key Pair

Run these commands to create RSA private and public keys:

# Generate private key (2048-bit)
openssl genrsa -out private.key 2048

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

Store both key files securely. The public key will encrypt your AES key, while the private key will be used by our backend to decrypt it.

Register Your RSA Private Key

1. Encode your private key file to Base64 format
2. Provide this encoded key to our customer service team for configuration in our backend
3. For detailed instructions on this process, see our RSA Private Key Example

Step 2: Prepare Encryption Parameters

When creating your encryption request, you’ll need to construct the fops (file operation parameters) that include special encryption settings:

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

Generating the hlsKey Parameter

The hlsKey is your AES encryption key that must be RSA-encrypted before inclusion in the API request:

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

Example with the AES key value 01234566543210abcdef888888abcdef:

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

# Encrypt your 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 your encrypted hlsKey parameter value.

Setting the hlsKeyUrl Parameter

The hlsKeyUrl specifies where players will retrieve the decryption key. You have two options:

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

To create a key file for option 2:

# Create a binary key file from your 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 parameter, for example:

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

Step 3: Execute the Encryption Process

With your parameters prepared, you can now make the API request to encrypt your video content.

Example API Request

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

curl -v -X POST \
  -d "bucket=Urlsafe_Base64_Encode(vod-wcs-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-wcs-test001:hls_aes_.m3u8))&force=1&separate=1" \
  -H "Authorization: AccessKey EncodeSign" \
  --url "http://mgrDomain/fops"

When transcoding completes successfully, your encrypted video will be available in the designated bucket. The resulting HLS manifest (m3u8 file) will include the EXT-X-KEY tag, indicating that the content is encrypted and providing the key location for players.

Security Considerations

• Keep your RSA private key secure at all times
• Consider implementing access controls on your key URL to prevent unauthorized access
• For high-security scenarios, implement a token-based authentication system for key delivery