DRM Attributes for Remote Assets (Including Live Streams)

For remote assets protected by Digital Rights Management (DRM) systems, you need to associate information about that system.

Note: For more information about Backlot REST API commands, see the Backlot API Reference.
Note: These steps are applicable to live linear (assets not packaged by Ooyala).

Assets that are transcoded by and stored on the Ooyala system have the DRM attributes applied automatically, but remote assets do not pass through Ooyala transcoding and thus must be updated by you. For example, for live encoders this has to be updated by someone configuring the encoder (such as you or your vendor's technical support team).

For every remote asset that is protected by licenses issued from DRM systems operated by Ooyala, you need to set some attributes pertinent to the type of DRM system in use (FairPlay Streaming, Widevine or PlayReady).
  • FairPlay Streaming (FPS) requires a content key and iv. You can optionally set a lease or rental duration.
  • Widevine Modular is supported. If you are currently using Widevine Classic, please contact Technical Support or your account manager to help you transition to Widevine Modular.
  • PlayReady needs the license acquisition URL, content_key, and key_id (explained below).
  • To configure DRM with Adobe Access, contact your CSM to set up Adobe Access certificates for your live encoders.
    Note: Ooyala integration with Adobe Access DRM has been deprecated and is scheduled to be disabled. For details and alternatives, see the OVP Release Notes.
Note: For PlayReady-protected remote assets (when drm_type is playready or playready_hls on the request), you need to set these attributes before acquiring a license from PlayReady; otherwise, the remote asset under the protection of the DRM cannot be played.
Note: The DRM attributes used for PlayReady are key_id and content_key. The key id is an identifier associated with the content. It can be any 16-byte value expressed in base64 or hex format. The content key should be a random 16-byte value that is used as the AES key to encrypt the content. This may also be stored in base64 or hex format. You must check if your encoder requires the key id and content key to be in the base64 format or hex format. When you create a key for the first time, you don’t need to use a version. In this case your content key field will be content_key and the license URL would be:

http://player.ooyala.com/sas/drm2/jqbkH9m/UPHGNsr/playready/ooyala.

Ooyala allows you to associate multiple content keys with an asset. You can do this by naming the content key field as content_key_version where version is a number that needs to match the version in the license URL. For example, if the content key field is content_key_2, then the license URL would need to end with a 2: .../playready/ooyala/version/2. You may associate multiple keys with an asset by using a different version number each time. See example below.

Set/Replace FPS Encryption Key

Create a new FPS encryption key:

[POST] /v2/assets/asset_id/drm_attributes/fps

Response:

{
  "drm_type": "fps",
  "fps_content_key": "base64 encoded content key",
  "fps_content_key_iv": "base64 encoded iv"
}

The fps_content_key field contains a base64-encoded, 128-bit key that can be used for performing AES encryption on the video. The fps_content_key_iv field is a base64-encoded, 128-bit value to use as an initialization vector for encrypting the content.

Sample response:

{
  "drm_type": "fps", 
  "fps_content_key": "5HdVooYGEROm+LX2NJBDZg==", 
  "fps_content_key_iv": "rOw7gQauk7RCGVi1aeP9QQ==" 
}	

The first time you create a key, its value will be returned unmasked. Later on, if you create another key, the value of any existing key is returned masked.

To associate an existing FPS encryption key with an asset:

[PATCH] /v2/assets/asset_id/drm_attributes/fps

If you have multiple keys associated with the asset, include the version for this key in the body. For example, if this is the third key used for this asset, you will send the following JSON body with a key of 2QCEebexS0G8+3jP/pM7TA== and a version number of 3:

{ "fps_content_key_3” : "2QCEebexS0G8+3jP/pM7TA==" }

The response indicates that key 3 was stored successfully and with the key value masked:

{
  "fps_content_key_3": "*****",
  "drm_type": "fps"
}

To create versioned keys, use the POST route.

[POST] /v2/assets/:asset_id/drm_attributes/fps?version=1

Sample response:

{
  "fps_content_key" : "****", 
  "fps_content_key_1" : "12s213" , 
  "fps_content_key_iv_1" : "daiosd" 
}

Packaging Widevine Modular Media

For serving VOD content transcoded by Ooyala, the provider attributes needed are:

  • widevine_aes_key - Just press enter after writing the attribute name and the default value will be automatically populated for you.
  • widevine_aes_iv - Just press enter after writing the attribute name and the default value will be automatically populated for you.
  • widevine_portal_id - Set the value to ooyala.

For serving live content not transcoded by Ooyala, the provider attributes needed are:

  • widevine_aes_key_live - It is recommended that the customer get their own Widevine credentials via the Certified Widevine Certification Program (CWIP). Press enter after writing the attribute name and the default value will be automatically populated for you.
  • widevine_aes_iv_live - The customer might have their own iv that you will need to get from them. Press enter after writing the attribute name and the default value will be automatically populated for you.
  • widevine_portal_id_live - If the customer is using their own key and iv, then get this value from the customer, otherwise set to ooyala.

Set/Replace PlayReady Attributes for DRM Protection of Remote Asset

If you need to use a non-Ooyala system to generate the content key, you may use the following route for PlayReady Smooth to associate the key and key id with the Ooyala asset.

Note: The API route you need to use is different when managing attributes for PlayReady HLS and PlayReady Smooth. For PlayReady Smooth use the endpoint /v2/assets/asset_id/drm_attributes/playready, as shown below. For PlayReady HLS use the endpoint /v2/assets/asset_id/drm_attributes/playready_hls.
[PATCH]/v2/assets/asset_id/drm_attributes/playready{
   "key_id":"value1"
   "content_key":"value2"
}

If you have multiple keys associated with the asset, include the version for this key in the body. For example, if this is the second key used for this asset, you will send the following body:

{
   "key_id":"value1"
   "content_key_1":"value2"
}

Generating a PlayReady key_id and content_key

This route generates a random key id and content key for the asset and associates them with the video. You do not need to call the PATCH route described above to store these attributes in Ooyala's datastore if you get your key id and content key using this route. The JSON response contains the key id in base64 as well as guid/hex formats. The response also contains the content_key in base64 encoded format. drm_type can be specified as playready or playready_hls.
Note: This route will only work over https. API calls made over plain http will be rejected because the encryption key is sensitive information.
[POST] /v2/assets/asset_id/drm_attributes/drm_type

This will return:

{
   "key_id":"base64 encoded key id",
   "key_id_guid":"hex version of the key id",
   "drm_type":"playready",
   "content_key":"base64 encoded content key"
}

To create another key for the same asset, you can call the same route with the version set to any number.

[POST] /v2/assets/asset_id/drm_attributes/drm_type?version=2

This will return:

{ 
   "key_id":"base64 encoded key id",
   "key_id_guid":"hex version of the key id",
   "drm_type":"playready",
   "content_key_2":"base64 encoded content key",
   "content_key":"***"
}

Notice the old content_key is not returned. Its value is masked with ***. This is for security reasons.

Get DRM Attributes

[GET] /v2/assets/asset_id/drm_attributes/drm_type

License Acquisition URL

You need to put the license acquisition URL into the encoder. If you are unable to do so, your CSM can work with you to get this value configured in the encoder. Ooyala stores the license acquisition URL in Ooyala systems.

https://player.ooyala.com/sas/drm2/pcode/asset_id/playready/ooyala
https://player.ooyala.com/sas/drm2/pcode/asset_id/playready_hls/ooyala

Example

This example creates DRM attributes for the IzNnoCi9B2rtWs asset for a live encoder. The license acquisition URL for this asset is as follows:
https://player.ooyala.com/sas/drm2/IzNnoCi9B2rtWs/asset_id/playready/ooyala
Backlot returns a response similar to the following:
{
   "content_key":"*****",
   "drm_type":"playready",
   "key_id":"1234"
}
Note:

Try out the code samples using your account credentials in the Ooyala Scratchpad. For information about using the Scratchpad, see Practice Making Requests with the Scratchpad. To launch the scratchpad, go to Ooyala API Scratchpad.

Properties

The following table describes the properties you need to set for each DRM type.

drm_type Property Description
fps fps_content_key_version The FairPlay Streaming identifier for the asset.
playready key_id The key_id is an identifier associated with the content. It can be any 16-byte value expressed in base64 or hex format.

Type: String

Default: None

Example in base64 - V/YqH723UV48kjRlUzyqww==

Example in hex - 1f2af657b7bd5e513c923465533caac3
playready content_key_version The PlayReady content key. The version of the parameter name is an integer that matches the version in the license acquisition URL for the specific asset.

For example, if the license acquisition URL is:

https://player.ooyala.com/sas/drm2/jqbkH9m/UPHGNsr/playready/ooyala/version/3
Then the corresponding parameter name is content_key_3.

Type: String

Default: None

Example in base64 - V/YqH723UV48kjRlUzyqww==

Example in hex - 1f2af657b7bd5e513c923465533caac3

widevine widevine_modular_enabled When creating a remote asset that has Widevine modular DRM, the movie attribute widevine_modular_enabled must be set to 1. This movie attribute should not be added if the asset does not have Widevine modular DRM.

Parameters

The following table describes the parameters of the routes.
Parameter Description Required?
asset_id The unique identifier for an asset.

Type: String

Yes
pcode Your provider code. Yes
version The number identifying the version to use if multiple versions exist.

Type: Int

No

해당 내용이 도움 되었습니까?