Configure M3U8 encryption and rewrite - CDN - Alibaba Cloud Documentation Center

When a client requests an M3U8 file, this feature automatically appends the authentication parameters from the request to the key URI within the #EXT-X-KEY tag. This secures access to your encryption keys without modifying your origin and prevents unauthorized video playback.

Use cases

In a standard HTTP Live Streaming (HLS) encryption workflow, the #EXT-X-KEY tag specifies the URI for retrieving the decryption key. If this URI is a fixed, public address, anyone who obtains the M3U8 file can download the key and decrypt the video content, rendering the encryption useless.

To solve this problem, this feature attaches a dynamic, verifiable authentication token to each key request. It is ideal for scenarios that require access control for HLS encryption keys, such as:

Paid video and online education: To prevent subsribers from sharing M3U8 addresses with non-paying users, you can generate a unique authentication parameter for each logged-in user. This ensures that only authorized users can retrieve the decryption key within its validity period.
Live streaming copyright protection: For major sporting events or live broadcasts, you can combine dynamically generated authentication parameters with the CDN's URL authentication feature. This enables fine-grained access control over the live stream and effectively prevents hotlinking.

How it works

A client sends a request to your Application Server. Based on your business logic (such as user login), the Application Server generates an authentication parameter with a validity period and signature (for example, token=xxxx) and returns it to the client.
The client appends this authentication parameter to the end of the M3U8 file's request URL and sends the request to a CDN point of presence (POP).
Before returning the M3U8 file, the CDN POP parses its content, finds the #EXT-X-KEY tag, and appends the authentication parameter from the client's request URL to the end of the tag's URI attribute.
The client receives the modified M3U8 file from the CDN and sends a request to the Key Server using the new key URI, which now includes the authentication parameter.
The Key Server receives the key request, extracts the authentication parameter from the URL, and validates it. If validation succeeds, it returns the decryption Key; otherwise, it denies the request.
After obtaining the Key, the client decrypts the TS video segments and begins playback.

Important

This feature does not encrypt video content. Before using this feature, you must encrypt the video segments (TS files) on the origin server using HLS encryption, such as AES-128. The original m3u8 file must also contain the correct #EXT-X-KEY tag. For more information about encrytion, see How do I generate an AES-128 encrypted HLS playlist (M3U8) with FFmpeg?
The terms business server and key server are mentioned to explain the role of M3U8 encryption and rewrite. This feature does not implement the business server or the key server. You must implement the functionality of the business and key servers to complete the HLS key authentication process.
The #EXT-X-KEY tag specifies whether the content is encrypted. For more information about M3U8 file tags, see Introduction to M3U8 Tags.

Procedure

Log on to the CDN console.
In the left navigation pane, click Domain Names.
On the Domain Names page, find the target domain name and click Manage in the Actions column.
In the domain's navigation pane, click Video.
In the M3U8 Encryption and Rewrite section, turn on M3U8 Encryption and Rewrite.
Note
After you turn on M3U8 Encryption and Rewrite, the default parameter name is MtsHlsUriToken.
Optional: To change the parameter name to match your client, follow these steps:
1. Click Modify next to Custom Parameter Name.
2. In the Custom Parameter Name dialog box, set Parameter Name.
  Note
  Parameter names are case-sensitive. Make sure that the parameter name you set is identical to the one included in client requests. For example, if client requests include the MtsHlsUriToken parameter, the custom parameter name mtshlsuritoken will not take effect.
3. Click OK.

Example

Access the M3U8 file accelerated by CDN in your browser and append MtsHlsUriToken=tokenxxxxx to the end of the request URL. For example: http://<CDN Accelerated Domain Name>/video.m3u8?MtsHlsUriToken=tokenxxxxx
In your browser's developer tools, the Network panel shows that the request for the M3U8 file includes the custom parameter, but the subsequent key request does not.
In the CDN console, enable M3U8 Encryption and Rewrite. Set a custom parameter name as needed. This example uses the default parameter MtsHlsUriToken, as shown in the following figure.
Repeat step 1. Access the CDN-accelerated M3U8 file in a browser and append MtsHlsUriToken=tokenxxxxx to the end of the request.
In the browser's developer tools, go to the Network tab. The request for the key address now includes the custom parameter.

