What is Personalization

Personalization is the process by which a Marlin DRM client (ExpressPlay SDK) acquires the keys and credentials it needs to be able to interact with a Marlin DRM service (ExpressPlay or other Marlin DRM service). Personalization is required for all clients and must occur before a client can be used.

Personalization can be achieved in two methods. The simplest way is to use ExpressPlay's built-in personalization service, in which case the client acquires the keys and credentials over a secure protocol from the service, at a time when it is convenient for the client to engage in the transaction. The ExpressPlay SDK (unless you are using a custom SDK build) is pre-configured to use ExpressPlay's personalization service. The second method which is considerably more complex, is for the developer of the application or device that uses the client to acquire these keys out of band and insert them into the client securely at final release or manufacture time, before the client needs to use them in production.

Handling failures

Personalization failures come in several flavors. As offline personalization is often quite specific to the developer's application logic, we will leave failure scenarios of this kind out of scope. Personalization using ExpressPlay's build-in personalization service may experience the following types of failures:

• lack of or unreliable network connectivity
• lack of or unreliable host connectivity
• a TLS handshake failure

Using the java API for Android: In general, failures can be trapped if the application code implements the wasabi.drm.TransactionListener class. During the personalization process, the ExpressPlay engine calls back the listeners with status at each stage of the process. Errors are surfaced, and can be examined by looking them up using the wasabi.ErrorCodeExplanation class.

Another class of failures can occur after personalization has been attempted and perhaps concluded successfully. Successful Personalization results in the creation of 2 databases, db0.storage and LicenseStore.db. In some rare circumstances access to these databases can fail resulting in an un-personalized client and causing further attempts at personalization to fail. The preferred remedy to this situation is to delete these 2 databases and to re-personalize.

Content License Aquisition

The following section describes content license acquisition using MS3 tokens as well as Marlin Broadband (BB) tokens.

MS3 Tokens vs. BB Tokens

At some point after getting personalized, your application will need to acquire a content license.

Marlin supports two types of licenses:

• The first type is called a Simple Access Statement (SAS) acquired over a protocol called Marlin Simple Secure Streaming (MS3), a lightweight TLS protocol between a personalized client and a Marlin MS3 License server
• The second type is called a Marlin Broadband (Marlin BB) License. This license type is acquired over the more feature-rich Marlin BB protocol.

The MS3 protocol is simple and delivers only SAS-type licenses, which are "use once and forget" type licenses with a limited set of constraints and are typically used when streaming content. The Marlin BB licenses on the other hand are self-protected objects that can express complex usage rules and that can be preserved in a local license store to be used over and over again, as long as they are valid.

The ExpressPlay service hosts both an MS3 server and a Marlin BB license server, and it can generate tokens for both types. These tokens are then passed to the client for redemption into licenses via the ExpressPlay SDK.

MS3 License Acquisition

When acquiring an MS3 license, a media storefront must supply the client application with a token containing the content location (C-URL) and an MS3 server license request (S-URL) where authorization to access the content may be obtained. This MS3 token is called a "compound URL". It is used by the expressplay SDK both to obtain access to the media stream and to obtain a Stream Access Statement (SAS, or license) over TLS.

BB License Acquisition

Marlin BB tokens work much the same way as MS3 tokens - they are provided by the Media Store Front to the application; however, BB tokens are provided as an XML document which is processed by the client separately from the content URL. BB tokens also enable some additional playback options as licenses may be reused for offline playback. During the license acquisition, the client application will store the content license in a local license store. This makes the license available to the DRM engine later when the application wants to playback the content offline.

Streaming vs. Offline

The ExpressPlay SDK supports streaming playback while the application is connected to the Internet, as well as download and offline playback. For streaming playback it is recommended to use Marlin MS3 format tokens, because they are easier to process. For download and offline playback it is recommended that you use Marlin BB tokens, as BB tokens can be stored with the app or embedded into the content for offline use.

Test vs. Production

ExpressPlay provides two service infrastructures: Test and Production. The Test service works only with the "ExpressPlay Test SDK" and the Production service works only with the "ExpressPlay SDK".

In order to meet the Marlin Compliance and Robustness Rules, among other things, the keys and certificates acquired during personalization must be managed securely with the confines of a client implementation. ExpressPlay clients utilize sophisticated key hiding and software tamper resistance technologies to make it very difficult for an attacker to extract these keys. An effect of that is that developing and debugging applications and services is not possible when using keys that must be well guarded.

ExpressPlay SDKs and Service are therefore available with two types of keys - one set called Test Keys and one set called Production Keys. The test keys are not protected, and debugging with a client that uses test keys is possible. Clients and services with Test Keys and Production Keys do not interoperate, both must use either Production or Test Keys.

Supported Formats

The ExpressPlay SDK supports the formats shown in the table below for encrypted video and audio: MPEG-DASH, HTTP Live Streaming (HLS), MP4 (PDCF), MPEG-TS (BBTS) and for ebooks: ePub (Marlin spec), PDCF encapsulated file.

