How AES-128 Encryption Works in HLS and How to Decrypt It

When delivering media segments across untrusted networks, basic HTTPS secures the transport layer, but the segments themselves remain readable if intercepted or downloaded directly. AES-128 encryption solves this by ensuring that only clients possessing the correct symmetric key can decode the video or audio payload.

Understanding AES-128 in HLS

Advanced Encryption Standard (AES) with a 128-bit key length is a symmetric encryption algorithm, meaning the same 16-byte key is used to both encrypt and decrypt the payload. In the context of HLS, when AES-128 is employed, every media segment is entirely encrypted using Cipher Block Chaining (CBC) mode with PKCS7 padding.

To tell the player that segments are encrypted, the media playlist (the M3U8 file listing the individual .ts or .m4s files) includes a specific tag: #EXT-X-KEY.

The #EXT-X-KEY Tag

This tag precedes the segments it applies to. A typical implementation looks like this:

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:10
#EXT-X-MEDIA-SEQUENCE:0
#EXT-X-KEY:METHOD=AES-128,URI="https://api.example.com/keys/key1.key",IV=0x00000000000000000000000000000005
#EXTINF:10.0,
segment_0.ts
#EXTINF:10.0,
segment_1.ts

Let’s break down the attributes of the #EXT-X-KEY tag:

• METHOD=AES-128: Specifies the encryption algorithm. Other valid methods include SAMPLE-AES (which encrypts only specific parts of the media) and NONE (which turns off encryption for subsequent segments).
• URI: A quoted string containing the URL where the 16-byte symmetric key can be fetched. The player will make an HTTP GET request to this URI before it attempts to play the segments.
• IV (Initialization Vector): An optional 128-bit hexadecimal integer. In CBC mode, an IV ensures that identical plaintexts encrypt to different ciphertexts. If the IV is omitted, the HLS specification dictates that the sequence number of the media segment must be used as the IV (padded with leading zeros to reach 16 bytes).

How Players Decrypt the Stream

When a browser or media player encounters an encrypted segment, it follows a strict sequence of operations:

1. Fetch the Key: The player reads the URI attribute and makes a network request. This request is often protected. It might require an authentication cookie, a bearer token in the headers, or session parameters in the query string. If the request is blocked by CORS (Cross-Origin Resource Sharing) or returns a 401 Unauthorized error, playback halts immediately.
2. Determine the IV: The player looks for an explicit IV attribute. If not found, it takes the current segment's #EXT-X-MEDIA-SEQUENCE number, converts it to a 16-byte big-endian integer, and uses that as the IV.
3. Download the Segment: The encrypted .ts file is downloaded via a standard GET request.
4. Decrypt the Block: The player applies the AES-128 CBC decryption routine to the segment buffer using the fetched key and the determined IV. Once decrypted, the raw transport stream data is fed into the demuxer and decoder for rendering.

Manual Decryption Using OpenSSL

For debugging purposes, engineers often need to verify that segments are encrypted properly and that the key/IV combination is valid. You can manually decrypt an AES-128 encrypted HLS segment using the standard openssl command-line utility.

Assuming you have downloaded the encrypted segment (segment.ts.enc) and the 16-byte key file (decryption.key), you can inspect the key in hex format using hexdump:

hexdump -e '16/1 "%02x"' decryption.key

This will output a 32-character hexadecimal string, for instance: a1b2c3d4e5f60718293a4b5c6d7e8f90.

If the playlist specifies an IV (e.g., IV=0x0123456789abcdef0123456789abcdef), you can run the decryption command:

openssl aes-128-cbc -d -in segment.ts.enc -out decrypted_segment.ts -K a1b2c3d4e5f60718293a4b5c6d7e8f90 -iv 0123456789abcdef0123456789abcdef

If the IV is not specified in the manifest, use the sequence number. For segment #EXT-X-MEDIA-SEQUENCE: 5, the IV is 00000000000000000000000000000005.

Tip: If OpenSSL reports a "bad decrypt" error, verify that the key hex string matches exactly 32 characters, the IV matches exactly 32 characters, and that you are not accidentally including newlines in your key file.

Decrypting and Downloading with FFmpeg

While OpenSSL is great for single segments, FFmpeg is the preferred tool for downloading and decrypting an entire M3U8 stream simultaneously. FFmpeg natively parses the #EXT-X-KEY tag, fetches the key using the specified URI, determines the IV, and decrypts the stream on the fly.

To download a stream to a single MP4 file without re-encoding, use the following command:

ffmpeg -i "https://example.com/playlist.m3u8" -c copy output.mp4

Handling Authentication Headers

If the key URI requires authentication headers (such as a Bearer token or a specific User-Agent), FFmpeg might fail with an HTTP 403 Forbidden error when trying to fetch the key. You can pass custom headers to FFmpeg using the -headers argument:

ffmpeg -headers "Authorization: Bearer YOUR_TOKEN_HERE" -i "https://example.com/playlist.m3u8" -c copy output.mp4

If the key requires a session cookie, you can provide it like this:

ffmpeg -cookies "session_id=12345abcde;" -i "https://example.com/playlist.m3u8" -c copy output.mp4

Common Troubleshooting Scenarios

When working with AES-128 in HLS, things don't always go smoothly. Here are the most frequent issues engineers encounter:

• 403 Forbidden on Key URI: The most common issue. The client lacks the proper cookies or tokens to access the key. Verify authentication mechanisms and ensure tokens haven't expired.
• CORS Missing on Key Server: In web browsers, if the server hosting the key does not return Access-Control-Allow-Origin: * (or a specific domain), the browser blocks the key request. The network tab will show the request failing due to CORS policies.
• Incorrect IV: If segments decrypt into digital garbage (heavy macroblocking and audio static), the IV is likely wrong. Ensure the encoder and the player agree on whether to use the explicit IV or the sequence number fallback.
• Mixed Content Warnings: If your webpage is loaded over HTTPS, but the key URI is served over HTTP, the browser will block the key fetch due to Mixed Content policies. Always use HTTPS for key delivery.
• Bad Padding Errors: This usually indicates that the segment was not encrypted properly (perhaps truncated during encoding) or the key used is completely wrong. AES CBC mode requires precise PKCS7 padding.

Security Best Practices

While AES-128 provides strong payload encryption, the overall security of the stream depends entirely on how securely the key is delivered. If anyone can hit the key URI and download the 16 bytes, the encryption is functionally useless.

To harden your AES-128 implementation:

• Always serve keys over TLS (HTTPS) to prevent man-in-the-middle sniffing.
• Implement strict authorization logic on the key endpoint. Check user sessions, geographic IP blocks, and concurrency limits before serving the key.
• Use short-lived, signed URLs for both the M3U8 playlist and the key URI to prevent link sharing.
• Rotate keys frequently. For high-value live events, rotate the AES key every 10-15 minutes by injecting a new #EXT-X-KEY tag into the manifest.

By understanding the mechanics of AES-128 encryption, from the initial manifest parsing to the byte-level decryption, you can confidently build, debug, and secure robust HLS delivery pipelines.