FAQ

What is the HLS protocol?

HLS (HTTP Live Streaming) is an HTTP-based adaptive streaming protocol developed by Apple. It enables video playback by having the client download a series of short video segments over standard HTTP.

The protocol works using two main components:

Media Segments (.ts files): The video stream is broken into small chunks, typically in the Transport Stream (TS) format.
Playlist File (.m3u8 file): A plain-text file that serves as a playlist. It lists the available media segments and associated metadata. When playback starts, the client first downloads the M3U8 file to know which segments to fetch and in what order.

What are the key tags in an HLS M3U8 playlist and what do they do?

An M3U8 file is a text-based playlist that uses tags to structure the stream and provide metadata to the player. Here are the most common tags and their functions:

#EXTM3U: The M3U8 file header. It must be the first line of the file.
#EXT-X-MEDIA-SEQUENCE: The serial number of the first TS segment. The value is usually 0. In live streaming scenarios, this serial number identifies the starting position of the live segment. For example: #EXT-X-MEDIA-SEQUENCE:0.
#EXT-X-TARGETDURATION: The maximum duration of each TS segment. For example, #EXT-X-TARGETDURATION:10 indicates that the maximum duration of each segment is 10 seconds.
#EXT-X-ALLOW-CACHE: Indicates whether the client can cache the segments. The value can be #EXT-X-ALLOW-CACHE:YES or #EXT-X-ALLOW-CACHE:NO. The default value is YES.
#EXT-X-ENDLIST: The end tag for the M3U8 file.
#EXTINF: Extra information (extra info) about a TS segment, such as its duration and bandwidth. The format is typically #EXTINF:<duration>,[<title>]. The value before the comma is the duration of the current TS segment. The segment duration must be less than or equal to the value of the #EXT-X-TARGETDURATION tag.
#EXT-X-VERSION: The M3U8 version number.
#EXT-X-DISCONTINUITY: This tag indicates a break between the previous segment and the next one.
#EXT-X-PLAYLIST-TYPE: Indicates the type of streaming media.
#EXT-X-KEY: Indicates whether decryption is required. For example: #EXT-X-KEY:METHOD=AES-128,URI="https://example.com/video.key?token=xxx". This example shows that the encryption algorithm is AES-128. The key is obtained by sending a request to https://example.com/video.key?token=xxx. After the key is retrieved, it is stored locally and used to decrypt subsequent TS video files.

How do I generate an AES-128 encrypted HLS playlist (M3U8) with FFmpeg?

You can generate an encrypted HLS stream using OpenSSL to create the key and FFmpeg to segment and encrypt the video. Follow these steps:

Generate an encryption key.
For AES-128 encryption, the key is typically a 16-byte random string. Use the following OpenSSL command to generate a random key file:
```
openssl rand 16 > encryption_key.key
```
Prepare the key_info.txt file for encryption. The encryption tool uses this file to encrypt the HLS video files.
```
https://example.com/encryption_key.key
/path/to/local/encryption_key.key
```
- The first line is the URL of the encryption key that you generated in Step 1. Place the key file in an OSS bucket that is accelerated by CDN. Then, use a CDN-accelerated domain name to access the file.
- The second line is the absolute path of the local key file.
Use the FFmpeg tool to generate and encrypt the HLS video files.
```
ffmpeg -i input_video.mp4 -c:v copy -c:a copy -hls_time 10 -hls_key_info_file key_info.txt -hls_list_size 0 output_playlist.m3u8
```
- -i input_video.mp4: Specifies the video file to transform, such as an MP4 video.
- -c:v copy: Copies the video stream without re-encoding.
- -c:a copy: Copies the audio stream without re-encoding.
- -hls_time 10: Sets the duration of each TS file to 10 seconds. You can change this setting based on the duration of the source video.
- -hls_key_info_file key_info.txt: Specifies the file that contains the encryption key information.
- -hls_list_size 0: Specifies the number of TS file entries to keep in the M3U8 playlist. A value of 0 keeps all .ts file entries.
- output_playlist.m3u8: The name of the output HLS playlist file (the M3U8 file).
Upload the generated output_playlist.m3u8, all .ts segments, and the encryption_key.key to your web server or an OSS Origin. Players can then access the encrypted stream using the M3U8's URL.