Skip to content

Latest commit

 

History

History
491 lines (382 loc) · 22.7 KB

Readme.md

File metadata and controls

491 lines (382 loc) · 22.7 KB
Raw

Axinom DRM - quick start

This guide will show you how you can start using Axinom DRM to protect and play back premium video content.

The DRM technologies offered by Axinom are:

  • Google Widevine
  • Microsoft PlayReady
  • Apple FairPlay Streaming

There are separate repositories that contain a simple implementation of an Android frontend and iOS frontend that also showcase the usage of Axinom DRM.

Axinom DRM overview

This chapter presents the basic concepts of DRM and provides a high-level overview of a common Axinom DRM usage workflow that is further demonstrated in the following chapters. For more in-depth information about the involved processes and guidance on choosing a workflow best suited for your business needs Contact Axinom.

Content protection

The first phase in the use of DRM is the preparation of DRM-protected content. This is illustrated by the following diagram:

  1. Clear (unencrypted) content is provided to a DRM-capable encoder / packager.
  2. The encoder / packager contacts Axinom DRM Key Service and requests one or more content keys (content encryption keys).
  3. The key service generates new keys and returns them securely to the encoder / packager, together with the key IDs.
  4. The encoder / packager uses the key information to encrypt the content and package it in a format suitable for DRM-enabled adaptive streaming, and uploads the output to an origin server.

Protected content playback

The second phase is the playback of DRM-protected content. To play a video, a DRM-capable player needs to decrypt the media. For this, it needs access to the content keys, which are delivered in a license that also defines the conditions under which the content keys may be used (e.g. expiration). Licenses are generated by Axinom DRM License Service when a player sends the license service a license request together with a license token. The license token proves that the player has the right to get a license and instructs the license service how to configure and generate the license.

This process is illustrated by the following diagram:

  1. An end-user chooses a video in a media player's playlist and initiates playback.
  2. The player requests the content from a content delivery network (CDN).
  3. Encrypted content is streamed from the CDN to the player.
  4. The player notices the stream is protected by DRM and prepares for license acquisiton by obtaining a license request (from a Content Decryption Module, or CDM, integrated into the playback platform) based on the media metadata and requests a license token from the Entitlement Service.
  5. The Entitlement Service authenticates the end-user and generates a license token configured according to the content manager's business rules.
  6. The player then sends the license request, together with the license token, to the license service.
  7. License service authenticates the license token and generates a license (according to the information in the license token), which is then returned to the player.
  8. Playback starts (provided that the content keys are valid and playback rules are satisfied).

Solution components

The core Axinom DRM products are Axinom DRM Key Service and Axinom DRM License Service. Both are offered as cloud services while Axinom DRM License Service is also available as an on-premises installation.

The remaining parts of a DRM-enabled solution must be composed of additional Axinom or 3rd party products, or custom-developed components.

In terms of freely available 3rd party playback applications, we recommend the following robust and reliable players:

The player ecosystem on other platforms is less straightforward - Contact Axinom for assistance in player selection and integration.

Sample scenario 1: ready to go demo video

In the first scenario everything has been prepared for you - there exists a small website with an integrated player and a couple of DRM-protected demo videos that you can watch. All necessary DRM information is hardcoded into the application.

The sample application can be used with the latest versions of the following browsers (the DRMs supported are in parentheses):

  • Google Chrome (Widevine)
  • Mozilla Firefox (Widevine)
  • Microsoft Edge (PlayReady and Widevine)
  • Microsoft Internet Explorer (PlayReady)
  • Apple Safari (FairPlay)

Please follow the instructions below to run this sample project and go through the first sample scenario.

  1. Install node.js

  2. Clone or download this Git repository (the one that you are currently reading).

  3. Open a command prompt window and go to the directory where you placed the repository's files (e.g. C:\Source\drm-quick-start).

  4. Install required 3rd party packages by executing the following command:

    npm install

  5. Run the application by executing the following command:

    node Server.js

  6. If everything went well, the output from this command will instruct you to open http://localhost:8120 in your browser. Do so.

  7. Open the website and click one of the links: the selected protected demo video will play.

If you encounter any difficulties in getting the demo videos to play, inspect the log messages shown in the browser's JavaScript console and in the command prompt window.

Understanding sample scenario 1

The sample project implements a basic website that enables the user to select a video and play it in a modern DRM-capable browser. By default, there are only a few demo videos in the list but the later chapters will show you how to add more.

