Http-Live-Streaming (HLS) Encryption must be used with Key Management Service (KMS) and token service. This topic describes the concepts, preparations, procedures, and FAQ of HLS Encryption.

Architecture

HLS architecture

Terms

  • KMS

    KMS is a security management service that is used to generate, encrypt, and decrypt data keys.

  • Resource Access Management (RAM)

    RAM allows you to manage user identities and control access to resources.

  • Data key (DK)

    DK is also called the plaintext key. DK is the plaintext key used to encrypt data.

  • Envelope data key (EDK)

    EDK is also called the ciphertext key. EDK is the ciphertext key generated by using envelope encryption.

Preparations

  1. Activate KMS.
  2. Submit a ticket to create a service key. A service key must be created in the same region as the origin that stores videos. For example, if videos are stored in the China (Shanghai) region, the service key must be created in the China (Shanghai) region.
    Note A service key is a primary encryption key used in KMS. You must use the service key to generate keys for HLS Encryption. You cannot create service keys in the ApsaraVideo VOD console.
  3. Build KMS to encapsulate Alibaba Cloud KMS. Call the GenerateDataKey operation to generate an AES-128 key.
    Note When you call the GenerateDataKey operation, you need to pass only the KeyId and KeySpec parameters. The KeyId is the service key and the value of KeySpec is AES_128. Do not pass other parameters. Otherwise, encryption may fail.
  4. Construct a token issuance service to generate MtsHlsUriToken.
  5. Call the Decrypt operation of KMS to decrypt EDKs and obtain DKs. If you want to authenticate the player that requests decryption, construct a token issuance service and make sure that the issued token can be parsed and verified by the decryption service.
    Note The GenerateDataKey operation generates a ciphertext key and a plaintext key. The plaintext key is encoded in Base64. The decryption operation returns the key after the operation decodes the key by using Base64.

Procedure

