DoveRunner DRM Multi-key Implementation Guide

Overview

This guide document aims to help DoveRunner customers implement multi-key scenarios and better utilize hardware DRM. It provides detailed instructions on how to apply differentiated security levels (L1/L3, SL2000/3000) based on content resolution using the multi-key method. This document is intended to serve as a technical reference for customers to understand and effectively implement these advanced DRM strategies.

Multi-key Concepts and Security Implications

Concept of multi-key DRM

Multi-key DRM refers to a sophisticated content protection strategy that applies different encryption keys for different track types in adaptive streaming content. This approach enables fine-grained control over video/audio tracks or content segments by resolution.

Key features of a multi-key implementation:

• Each content asset is assigned a unique ContentID.
• Within this ContentID, an individual KeyID is assigned to a specific Track Type.
• The system recognizes five main Track Types: SD, HD, UHD1, UHD2, and Audio.
• Different security policies can be applied to each Track Type when issuing DRM licenses.

Strategic benefits of implementing multi-key

Content services can gain the following benefits from a multi-key implementation:

1. Enhanced protection for premium content For adaptive streaming (ABR) content that includes high resolutions above 1080p, content providers can selectively enforce hardware DRM requirements for high-resolution tracks.

2. Support for flexible business models Multi-key and multi-manifest technologies enable fine-grained control over content access by limiting available video quality based on subscription tiers or user categorization.

Packaging Multi-key Content

Multi-manifest methodology

If you apply a per-track security policy to a single manifest (DASH mpd or HLS m3u8), even if the per-track keys are separated by multi-key packaging, you may experience issues with content playback on client environments that do not support hardware DRM or output security.

A multi-manifest approach can solve potential playback issues with the single manifest use case.

• Problem: When applying multi-key licenses in a single manifest, ABR operation can lead to playback failures when a player attempts to access a track with an unsupported security level.
• Solution: Create multiple manifest files per Track Type during the packaging phase. Client applications detect the security level of the environment and apply supportable manifests and security policies. This allows you to issue licenses that contain only the track information and keys that are essential for successful playback.

Multi-key packaging solutions

DoveRunner supports integration with its own packaging tools and third-party solutions for multi-key content packaging. Here are the features of each tool and how to use them.

DRM CLI Packager (v3.10.0 or later)

DoveRunner DRM CLI Packager is a powerful command line tool for encrypting and packaging content in your local environment.

Key Features:

• Supports various operating systems (Windows, macOS, Linux) Supports packaging in DASH, HLS, CMAF formats
• Multi-key and multi-manifest generation capabilities Support for handling subtitle files
• Fine-grained track type control options

How to use:

1. specify an mp4 file for each resolution as the input file (-i).
2. add the --multi_key option and the --generate_tracktype_manifests option to the command.
3. Add --skip_audio_encryption option to disable encryption for audio tracks (recommended)
4. If necessary, use the following options to adjust the resolution specified for each track type (SD, HD, etc.):

• --max_sd_height: Set the maximum resolution to be packaged as an SD track (default: 480).
• --max_hd_height: Set the maximum resolution to be packaged as an HD track (default: 1080)
• --max_uhd1_height: Set the maximum resolution to be packaged as UHD1 track (default: 2160)

Packaging command example:

PallyConPackager --enc_token <enc token> --content_id sample_multikey --dash --hls --multi_key --generate_tracktype_manifests --skip_audio_encryption -i <input file1> <input file2> ... 

Packaging result:

• DASH:
  • /sample_multikey/dash/stream_SD.mpd
  • /sample_multikey/dash/stream_HD.mpd
  • /sample_multikey/dash/stream_UHD1.mpd
  • /sample_multikey/dash/stream_UHD2.mpd
• HLS:
  • /sample_multikey/hls/master_SD.m3u8
  • /sample_multikey/hls/master_HD.m3u8
  • /sample_multikey/hls/master_UHD1.m3u8
  • /sample_multikey/hls/master_UHD2.m3u8

TNP(Transcoding & Packaging) Service

DoveRunner TNP Service is a cloud-based transcoding and packaging solution that allows you to easily and quickly package your content without building a separate packaging environment.

Key features:

• Easy task management through a web-based interface
• Automated workflows and support for multiple input formats
• High-performance cloud-based processing
• Offers multi-key and multi-manifest options
• Customizable transcoding profiles

How to use:

1. Log in to DoveRunner Console.
2. Go to Transcoding & Packaging → Settings menu.
3. In Service Status, enable the use of TNP service via Request activation.
4. When creating a new task, you can set the following options in Task Behavior in step 5 of task creation