The main building blocks of the sample are:

  • Server.js - creates an HTTP server that publishes the website, the catalog API and the Entitlement Service.
  • VideoDatabase.js - defines the list of videos made available to the user.
  • CatalogApi.js - implements the catalog API that is used by browser-side JavaScript code to obtain the list of videos.
  • EntitlementService.js - implements the Entitlement Service - an API that authorizes playback requests coming from the browser-side JavaScript code and returns license tokens.
  • Website/index.html - the page loaded in the browser, including the browser-side JavaScript code; it communicates with the catalog API and the token service using REST web service calls; the website integrates Shaka Player for video playback.

In terms of executed workflows, the following takes place:

  1. When the website is loaded in a browser, the browser-side JavasScript code first determines whether the browser supports FairPlay.
  2. If FairPlay is supported, then the Axinom FairPlay Test Certificate is loaded from an Axinom server and the integrated player is configured for FairPlay use.
  3. Catalog API is contacted to retrieve the list of videos.
  4. Catalog API returns the videos listed in VideoDatabase.js. The demo videos are filtered by tags to only show those playable on the current browser.
  5. When the user clicks on a video link to start playback, the following will take place.
  6. The browser-side JavaScript code requests a license token from the Entitlement Service. In production, this service should also authorize the user.
  7. The Entitlement Service grants a token for every request, as there is no need to actually refuse playback in the sample scenarios. If the website requested permission to play one of the pre-defined videos then the Entitlement Service simply returns a hardcoded license token (this is a special case to keep the first sample scenario simple); other scenarios introduced below will use a more realistic workflow, where a new token is generated upon each request.
  8. Upon receiving the license token, the browser-side JavaScript code activates the embedded Shaka Player and instruct it to play the video, providing both the video URL and the DRM configuration. For the rest of the process, the player code will be in control.
  9. The player detects that the video is protected and requests a license from the license service, while also attaching the license token to the request.
  10. License service authorizes the license token and returns a license based on the information in the token.
  11. Playback starts (provided that the content keys in the license are correct and playback rules are met).

The code is thoroughly commented, so the above is only a high-level overview. To understand the details, please explore the source code.

Sample scenario 2: creating your own license tokens

In this scenario, sample project is going to be modified to generate a unique license token upon every request, instead of returning a hardcoded one.

Axinom DRM evaluation account is needed in order to proceed. Upon signing up, you will need to go to the "DRM" area from My Mosaic and you can request for a DRM tenant. With that you will receive a document containing DRM configuration information required below.

To modify the project for the second sample scenario:

  1. Open VideoDatabase.js and pick one of the pre-made video entries, which is going to be modified and worked with for the rest of this scenario.

  2. Depending on your browser, choose one of the following:

    • On Safari: "Axinom demo video - single key (HLS; cbcs)"
    • Other browsers: "Axinom demo video - single key (DASH; cenc)"

  3. If you are using Axinom Encoding, remove the hardcoded license token from the video and replace it with the following keys list:

        "keys": [
        {
            "keyId": "211ac1dc-c8a2-4575-baf7-fa4ba56c38ac"
        }
    ]

or if you are using a sample video provided by Axinom, the key seed of the tenant that was used to encode the video will be different and you'll need to explicitly generate and provide a token in the video entry( VideoDatabase.js ) that contains the embedded encryption key for the media. We recommend to use the https://portal.axinom.com/mosaic/tools/entitlement-message tool for token generation.

        {
            "name": "Axinom demo video - single key (DASH; cenc)",
            "url": "https://media.axprod.net/TestVectors/v7-MultiDRM-SingleKey/Manifest.mpd",
             "licenseToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2ZXJzaW9uIjogMSwiY29tX2tleV9pZCI6ICI0N2RhM2NlMC04ZjFlLTQ4NDYtYTUwZi1hZTc0MDAzY2Y0MmMiLCJtZXNzYWdlIjogeyAgInR5cGUiOiAiZW50aXRsZW1lbnRfbWVzc2FnZSIsICAidmVyc2lvbiI6IDIsICAiY29udGVudF9rZXlzX3NvdXJjZSI6IHsgICAgImlubGluZSI6IFsgICAgICB7ICAgICAgICAiaWQiOiAiOWViNDA1MGQtZTQ0Yi00ODAyLTkzMmUtMjdkNzUwODNlMjY2IiwgICAgICAgICJlbmNyeXB0ZWRfa2V5IjogIjgwOWxkUzVYM1VqU29ON1ovMjN6aFE9PSIgICAgICB9ICAgIF0gIH19fQ.OaOk2jS3KreIB4WCqBD4_0GI4S5Hb_yiWEORLRL-qCA",
        }

  1. Create a Secrets.json file based on the sample below and place it in the same directory as Server.js. Replace the communication key below with real values from the Axinom DRM Fact Sheet.

    {
    "communicationKeyId": "00000000-0000-0000-0000-000000000000",
    "communicationKey": "00000000000000000000000000000000000000000w=="
}

    The communication key is used to digitally sign license tokens and secure the transfer of sensitive data. The signature will be checked by the license service to authenticate the token and to verify its integrity, making the token impossible to forge. See the comments in EntitlementService.js for more details.

    Having created the Secrets.json file, you should see a message about it being loaded when you start the application.

    From now on the token service will generate a unique license token upon every request for videos not using a hardcoded token.

  2. Run the application, open the website in a browser and go play the video!