Use HLS Encryption based on the following procedure:

  1. Configure transcoding templates

    HLS Encryption requires that you perform the following operations to create two transcoding templates:

    • Transcoding template that has encryption enabled: Log on to the ApsaraVideo VOD console and click Add Template in the Normal Transcoding Template section on the Added Transcoding Template Group page. Select hls from the Encapsulation Format drop-down list to create an HLS transcoding template. Enable Video Encryption and select Alibaba Cloud Proprietary Cryptography in the Advanced Parameters section. You must turn on the Video Encryption switch. Otherwise, videos are unencrypted. For more information, see Manage transcoding settings.
      Note When you call the SubmitTranscodeJobs operation, you can use the TemplateGroupId parameter to encrypt and transcode videos based on the specified template and key.
    • No transcoding template

      You can click Set as Default in the Actions column to activate the no transcoding template on the Transcode page in the console. If the no transcoding template already exists, you do not need to activate it again.

      Note By default, ApsaraVideo VOD automatically transcodes uploaded videos. However, automatic transcoding does not support HLS Encryption. To prevent automatic transcoding when you use HLS Encryption, you must use the no transcoding template to upload videos. Then, you can call the SubmitTranscodeJobs operation to start HLS Encryption and transcoding.
  2. Use RAM to authorize ApsaraVideo VOD

    Use RAM to authorize ApsaraVideo VOD to access your KMS. For more information, see Cloud Resource Access Authorization.

  3. Upload a video

    Use the no transcoding template activated in Step 1 to obtain the upload URL and credential. For more information about how to upload a video in the ApsaraVideo VOD console, see Upload media assets. For more information about how to upload a video by calling a server operation, see CreateUploadVideo.

  4. Receive the upload callback message

    The FileUploadComplete message indicates that the video file has been uploaded to ApsaraVideo VOD.

  5. Start HLS Encryption and transcoding

    Call the SubmitTranscodeJobs operation by passing the ID of the template created in Step 1 and HLS Encryption parameters to start HLS Encryption and transcoding.

  6. Verify whether HLS Encryption and transcoding are successful

    You can use one of the following methods to verify whether HLS Encryption and transcoding are successful:

    • You can check whether only the M3U8 video is generated and whether the video status is in the Transcoding Failed state. If only the M3U8 video is generated and the video status is in the Transcoding Failed state, HLS Encryption and transcoding failed.
    • If videos in other formats are generated in addition to the M3U8 video, go to the video details page in the ApsaraVideo VOD console and check whether an M3U8 file marked as Encrypted is generated. If the file is generated, HLS Encryption and transcoding may be successful.
    • If you are unsure after you check the result by using the preceding methods, copy the URL of the M3U8 file that is marked as Encrypted and run the curl -v "URL of the M3U8 file" command. Check whether the displayed M3U8 information contains the following information: URI="<The decryption URL that you pass when you start HLS Encryption, which is the value of DecryptKeyUri in EncryptConfig>". If the preceding information exists, the file is encrypted in HLS Encryption mode and that the encryption is successful.
  7. Obtain the playback URL and credential of a video

    Call the GetPlayInfo and GetVideoPlayAuth operations to obtain the playback URL and credential of a video.

  8. Pass the authentication information

    After the player obtains the URL of the M3U8 file, the player parses and accesses the URI in the EXT-X-KEY tag of the M3U8 file. This way, the player obtains the decryption operation URI that has the ciphertext key. This decryption operation URI is the value of DecryptKeyUri in EncryptConfig that you pass when you start HLS Encryption.

    If you allow only authorized users to access the video, the player must provide the authentication information that you acknowledge when the player obtains the decryption key. The authentication information can be passed by using the MtsHlsUriToken parameter.

    Example:

    • The video playback URL is https://vod.demo.com/encrypt-stream-hd.m3u8. The request must contain the MtsHlsUriToken parameter.
    • The final request URL is https://vod.demo.com/encrypt-stream-hd.m3u8?MtsHlsUriToken=<token>.
    • The decrypted URL is https://vod.decrypt.com?Ciphertext=ZjJmZGViNzUtZWY1Mi00Y2RlLTk3MTMtOTYyOT.
    • The final decrypted request URL is https://vod.decrypt.com?Ciphertext=ZjJmZGViNzUtZWY1Mi00Y2RlLTk3MTMtOTYyOT&MtsHlsUriToken=<The issued token>.
  9. After the player obtains the URI of the decryption operation, the player automatically requests the decryption operation to obtain the decryption key. After the player obtains the decryption key, the player decrypts the encrypted TS file for playback.

Best practices of decryption and playback

For more information about the best practices of video decryption and playback, see Secure playback based on HLS encryption.