• Multi-key and Multi-manifest options
• Audio track encryption option (recommended to skip audio encryption)
• Maximum resolution for each track type

The TNP service makes it easy to generate high-quality, multi-key DRM content without the need for complex local setup. It is especially useful when you need to process large volumes of content.

AWS MediaConvert and MediaPackage

AWS Media Services provide MediaConvert and MediaPackage services which support multi-key packaging via the SPEKE v2 specification.

For details on multi-key packaging and multi-manifest creation for AWS Media Services, please refer to AWS’s guidance documentation or contact AWS for technical support.

Detecting Security Level

An effective multi-key DRM implementation requires the ability to detect the security level supported by the client device and apply the appropriate manifest and security policy. This section describes how to detect the DRM security level (SL2000/SL3000, L1/L3) and HDCP version supported by a web or native client application.

Widevine clients

For Android devices or Chrome browser environments that support Widevine DRM, the following multi-key scenarios are supported natively, without the need for multiple manifests or separate handling based on client security level.

• Multi-key content: Use a single manifest, including the highest resolution video tracks
• DRM license token: Use a single token with different security policies for different tracks.
• Playback scenarios: Automated playback of playable video tracks within a single manifest based on the security levels supported by the client such as Widevine L1/L3 and HDCP version.

If some Widevine client environments experience issues with the above playback scenario or if you require video resolution limits based on business models, this can be handled with multiple manifests and the following client-side implementations.

Web browsers

For web browsers that support Widevine DRM, such as Chrome, you can detect the security level by referring to the sample code below and the HDCP Policy Check code.

function isWindowsChrome() {
  return navigator.userAgent.indexOf("Windows") > -1 && navigator.userAgent.indexOf("Chrome") > -1;
}

// Request media key system access
async function tryKeySystemAccess(keySystem, config) {
  try {
      await navigator.requestMediaKeySystemAccess(keySystem, config);
      return true;
  } catch {
      return false;
  }
}

// Base EME configuration
const baseEmeConfig = [{
  initDataTypes: ['cenc'],
  videoCapabilities: [{
      contentType: 'video/mp4;codecs="avc1.42E01E"'
  }],
  audioCapabilities: [{
      contentType: 'audio/mp4;codecs="mp4a.40.2"'
  }]
}];

// Widevine robustness levels in descending order
const robustnessLevels = [
  'HW_SECURE_ALL',
  'HW_SECURE_DECODE', 
  'HW_SECURE_CRYPTO',
  'SW_SECURE_DECODE',
  'SW_SECURE_CRYPTO'
];

// Create EME config with robustness
function createEmeConfigWithRobustness(videoRobustness, audioRobustness) {
  return [{
      ...baseEmeConfig[0],
      videoCapabilities: [{
          ...baseEmeConfig[0].videoCapabilities[0],
          robustness: videoRobustness
      }],
      audioCapabilities: [{
          ...baseEmeConfig[0].audioCapabilities[0],
          robustness: audioRobustness
      }]
  }];
}

async function getWidevineHighestSecurityConfig() {
  const keySystems = isWindowsChrome() ? 
      ['com.widevine.alpha.experiment', 'com.widevine.alpha'] : 
      ['com.widevine.alpha'];

  // Try with robustness levels
  for (const keySystem of keySystems) {
    for (const videoRobustness of robustnessLevels) {
        for (const audioRobustness of robustnessLevels) {
            const succeed = await tryKeySystemAccess(
                keySystem, 
                createEmeConfigWithRobustness(videoRobustness, audioRobustness)
            );
            
            if (succeed) {
                if (videoRobustness.startsWith('HW_SECURE_') || audioRobustness.startsWith('HW_SECURE_')) {
                    supportL1 = true;
                }
                return { keySystem, videoRobustness, audioRobustness };
            }
        }
    }
  }

Android native apps

For Android native applications, you can check the Widevine security level and HDCP support information via the API provided by Android MediaDrm.

fun getWidevineSecurity() {
        var mediaDrm: MediaDrm? = null
        return try {
            mediaDrm = MediaDrm(C.WIDEVINE_UUID)
            val securityLevel = mediaDrm.getPropertyString(PROPERTY_SECURITY_LEVEL)
            val hdcpLevel = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
                mediaDrm.getPropertyString(PROPERTY_HDCP_LEVEL)
            } else {
                "Unknown"
            }
            print("securityLevel : $securityLevel, hdcpLevel : $hdcpLevel")
        } catch (e: Exception) {
            e.printStackTrace()
        } finally {
            mediaDrm?.let {
                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
                    it.close()
                } else {
                    it.release()
                }
            }
        }
    }

PlayReady clients

Web browsers