If you encounter any difficulties in getting the demo video to play, inspect the log messages shown in the browser's JavaScript console and in the command prompt window.

Understanding sample scenario 2

The logic for generating license tokens is already provided in EntitlementService.js and this functionality is activated by the instructions above. In order to generate a license token, the token service needs to know the IDs of all content keys that are to be made available to the user.

Note: this pattern of key management is simplified compared to actual production use. See the chapter on security below.

Sample scenario 3: creating your own videos

In this scenario the sample project is going to be modified to play back videos that you create.

To proceed, please ensure that the following prerequisites are fulfilled:

  • The sample project modifications described in scenario 2 are already performed.

  • Makesure you have access to the Mosaic Management system. You can acquire a Management system for yourself via https://portal.axinom.com/mosaic/my-mosaic

  • Ensure that you have an MP4 or MOV file containing both video and audio. You can download some free test content in this format from the Blender Foundation. During initial experimentation it is recommended to start out with short clips to reduce media processing time.

The steps below will transform this your video file into a format suitable for playback:

  1. Create Storage for an Input Storage for Axinom Encoding (this is where the source material will be uploaded to) and an Output Storage (this is where Axinom Encoding) will store the encoding results.
  2. Set up an Acquisition and a Publishing Profile.
  3. Set up a Processing Profile.
  4. Upload a video to the Input Storage (use a subfolder for each video).
  5. Start encoding. Wait until encoding is finished.

Create storage for Input

The simplest way to create a Storage is using a Mosaic Hosting Service.

Follow instructions under Storage with Mosaic Hosting Service

With a few clicks you will get a Storage Account in Microsoft Azure, which you can use from Axinom Mosaic, but also directly using tools such asAzure Storage Explorer.

Set up an Acquisition and a Publishing Profile

Log in to your Mosaic Management System and follow instructions under Set up Encoding Profiles. As a storage provider choose "Microsoft Azure". All the required configuration (such as, account name, account key, SAS token) you can copy from the previous step (Storage properties).

Your secrets, such as your account key, shall be entered encrypted (with a certificate of Axinom Encoding), so that only Axinom Encoding can access your storage. To encrypt credentials, use Credentials Protection Tool.

Set up a Processing Profile

Log in to your Mosaic Management System. You will find Processing Profiles under Settings / Video Encoding.

You can create a new profile or edit the DEFAULT profile. The properties here impact the encoding process. check Processing Profile document to have more understanding about the each property.

We recommend for the start leaving all values at their defaults. You can experiment with them later.

Upload the video

Upload the video to your Input Storage. Select the container video-input, create a subfolder for your video and upload the .mp4 file there. Just a single .mp4 file is enough.

To upload a file to your storage you can use a tool such as Azure Storage Explorer.

Alternatively, you can upload files directly in Axinom Portal. Go to My Mosaic / Encoding and select "Upload a Source Video". This module uploads files to your storage previously created with the Mosaic Hosting Service.

Encode the video

  1. To start encoding follow the steps below:
  2. Log in to your Mosaic Management System.
  3. Go to "Videos", then "New". You will get a list of folder in your configured Input Storage.
  4. Select the folder with your video
  5. Click Start encoding.

Encoding process takes some time (the longer the video, the longer the process). You can observe the progress looking at the logs, accessible from the respective station.

Once encoding is finished, you can copy the link to the DASH manifest and play it with any DASH-capable video player.

Add the video details to VideoDatabase.js

Having created the video, add a matching entry to VideoDatabase.js. You need to provide a video name, the URL to one of the manifest files and the Key ID used in encrypting the video or a token with key and the keyID.

