DocsICP FilingConsole
Documentation
Home Page CDN User Guide Domain name management Video-related settings Configure standard M3U8 encryption and rewrite

Configure standard M3U8 encryption and rewrite

Updated at:
Copy as MD
Product
My Favorites

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 server and prevents unauthorized video playback.

Use cases

In a standard HLS encryption workflow, the #EXT-X-KEY tag specifies the URI for retrieving the decryption key. If this URI is a fixed, unprotected public address, anyone who obtains the M3U8 file can download the key and decrypt the video content, which renders the encryption ineffective.

This feature solves the problem by attaching a dynamic, verifiable authentication token to each key request. It is ideal for scenarios that require access control over HLS encryption keys, such as:

  • Paid video and online education: To prevent users from sharing M3U8 URLs 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 stream copyright protection: For major sporting events or live broadcasts, you can combine dynamically generated authentication parameters with CDN URL authentication. This enables fine-grained access control over the live stream and effectively prevents hotlinking.

How it works

  1. 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.

  2. The client appends this authentication parameter to the end of the M3U8 file request URL and sends an M3U8 request to a CDN point of presence (PoP).

  3. 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.

  4. The client receives the rewritten M3U8 file from CDN and sends a request to the key server using the new key URI, which now includes the authentication parameter.

  5. 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.

  6. After obtaining the key, the client decrypts the TS video stream and starts playback.

Important

  • This feature does not encrypt video content. Before you use this feature, ensure that the video segments (TS files) on your origin server are encrypted based on an HLS standard, such as AES-128. The original M3U8 file must also contain the correct #EXT-X-KEY tag. For more information about video encryption, see How to generate and encrypt an M3U8 file.

  • The application server and key server are shown here to illustrate the overall flow. You must implement them yourself 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 What is in an HLS M3U8 file.

Procedure

  1. Log on to the CDN console.

  2. In the left navigation pane, click Domain Names.

  3. On the Domain Names page, find the target domain name and click Manage in the Actions column.

  4. In the domain's navigation pane, click Video.

  5. In the M3U8 Encryption and Rewrite section, turn on the M3U8 Encryption and Rewrite switch.

    Note

    After you enable M3U8 Encryption and Rewrite, the default parameter name is MtsHlsUriToken.

  6. Optional: To modify the parameter name to match your client, perform the following steps:

    1. Click Modify next to Custom Parameter Name.

    2. In the Custom Parameter Name dialog box, set Parameter Name.

      If you do not specify a value, the parameter name defaults to MtsHlsUriToken.

      Note

      Parameter names are case-sensitive. Make sure the parameter name you set exactly matches the parameter name in client requests. For example, if the client request includes the MtsHlsUriToken parameter and you set the custom parameter name in the CDN console to mtshlsuritoken, the configuration does not take effect.

    3. Click OK to complete the configuration.

Example

  1. Access the M3U8 file that is accelerated by CDN in your browser and append MtsHlsUriToken=tokenxxxxx to the end of the request. 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.

  2. In the CDN console, enable M3U8 Encryption and Rewrite. If needed, you can set a custom parameter name (this demonstration uses the default parameter MtsHlsUriToken). In the CDN console, enable the M3U8 encryption and rewrite feature, and set Custom Parameter Name to MtsHlsUriToken.

  3. Repeat Step 1. Access the CDN-accelerated M3U8 file in a browser and append MtsHlsUriToken=tokenxxxxx to the end of the request.

    In your browser's developer tools, on the Network panel, you can see that the request for the key address now includes the custom parameter.

    The request URL for the key file encryption_key.key includes the MtsHlsUriToken=tokenxxxxx parameter, and the response has a status code of 206 and a Content-Length of 16 bytes.

FAQ

What is the HLS protocol?

HTTP Live Streaming (HLS) is an HTTP-based streaming media protocol developed by Apple. It splits a video stream into small Transport Stream (TS) segments and uses a text file with an M3U8 extension as the playlist. To start playback, a client first downloads the M3U8 playlist, then downloads each media segment in sequence using the URLs it contains.

What is in an HLS M3U8 file?

Basic M3U8 tags:

  • #EXTM3U: The file header. Must be the first line of the playlist.

  • EXT-X-MEDIA-SEQUENCE : The sequence number of the first TS segment. Typically 0. In live streaming, it identifies the starting point. For example, #EXT-X-MEDIA-SEQUENCE:0.

  • #EXT-X-TARGETDURATION: The maximum duration of a media segment. For example, #EXT-X-TARGETDURATION:10 sets the maximum to 10 seconds.

  • #EXT-X-ALLOW-CACHE: Whether the client can cache media segments. Valid values: #EXT-X-ALLOW-CACHE:YES and #EXT-X-ALLOW-CACHE:NO. Default: YES.

  • #EXT-X-ENDLIST: Marks the end of the playlist.

  • #EXTINF: Extra information about a media segment, such as duration and bandwidth. Format: #EXTINF:<duration>,[<title>]. The value before the comma is the segment duration, which must not exceed the #EXT-X-TARGETDURATION value.

  • #EXT-X-VERSION: The M3U8 playlist version number.

  • #EXT-X-DISCONTINUITY: Signals a break between the preceding and following media segments.

  • #EXT-X-PLAYLIST-TYPE : Indicates the type of the stream.

  • #EXT-X-KEY: Specifies the decryption method for encrypted media segments. For example: #EXT-X-KEY:METHOD=AES-128,URI="https://example.com/video.key?token=xxx" uses AES-128 encryption. The key is retrieved from https://example.com/video.key?token=xxx, stored locally, and used to decrypt subsequent TS files.

How to generate and encrypt an M3U8 file?

  1. Generate an encryption key.

    This key is typically a 16-byte random string for AES-128 encryption. Generate a key file with OpenSSL:

    openssl rand 16 > encryption_key.key

  2. Prepare the key_info.txt file. The encryption tool uses this file to encrypt 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 generated in Step 1. We recommend hosting the file on a CDN-accelerated OSS origin server.

    • The second line is the absolute path of the local key file.

  3. Use FFmpeg to generate and encrypt 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 convert, such as a video in MP4 format.

    • -c:v copy: Copies the video stream directly without re-encoding.

    • -c:a copy: Copies the audio stream directly without re-encoding.

    • -hls_time 10: Sets the duration of each TS file to 10 seconds. You can modify this setting based on the duration of the original video.

    • -hls_key_info_file key_info.txt: Specifies the file that contains the encryption key information.

    • -hls_list_size 0: Sets the number of TS file indexes to retain in the M3U8 file. A value of 0 indicates that all .ts file indexes are retained.

    • output_playlist.m3u8: The output HLS playlist file name (that is, the M3U8 file name).

  4. Save the encrypted TS files and M3U8 files to a server, such as a CDN-accelerated OSS origin server. Then, use a CDN-accelerated domain name in a browser to access the M3U8 file to enable encrypted playback of videos that use the HLS protocol.

Previous：Configure audio and video previewNext：Traffic throttling