For edge browsers that support PlayReady DRM, you can use the below EME KeySystem API to detect the security level.

// Request media key system access
async function tryKeySystemAccess(keySystem, config) {
  try {
      await navigator.requestMediaKeySystemAccess(keySystem, config);
      return true;
  } catch {
      return false;
  }
}

// Base EME configuration
const baseEmeConfig = [{
  initDataTypes: ['cenc'],
  videoCapabilities: [{
      contentType: 'video/mp4;codecs="avc1.42E01E"'
  }],
  audioCapabilities: [{
      contentType: 'audio/mp4;codecs="mp4a.40.2"'
  }]
}];

supportSl3000 = await tryKeySystemAccess('com.microsoft.playready.recommendation.3000', baseEmeConfig);

Windows native apps

For Windows applications that use PlayReady, you can use the PlayReadyStatics class.

using Windows.Media.Protection.PlayReady;

public class SecurityLevelDetector
{
    public static SecurityInfo GetPlayReadySecurity()
    {
        try
        {
            var securityLevel = PlayReadyStatics.PlayReadyCertificateSecurityLevel;
            var supportHardwareDRM = PlayReadyStatics.CheckSupportedHardware(PlayReadyHardwareDRMFeatures.HardwareDRM);

            return new SecurityInfo
            {
                SecurityLevel = securityLevel,
                SupportHardwareDRM = supportHardwareDRM
            };
        }
        catch (Exception ex)
        {
            System.Diagnostics.Debug.WriteLine($"Error getting PlayReady security information:  {ex.Message}"); 
            return new SecurityInfo
            {
                SecurityLevel = 150,
                SupportHardwareDRM = false
            };
        }
    }

    public class SecurityInfo
    {
        public uint SecurityLevel { get; set; }
        public bool SupportHardwareDRM { get; set; }
    }
}

FairPlay clients

Web client environments that support FairPlay DRM, such as macOS and iOS Safari browsers, cannot directly detect supported HDCP versions.

However, if you attempt to play HDCP-enabled content, or if there is an environmental change related to external output during playback (for example, connecting an external monitor), you can detect these events and apply your manifest and security policies appropriately.

const session = video.mediaKeys.createSession();
                
// Key Status Change Listener
session.addEventListener('keystatuseschange', () => {
  const statuses = session.keyStatuses;
  let statusText = '';
  statuses.forEach((status, keyId) => {
    statusText += `Status: ${status}, `;
  });
  Logger.info(`Key Status Changed: ${statusText || 'None'}`);
});

In client environments that do not support the HDCP security policy applied to the content you are playing, you can see events with a Key Status of output-restricted in the event listener above. At this point, the client application can switch to a manifest and security policy with resolution restrictions applied to prevent content playback errors and enhance the user experience.

Selecting manifest

After detecting the client security level, set up a manifest in the player with tracks that are playable in that environment. You can add FairPlay-specific code and HDCP enforcement logic to the example code below as needed.

function selectManifest(securityLevel, drm) {
    let manifestUrl;

    switch (drm) {
        case 'widevine':
            if (securityLevel === 1) {
                manifestUrl = 'https://<Service_Domain>/Sample/dash/stream_UHD1.mpd'
            } else {
                manifestUrl = 'https://<Service_Domain>/Sample/dash/stream_HD.mpd'
            }
            break;
        case 'playready':
            if (securityLevel >= 3000) {
                manifestUrl = 'https://<Service_Domain>/Sample/dash/stream_UHD1.mpd'
            } else if (securityLevel >= 2000) {
                manifestUrl = 'https://<Service_Domain>/Sample/dash/stream_HD.mpd'
            } else {
                manifestUrl = 'https://<Service_Domain>/Sample/dash/stream_SD.mpd'
            }
            break;

        default:
            manifestUrl = 'https://<Service_Domain>/Sample/dash/stream_SD.mpd';
    }

    return manifestUrl;
}

By implementing these detection and selection mechanisms, you can ensure that your multi-key DRM solution delivers the highest quality content possible while maintaining the required level of security across different devices and platforms.

Setting Token Policies

Widevine clients

Playback control by security level in a Widevine environment can be handled by a single security policy, such as the following. In the example below, we have set different levels of Widevine Security Level and external output security for SD, HD, and UHD1 video tracks.