```
{
    "name": "My video 1",
    "url": "http://localhost:8120/Video1/Encrypted_Cenc/Manifest.mpd",
    "keys": [
        {
            "keyId": "60447277-19b2-4367-a1e0-da543aee2da0"
        } 
    ]
}
```

Note: when evaluating FairPlay, e.g. on Safari, use the URL of the HLS-CBCS manifest (Encrypted_Cbcs/Manifest.m3u8); otherwise use the DASH-CENC manifest (Encrypted_Cenc/Manifest.mpd).

That's it! You can now start the application, open the website and play your video!

If you encounter any difficulties in getting the demo video to play, inspect the log messages shown in the browser's JavaScript console and in the command prompt window.

Follow the same process to play videos created with 3rd party tools. As each media processing product operates differently, universal instructions cannot be provided here. Contact Axinom for detailed support in setting up your media workflows.

Sample scenario 4: creating your own multi-key videos

When working with high-value content, content owners may require the usage of different keys for different tracks and quality levels.

Current scenario, very similar to the previous 3rd scenario, demonstrates how to prepare multi-key content. It will use UI for all operations (Mosaic Management System) to create multi-key content similar to the predefined "multikey" demo videos in VideoDatabase.js, where the FHD and HD tracks (1080p and 720p), SD tracks (480p, 360p and 288p) and the audio track are encrypted with different keys.

In order to proceed, please ensure that the following prerequisites are fulfilled:

  • Scenario 3 is completed and understood.
  • Make sure the input video has at least 720p resolution. Otherwise HD-track specific keys cannot be applied, and your content will end up being encrypted with fewer different keys.

Steps for multi-key content preparation:

  1. While Setting up the Processing Profile as mentioned in the scenario 3, you will have to select the DRM Protection to Multi Keys.

  2. Then run the encoding process.

  3. Wait for the video to be processed. When finished, the output location will have similar contents as in scenario 3. However, if you open the HLS or DASH manifests of the encrypted content with a text editor, you'll notice that now different tracks are associated with different content key IDs.

  4. Add a matching entry to VideoDatabase.js, similarly to scenario 3. The only difference is that this time multiple Key IDs need to be specified - all three that were used in the encryption of this video.

    {
    "name": "My video 2",
    "url": "http://localhost:8120/Video2/Encrypted_Cenc/Manifest.mpd",
    "keys": [
        {
            "keyId": "f3d588c7-c17a-4033-9035-8db317390be6"
        },
        {
            "keyId": "44b18a32-6d36-499d-8b93-a20f948ac5f2"
        },
        {
            "keyId": "ae6e87e2-3c3c-46d1-8e9d-ef4c461d4681"
        }, 
    ]
}

    Note: when evaluating FairPlay, e.g. on Safari, use the URL of the HLS-CBCS manifest (Encrypted_Cbcs/Manifest.m3u8); otherwise use the DASH-CENC manifest (Encrypted_Cenc/Manifest.mpd).

  5. That's it! Start the application, open the website and play your multi-key video.

Moving onward to real-world usage

In a real-world scenario there are potentially many more aspects to consider.

  • Axinom DRM License Service and Key Service are highly flexible and can accommodate to a wide range of scenarios:

    • Axinom DRM can work in different modes - it supports working with key seeds as well as individual keys.

    • Axinom DRM Key Service supports several key delivery protocols out of the box, including AWS SPEKE and Google Widevine Common Encryption API

    • Axinom has complementary offerings that can help create a comprehensive video streaming solution: Axinom VIP - for encoding / packaging, Axinom Player SDK - for secure playback, and Axinom CMS - for managing content.

  • To keep the sample code straightforward, simplifications have been made. The following additional aspects should be considered when planning a real-world deployment:

    • The Entitlement Service shown here authorizes every user for every playback request and produces tokens with very relaxed playback restrictions. Adjust this behaviour according to your business needs, so that only the intended users can play back content under intended terms.

    • Your website or client app should use HTTPS in order to protect against the interception of communications (e.g. to steal the license token generated by the token service). Also, if your website/player is not served on localhost, it must be accessed using HTTPS to enable DRM playback.

    • You must carefully plan the life cycle of license tokens to match your business scenario. While the sample project requests a license token immediately before playback, this need not always be so. Some scenarios may benefit from long-lived license tokens generated well in advance of playback, thereby reducing network traffic. On the other hand, long-lived license tokens enable a greater degree of misuse if they are ever stolen; short 5-minute license tokens enable a stricter level of control for scenarios where that is a concern.

Contact us to learn more about our offerings and to get support in setting up your production environment.