DRM preferences and security levels

The CONNECT Player SDK for Browsers and Connected TV supports different DRM key systems depending on the browser/device and the content protocol:

• Widevine

• Playready

• FairPlay

• TVKey

• Nagra CONNECT

The key systems may have different security levels, depending on the device's capabilities and the browser on which they are used.

Four increasing security levels are defined:

1. OTVDRMSL_UNKNOWN 

2. OTVDRMSL_SW

3. OTVDRMSL_HW_CRYPT

4. OTVDRMSL_HW_DECODE

Where a browser supports multiple DRM key systems, the SDK provides mechanisms by which the application can specify its preferred key system. The SDK provides an API to find the security level of the key system on the browser to aid in selecting the preferred key system.

Querying security level capabilities

To query security level capabilities, use the getDrmInfo() API call which returns a Promise that resolves to provide an array of the DRM capabilities.

playerInstance
   .otvtoolkit()
   .drmSecurityLevel.getDrmInfo(keySystem, mediaType, contentType);

When details of a specific DRM key system and, optionally, a specific media and content type combination are required, this can be requested in the arguments to getDrmInfo(). For example, querying for Widevine encrypted video at a specific codec, if the mediaType and contentType parameter combination is omitted, then defaults will be used depending on the keySystem:

playerInstance
   .otvtoolkit()
   .drmSecurityLevel.getDrmInfo(
       "com.widevine.alpha",
       "video",
       'video/mp4;codecs="avc1.640015"'
   );

Details of a specific DRM key system and optional specific media and content type combination can be requested in the arguments to getDrmInfo(). For example, querying for Widevine encrypted video generically:

playerInstance
   .otvtoolkit()
   .drmSecurityLevel.getDrmInfo("com.widevine.alpha");

When no arguments are supplied, all DRM systems are queried, and the results will contain their capabilities (only supported key systems are included). Querying all supported keySystems:

playerInstance.otvtoolkit().drmSecurityLevel.getDrmInfo();

Setting the preferred DRM key system

For the multi DRM OTT stream encrypted using CENC algorithms, if the App configures the preferredDRM with a KeySystem name and the client device also supports the same matching KeySystem, then that will be selected as a DRM KeySystem for decrypting the content.

Setting the preferred key system on player initialisation

otvplayer(
 "videoPlayer",
 // options
 {
        ......
     plugins: {
         otvtoolkit: {
             drm: {
                    ......
                 config: {
                     preferredDRM: "com.widevine.alpha",
                     useHW: true,
                 }
             }
         }
     }
 }
);

In HbbTV mode, assuming the preferred player is not overridden (i.e., the default player is native, not ShakaPlayer), the CONNECT Player will automatically pick TVKey DRM system ("com.tvkey.drm") as the default and only DRM system available; this cannot be overridden.

Similarly in VEWD based STBs that support Nagra CONNECT ("com.nagra.prm").

In addition to the preferredDRM configuration, the flag useHw is used to enforce whether the selected DRM KeySystem should use the hardware-level crypto engine provisioned in the platform for decrypting and decoding the content in a secured chipset memory or not. Suppose the useHw: true, but the hardware level decryption is not available in the client device; then the playback must fail by the player with a DRM system error. The useHw is defined as false in the player if it is not configured.

The useHw flag can be ignored if separate keySystem names are available for both SW and HW decryption, such as com.microsoft.playready.recommendation and com.microsoft.playready.recommendation.3000, because in this case, the HW or SW KeySystem selection is purely based on preferredDRM configuration only.

Setting the preferred key system on source selection

player.src({
    src: stream.url,
    token: stream.Token,
    preferredDRM: "com.widevine.alpha"
});

Setting the preferred key system using the drmSecurityLevel API

playerInstance
   .otvtoolkit()
   .drmSecurityLevel.setPreferredDrm("com.widevine.alpha");

Finding the actual key system used for playback

The application may select a preferred key system that is not supported by the browser or not supported for a piece of content. In this case, the SDK will use a different key system. To find the actual key system in use during playback:

let ks = playerInstance.otvtoolkit().drmSecurityLevel.getCurrentSelectedDrm();

getCurrentSelectedDrm() is only valid during playback. Until playback starts, it will return the preferred DRM key system.