Note: To abide by the Content Provider’s robustness rules, the expressplay sdk limits the resolution of the content that can be displayed to 520K. On MacOS/Windows it will attempt to downscale, on iOS/Android it will refuse to playback content with higher resolution.
If your content license permits you to lift this restriction, you can do so by adding parameters to your ExpressPlay license requests:

• adding the following request parameters to the ExpressPlay Service MS3 license request: "&extensionType=wudo&extensionCriticalFlag=false&extensionPayload=AAAAAA=="
• adding the following request parameters to the ExpressPlay Service BB license request: "&outputControlOverrideId=urn:marlin:organization:intertrust:wudo&outputControlOverrideParameter=ImageConstraintLevel &outputControlOverrideValue=0"

Supported Streaming Formats
Format	Encryption	Android	iOS	Desktop (Win, OSX)	Embedded Linux (Source SDK)
MPEG2-TS1	Marlin BBTS, all modes	YES3	YES3	YES4	YES
DASH-MP42	CENC	YES5,6	YES6	YES7	YES
DASH-MP42	clear	YES5,6	YES6	YES	YES
HLS8	Marlin BBTS	YES5	YES	YES	YES
HLS8	Pantos-RFC AES-128 CBC	YES5	YES	YES	YES
HLS8	clear	SDK not needed	SDK not needed	YES	YES

Supported Downloadable Formats
Format	Encryption	Android	iOS	Desktop (Win, OSX)	Embedded Linux (Source SDK)
PDCF	AES 128 CTR & CBC	YES9	YES9	YES	YES
BBTS	Marlin BBTS	YES9	YES9	YES10	YES
DCF	AES 128 CTR & CBC	YES9	YES9	YES	YES
CFF (fMP4)	CENC	YES9	YES9	NO	YES11

Footnotes:

1. HTTP streaming of MPEG2-TS
2. Multiple and single bit rate streams are supported; isoff-live profile (urn:mpeg:dash:profile:isoff-live:2011), as referenced in HbbTV 1.5
3. Indexed streams only
4. With a limitation that discontinuity from bit rate change and seeking is not supported at this time
5. Android 4.x or greater required
6. No single stream support, additional constraints from Playlist Proxy
7. Wideo single stream not supported
8. Static, vod and live streams
9. Using Playlist Proxy
10. With a limitation that resolution change and seeking are not supported at this time
11. Requires a custom media stack developed by a third party

SOFTWARE DECODER FOR DESKTOP: The SDK binaries for desktop platforms consist of shared objects on Windows and OS X. A license to the software decoder is included with the SDK; however, no MPEG-LA or AAC decoder IP license is provided. Such IP licenses should be obtained prior to distribution of the included software decoders. The SDK binaries are protected to meet the required robustness rule and will give a good indication or performance of the production application

Included Software Codecs for Windows and Mac OS X:

• Intel IPP decoder for H.264 video.
• AAC LC (low complexity) audio.

For a good user experience, media packaged in single MP4 files should first be downloaded by the application (or progressively downloaded) so that the player engine reads media data from an already downloaded file. Attempting to stream such content without downloading is not recommended.

Core and Extended Digital Rights Management (DRM) Functions

Beyond initialization and playback there are other DRM functions available in the ExpressPlay SDK.

Some of the additional functions include:

• Token processing
• Managing the license store when using BB licenses

See the WSB_LicenseStore and SHI_Engine_ API reference descriptions for such extended DRM functionality.

Output Restrictions Imposed by Marlin Robustness Rules

To satisfy the Marlin Robustness rules, the digital video output of the desktop platform binaries is downscaled if necessary (and possible). When downscaling, the SDK will limit the resolution of the content that can be displayed to 520,000 pixels. For example, a video with 720x480 resolution is 345,600 pixels, below the limit. A video with 1280x720 resolution is 921,600 pixels, above the limit. For adaptive-bitrate streaming (HLS and DASH), the client will automatically filter out the resolutions above the limit and keep the ones below the limit.

Additional constraints:

• On all platforms, playback is denied for content licenses which contain output controls as these output controls cannot easily be enforced on each platform via the SDK.

Other Marlin BB protocols and objects

Marlin DRM servers in general and ExpressPlay service in particular also generate other Marlin DRM objects, such as Nodes and Links. These objects are used to represent possible relationships for expressing rights such as group membership. Such objects are useful when considering content playback scenarios other than streaming, or when offline. For instance, a client could become part of a family group of clients, so that content licenses can be issued to the group membership, and a license is then valid on any device that can prove membership in the group. In that scenario, one member of the group could acquire content and licenses (say a media server in a home). Any devices that can be considered part of the group would then simply acquire a group membership (expressed by a node and a link) and then be able to playback the content stored on the home media server.