開発者センター

SDK Key Concepts

This section describes the key concepts useful to developers using the ExpressPlay SDK. It is recommended that developers review this section prior to reading the SDK Overview for a specific platform or the SDK API reference.

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 Broafdband (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 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.

• 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.

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”