FAQ

  • How do I view a service key?

    You can view a service key in your KMS console. The primary encryption key described as vod is the service key.

  • How do I use a service key to generate keys?

    Call the GenerateDataKey operation of KMS to generate the AES_128 keys by using the service key.

    Note When you call the GenerateDataKey operation, you need to pass only the KeyId and KeySpec parameters. The KeyId is the service key and the value of KeySpec is AES_128. Do not pass other parameters. Otherwise, encryption may fail.
  • How do I use the generated keys?

    The GenerateDataKey operation returns a ciphertext key and a plaintext key. You need to pass only the ciphertext key to ApsaraVideo VOD. For more information about the parameters to be passed, see "the EncryptConfig parameters" section of the SubmitTranscodeJobs topic.

    Note
    • We recommend that you cache the generated ciphertext key and plaintext key.
    • After the service key is created, the service key cannot be deleted or updated. The service key is used to generate encryption keys.
    • For more information about key-related fees, see the "Key hosting fees-API operation call fees" section of the Billing topic.
  • How do I pass the generated token to the decryption operation?

    To rewrite a decryption request by adding the token, you need to use an Alibaba Cloud CDN domain name. When you request an M3U8 file URL, you must pass the generated token in the MtsHlsUriToken parameter. Then, CDN automatically rewrites the decryption request by adding this parameter and sends the request.

  • How do I enable the feature that allows me to rewrite a request by adding the MtsHlsUriToken parameter?

    You can log on to the ApsaraVideo VOD console and choose Configuration Management > CDN Configuration > Domain Names > Video Related > Encrypted Playback to enable the feature that allows you to rewrite a request by adding the MtsHlsUriToken parameter.

  • How does a player decrypt and play the video?

    All players that support HLS can decrypt and play a video encrypted in HLS Encryption mode. Procedure:

    1. Call the GetPlayInfo and GetVideoPlayAuth operations to obtain the playback URL and credential of a video. For more information, see GetPlayInfo and GetVideoPlayAuth.
    2. After the player obtains the URL of the M3U8 file, the player parses and accesses the URI in the EXT-X-KEY tag of the M3U8 file. This way, the player obtains the decryption operation URI that has the ciphertext key. This decryption operation URI is the value of DecryptKeyUri in Request parameters that you pass when you start HLS Encryption. For more information, see EncryptConfig. If you allow only authorized users to access the video, the player must provide the authentication information you acknowledge when the player obtains the decryption key. The authentication information can be passed by using the MtsHlsUriToken parameter.

      Example:

      • The video playback URL is https://vod.demo.com/encrypt-stream-hd.m3u8. The request must contain the MtsHlsUriToken parameter.
      • The final request URL is https://vod.demo.com/encrypt-stream-hd.m3u8?MtsHlsUriToken=token. During playback, the player sends the final requested URL to Alibaba Cloud CDN. After Alibaba Cloud CDN parses the decryption operation URI from the M3U8 file, Alibaba Cloud CDN automatically concatenates the decryption operation URI that has the MtsHlsUriToken parameter.
      • The final requested decryption URL is https://vod.decrypt.com?Ciphertext=ZjJmZGViNzUtZWY1Mi00Y2RlLTk3MTMtOTYyOT.
      • The final decrypted request URL is https://vod.decrypt.com?Ciphertext=ZjJmZGViNzUtZWY1Mi00Y2RlLTk3MTMtOTYyOT&MtsHlsUriToken=The issued token.
    3. After the player obtains the decryption operation URI, the player automatically requests the decryption operation to obtain the decryption key.
    4. After the player obtains the URI of the decryption operation, the player decrypts the encrypted TS file for playback.
  • How do I quickly check whether the encrypted video can be played?

    You can use Alibaba Cloud Player Diagnostic Platform to quickly check whether an M3U8 file encrypted in HLS Encryption mode can be played. Copy the URL of the M3U8 file (with the value of MtsHlsUriToken if any) to Alibaba Cloud Player Diagnostic Platform to check whether the file can be played.

    Note The playback must request the decryption operation. Therefore, ensure that the decryption service is normal.
  • Other FAQ
    • Interface notes:

      KeyNotFound is returned when the SubmitTranscodeJobs operation is called. In this case, contact ApsaraVideo VOD technical support to create a service key in the required region such as China (Beijing) or China (Shanghai). The service key is used to generate encryption keys.

    • Unencrypted file:

      The generated file is unencrypted. In this case, verify whether Video Encryption is enabled and Alibaba Cloud Proprietary Cryptography is selected.

    • Custom key:

      Encryption and transcoding fail because a custom string is used to generate the encryption key. The plaintext key for encryption must be generated by GenerateDataKey. You cannot use a custom string to generate an encryption key.

    • Encryption failure:

      HLS Encryption and transcoding fail, and no encrypted file is generated. In this case, verify whether the key type is set to AES_128 for the GenerateDataKey operation. If another key type is set, HLS Encryption and transcoding fail, and no encrypted file is generated.

    • Decryption failure:

      A video encrypted in HLS Encryption mode fails to be decrypted for playback. In this case, verify whether the decryption operation uses Base64 to decode the plaintext key generated by KMS before the decryption operation sends the key to the player. If the plaintext key is not decoded, the decryption fails.

    • Duplicate encrypted files:

      Duplicate encrypted files are generated. In this case, check whether the SubmitTranscodeJobs operation is called repeatedly. If this operation is called repeatedly, duplicate encrypted files are generated. HLS Encryption and transcoding can be only manually started.