{
    "policy_version": 2,
    "playback_policy": {
        "persistent": false,
        "allowed_track_types": "ALL"
    },
    "security_policy": [
        {
            "track_type": "SD",
            "widevine": {
                "security_level": 1,
                "required_hdcp_version": "HDCP_NONE",
                "required_cgms_flags": "CGMS_NONE"
            }
        },
        {
            "track_type": "HD",
            "widevine": {
                "security_level": 1,
                "required_hdcp_version": "HDCP_V1",
                "required_cgms_flags": "COPY_NEVER"
            }
        },
        {
            "track_type": "UHD1",
            "widevine": {
                "security_level": 5,
                "required_hdcp_version": "HDCP_V2_2",
                "required_cgms_flags": "COPY_NEVER",
                "hdcp_srm_rule": "CURRENT_SRM"
            }
        }
    ]
}

PlayReady clients

To support multi-key scenarios in a PlayReady environment, the security policy of the license token must also be different for different client security levels.

Hardware DRM

For environments where the client security level detection feature has identified PlayReady SL3000 (hardware-level DRM) and HDCP support, you can apply a license token security policy like the following example.

{
    "policy_version": 2,
    "playback_policy": {
        "persistent": false,
        "allowed_track_types": "ALL"
    },
    "security_policy": [
        {
            "track_type": "ALL_VIDEO",
            "playready": {
                "security_level": 3000,
                "digital_video_protection_level": 300,
                "analog_video_protection_level": 201,
                "digital_audio_protection_level": 300,
                "require_hdcp_type_1": true
            }
        }
    ]
}

Software DRM

For software-level (SL2000, SL150) or environments where HDCP is not supported, you can apply a token security policy like the example below.

{
    "policy_version": 2,
    "playback_policy": {
        "persistent": false,
        "allowed_track_types": "ALL"
    },
    "security_policy": [
        {
            "track_type": "ALL_VIDEO",
            "playready": {
                "security_level": 150,
                "digital_video_protection_level": 100,
                "analog_video_protection_level": 100,
                "digital_audio_protection_level": 100
            }
        }
    ]
}

FairPlay clients

Unlike the Widevine and PlayReady client environments, which are divided into software-level and hardware-level DRM, FairPlay clients all support hardware-level DRM.

Therefore, when applying a multi-key scenario, the maximum video resolution for FairPlay clients is primarily limited by whether or not the display output is secure.

Environments with output protection

For HDCP type 1 (v2.2 and later) environments, you can apply the following token security policies and manifests with high resolution tracks. You can also specify HDCP type 0 (v2.1 and earlier) or allow output display by the security requirements for the specific content.

{
    "policy_version": 2,
    "playback_policy": {
        "persistent": false,
        "allowed_track_types": "ALL"
    },
    "security_policy": [
        {
            "track_type": "ALL_VIDEO",
            "fairplay": {
                "hdcp_enforcement": 1,
                "allow_airplay": false,
                "allow_av_adapter": false
            }
        }
    ]
}

Environments without output protection

If HDCP is not supported or external output via AirPlay/AVadapter is required, you can apply a manifest restricted to low resolution with the following token security policies.

{
    "policy_version": 2,
    "playback_policy": {
        "persistent": false,
        "allowed_track_types": "SD_ONLY"
    },
    "security_policy": [
        {
            "track_type": "SD",
            "fairplay": {
                "hdcp_enforcement": -1,
                "allow_airplay": true,
                "allow_av_adapter": true
            }
        }
    ]
}

Limiting Resolution by BM

If you want to limit video resolution based on the plan a user subscribes to, regardless of the client security level, you can leverage multi-manifest to implement it as follows:

1. Specify mpd or m3u8 for the SD track of the content you want to play.

• DASH: https://<Service_Domain>/Sample/dash/stream_SD.mpd
• HLS: https://<Service_Domain>/Sample/hls/master_SD.m3u8

2. Specify the license token policy as follows. You can also allow HD resolutions if needed by your business models.

• Set allowed_track_types in playback_policy to SD_ONLY
• Set security policy for each DRM for SD tracks

{
    "policy_version": 2,
    "playback_policy": {
        "persistent": false,
        "license_duration": 0,
        "allowed_track_types": "SD_ONLY"
    },
    "security_policy": [
        {
            "track_type": "SD",
            "widevine": {
                "security_level": 1,
                "required_hdcp_version": "HDCP_NONE",
                "required_cgms_flags": "CGMS_NONE"
            },
            "playready": {
                "security_level": 150,
                "digital_video_protection_level": 100,
                "analog_video_protection_level": 100,
                "digital_audio_protection_level": 100
            },
            "fairplay": {
                "hdcp_enforcement": -1,
                "allow_airplay": true,
                "allow_av_adapter": true
            }
        }
    ]
}

By implementing these detection and selection mechanisms, you can ensure that your multi-key DRM solution delivers the highest quality content possible while maintaining the required level of security across different devices and platforms.

If you need further assistance or clarification on implementing an advanced DRM strategy, please contact DoveRunner Technical Support.