MediaDrm

public final class MediaDrm
extends Object implements AutoCloseable

java.lang.Object
   ↳ android.media.MediaDrm


MediaDrm can be used to obtain keys for decrypting protected media streams, in conjunction with MediaCrypto. The MediaDrm APIs are designed to support the ISO/IEC 23001-7: Common Encryption standard, but may also be used to implement other encryption schemes.

Encrypted content is prepared using an encryption server and stored in a content library. The encrypted content is streamed or downloaded from the content library to client devices via content servers. Licenses to view the content are obtained from a License Server.

MediaDrm Overview diagram

Keys are requested from the license server using a key request. The key response is delivered to the client app, which provides the response to the MediaDrm API.

A Provisioning server may be required to distribute device-unique credentials to the devices.

Enforcing requirements related to the number of devices that may play content simultaneously can be performed either through key renewal or using the secure stop methods.

The following sequence diagram shows the interactions between the objects involved while playing back encrypted content:

MediaDrm Overview diagram

The app first constructs MediaExtractor and MediaCodec objects. It accesses the DRM-scheme-identifying UUID, typically from metadata in the content, and uses this UUID to construct an instance of a MediaDrm object that is able to support the DRM scheme required by the content. Crypto schemes are assigned 16 byte UUIDs. The method isCryptoSchemeSupported(UUID) can be used to query if a given scheme is supported on the device.

The app calls openSession() to generate a sessionId that will uniquely identify the session in subsequent interactions. The app next uses the MediaDrm object to obtain a key request message and send it to the license server, then provide the server's response to the MediaDrm object.

Once the app has a sessionId, it can construct a MediaCrypto object from the UUID and sessionId. The MediaCrypto object is registered with the MediaCodec in the MediaCodec.configure(MediaFormat, Surface, MediaCrypto, int) method to enable the codec to decrypt content.

When the app has constructed MediaExtractor, MediaCodec and MediaCrypto objects, it proceeds to pull samples from the extractor and queue them into the decoder. For encrypted content, the samples returned from the extractor remain encrypted, they are only decrypted when the samples are delivered to the decoder.

MediaDrm methods throw MediaDrm.MediaDrmStateException when a method is called on a MediaDrm object that has had an unrecoverable failure in the DRM plugin or security hardware. MediaDrm.MediaDrmStateException extends IllegalStateException with the addition of a developer-readable diagnostic information string associated with the exception.

In the event of a mediaserver process crash or restart while a MediaDrm object is active, MediaDrm methods may throw MediaDrmResetException. To recover, the app must release the MediaDrm object, then create and initialize a new one.

As MediaDrmResetException and MediaDrm.MediaDrmStateException both extend IllegalStateException, they should be in an earlier catch() block than IllegalStateException if handled separately.

Callbacks

Applications should register for informational events in order to be informed of key state updates during playback or streaming. Registration for these events is done via a call to setOnEventListener(MediaDrm.OnEventListener). In order to receive the respective callback associated with this listener, applications are required to create MediaDrm objects on a thread with its own Looper running (main UI thread by default has a Looper running).

Summary

Nested classes

class MediaDrm.CryptoSession

In addition to supporting decryption of DASH Common Encrypted Media, the MediaDrm APIs provide the ability to securely deliver session keys from an operator's session key server to a client device, based on the factory-installed root of trust, and then perform encrypt, decrypt, sign and verify operations with the session key on arbitrary user data. 

@interface MediaDrm.HdcpLevel

 

class MediaDrm.KeyRequest

Contains the opaque data an app uses to request keys from a license server. 

class MediaDrm.KeyStatus

Defines the status of a key. 

class MediaDrm.MediaDrmStateException

Thrown when an unrecoverable failure occurs during a MediaDrm operation. 

class MediaDrm.MetricsConstants

Definitions for the metrics that are reported via the MediaDrm.getMetrics() call. 

interface MediaDrm.OnEventListener

Interface definition for a callback to be invoked when a drm event occurs  

interface MediaDrm.OnExpirationUpdateListener

Interface definition for a callback to be invoked when a drm session expiration update occurs  

interface MediaDrm.OnKeyStatusChangeListener

Interface definition for a callback to be invoked when the keys in a drm session change states. 

class MediaDrm.ProvisionRequest

Contains the opaque data an app uses to request a certificate from a provisioning server  

@interface MediaDrm.SecurityLevel

Security level indicates the robustness of the device's DRM implementation. 

Constants

int EVENT_KEY_EXPIRED

This constant was deprecated in API level 26. Use MediaDrm.OnKeyStatusChangeListener.onKeyStatusChange(MediaDrm, byte[], List, boolean) and check for MediaDrm.KeyStatus.STATUS_EXPIRED in the MediaDrm.KeyStatus instead.

int EVENT_KEY_REQUIRED

This event type indicates that the app needs to request keys from a license server.

int EVENT_PROVISION_REQUIRED

This constant was deprecated in API level 23. Handle provisioning via NotProvisionedException instead.

int EVENT_SESSION_RECLAIMED

This event indicates that a session opened by the app has been reclaimed by the resource manager.

int EVENT_VENDOR_DEFINED

This event may indicate some specific vendor-defined condition, see your DRM provider documentation for details

int HDCP_LEVEL_UNKNOWN

The DRM plugin did not report an HDCP level, or an error occurred accessing it

int HDCP_NONE

HDCP is not supported on this device, content is unprotected

int HDCP_NO_DIGITAL_OUTPUT

No digital output, implicitly secure

int HDCP_V1

HDCP version 1.0

int HDCP_V2

HDCP version 2.0 Type 1.

int HDCP_V2_1

HDCP version 2.1 Type 1.

int HDCP_V2_2

HDCP version 2.2 Type 1.

int KEY_TYPE_OFFLINE

This key request type specifies that the keys will be for offline use, they will be saved to the device for use when the device is not connected to a network.

int KEY_TYPE_RELEASE

This key request type specifies that previously saved offline keys should be released.

int KEY_TYPE_STREAMING

This key request type species that the keys will be for online use, they will not be saved to the device for subsequent use when the device is not connected to a network.

String PROPERTY_ALGORITHMS

String property name: a comma-separated list of cipher and mac algorithms supported by CryptoSession.

String PROPERTY_DESCRIPTION

String property name: describes the DRM plugin

String PROPERTY_DEVICE_UNIQUE_ID

Byte array property name: the device unique identifier is established during device provisioning and provides a means of uniquely identifying each device.

String PROPERTY_VENDOR

String property name: identifies the maker of the DRM plugin

String PROPERTY_VERSION

String property name: identifies the version of the DRM plugin

int SECURITY_LEVEL_HW_SECURE_ALL

DRM key management, crypto operations, decoding of content and all handling of the media (compressed and uncompressed) is handled within a hardware backed trusted execution environment.

int SECURITY_LEVEL_HW_SECURE_CRYPTO

DRM key management and crypto operations are performed within a hardware backed trusted execution environment.

int SECURITY_LEVEL_HW_SECURE_DECODE

DRM key management, crypto operations and decoding of content are performed within a hardware backed trusted execution environment.

int SECURITY_LEVEL_SW_SECURE_CRYPTO

DRM key management uses software-based whitebox crypto.

int SECURITY_LEVEL_SW_SECURE_DECODE

DRM key management and decoding use software-based whitebox crypto.

int SECURITY_LEVEL_UNKNOWN

The DRM plugin did not report a security level, or an error occurred accessing it

Public constructors

MediaDrm(UUID uuid)

Instantiate a MediaDrm object

Public methods

void close()

Releases resources associated with the current session of MediaDrm.

void closeSession(byte[] sessionId)

Close a session on the MediaDrm object that was previously opened with openSession().

int getConnectedHdcpLevel()

Return the HDCP level negotiated with downstream receivers the device is connected to.

MediaDrm.CryptoSession getCryptoSession(byte[] sessionId, String cipherAlgorithm, String macAlgorithm)

Obtain a CryptoSession object which can be used to encrypt, decrypt, sign and verify messages or data using the session keys established for the session using methods getKeyRequest(byte[], byte[], String, int, HashMap) and provideKeyResponse(byte[], byte[]) using a session key server.

MediaDrm.KeyRequest getKeyRequest(byte[] scope, byte[] init, String mimeType, int keyType, HashMap<StringString> optionalParameters)

A key request/response exchange occurs between the app and a license server to obtain or release keys used to decrypt encrypted content.

int getMaxHdcpLevel()

Return the maximum supported HDCP level.

static int getMaxSecurityLevel()

The maximum security level supported by the device.

int getMaxSessionCount()

Return the maximum number of MediaDrm sessions that may be opened simultaneosly among all MediaDrm instances for the active DRM scheme.

PersistableBundle getMetrics()

Return Metrics data about the current MediaDrm instance.

int getOpenSessionCount()

Return the number of MediaDrm sessions that are currently opened simultaneously among all MediaDrm instances for the active DRM scheme.

byte[] getPropertyByteArray(String propertyName)

Read a MediaDrm byte array property value, given the property name string.

String getPropertyString(String propertyName)

Read a MediaDrm String property value, given the property name string.

MediaDrm.ProvisionRequest getProvisionRequest()

A provision request/response exchange occurs between the app and a provisioning server to retrieve a device certificate.

byte[] getSecureStop(byte[] ssid)

Access a specific secure stop given its secure stop ID.

List<byte[]> getSecureStopIds()

Return a list of all secure stop IDs currently in persistent memory.

List<byte[]> getSecureStops()

Secure stops are a way to enforce limits on the number of concurrent streams per subscriber across devices.

int getSecurityLevel(byte[] sessionId)

Return the current security level of a session.

static boolean isCryptoSchemeSupported(UUID uuid, String mimeType)

Query if the given scheme identified by its UUID is supported on this device, and whether the DRM plugin is able to handle the media container format specified by mimeType.

static boolean isCryptoSchemeSupported(UUID uuid)

Query if the given scheme identified by its UUID is supported on this device.

byte[] openSession()

Open a new session with the MediaDrm object.

byte[] openSession(int level)

Open a new session at a requested security level.

byte[] provideKeyResponse(byte[] scope, byte[] response)

A key response is received from the license server by the app, then it is provided to the MediaDrm instance using provideKeyResponse.

void provideProvisionResponse(byte[] response)

After a provision response is received by the app, it is provided to the MediaDrm instance using this method.

HashMap<StringString> queryKeyStatus(byte[] sessionId)

Request an informative description of the key status for the session.

void release()

This method was deprecated in API level 28. replaced by close().

void releaseAllSecureStops()

This method was deprecated in API level 28. Remove all secure stops using removeAllSecureStops() instead.

void releaseSecureStops(byte[] ssRelease)

Process the secure stop server response message ssRelease.

void removeAllSecureStops()

Remove all secure stops without requiring a secure stop release message from the license server.

void removeKeys(byte[] sessionId)

Remove the current keys from a session.

void removeSecureStop(byte[] ssid)

Remove a specific secure stop without requiring a secure stop release message from the license server.

void restoreKeys(byte[] sessionId, byte[] keySetId)

Restore persisted offline keys into a new session.

void setOnEventListener(MediaDrm.OnEventListener listener)

Register a callback to be invoked when an event occurs

void setOnExpirationUpdateListener(MediaDrm.OnExpirationUpdateListener listener, Handler handler)

Register a callback to be invoked when a session expiration update occurs.

void setOnKeyStatusChangeListener(MediaDrm.OnKeyStatusChangeListener listener, Handler handler)

Register a callback to be invoked when the state of keys in a session change, e.g.

void setPropertyByteArray(String propertyName, byte[] value)

Set a MediaDrm byte array property value, given the property name string and new value for the property.

void setPropertyString(String propertyName, String value)

Set a MediaDrm String property value, given the property name string and new value for the property.

Protected methods

void finalize()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

Inherited methods

Constants

EVENT_KEY_EXPIRED

added in API level 18
public static final int EVENT_KEY_EXPIRED

This constant was deprecated in API level 26.
Use MediaDrm.OnKeyStatusChangeListener.onKeyStatusChange(MediaDrm, byte[], List, boolean) and check for MediaDrm.KeyStatus.STATUS_EXPIRED in the MediaDrm.KeyStatus instead.

This event type indicates that the licensed usage duration for keys in a session has expired. The keys are no longer valid.

Constant Value: 3 (0x00000003)

EVENT_KEY_REQUIRED

added in API level 18
public static final int EVENT_KEY_REQUIRED

This event type indicates that the app needs to request keys from a license server. The request message data is obtained using getKeyRequest(byte[], byte[], String, int, HashMap).

Constant Value: 2 (0x00000002)

EVENT_PROVISION_REQUIRED

added in API level 18
public static final int EVENT_PROVISION_REQUIRED

This constant was deprecated in API level 23.
Handle provisioning via NotProvisionedException instead.

This event type indicates that the app needs to request a certificate from the provisioning server. The request message data is obtained using getProvisionRequest()

Constant Value: 1 (0x00000001)

EVENT_SESSION_RECLAIMED

added in API level 23
public static final int EVENT_SESSION_RECLAIMED

This event indicates that a session opened by the app has been reclaimed by the resource manager.

Constant Value: 5 (0x00000005)

EVENT_VENDOR_DEFINED

added in API level 18
public static final int EVENT_VENDOR_DEFINED

This event may indicate some specific vendor-defined condition, see your DRM provider documentation for details

Constant Value: 4 (0x00000004)

HDCP_LEVEL_UNKNOWN

added in API level 28
public static final int HDCP_LEVEL_UNKNOWN

The DRM plugin did not report an HDCP level, or an error occurred accessing it

Constant Value: 0 (0x00000000)

HDCP_NONE

added in API level 28
public static final int HDCP_NONE

HDCP is not supported on this device, content is unprotected

Constant Value: 1 (0x00000001)

HDCP_NO_DIGITAL_OUTPUT

added in API level 28
public static final int HDCP_NO_DIGITAL_OUTPUT

No digital output, implicitly secure

Constant Value: 2147483647 (0x7fffffff)

HDCP_V1

added in API level 28
public static final int HDCP_V1

HDCP version 1.0

Constant Value: 2 (0x00000002)

HDCP_V2

added in API level 28
public static final int HDCP_V2

HDCP version 2.0 Type 1.

Constant Value: 3 (0x00000003)

HDCP_V2_1

added in API level 28
public static final int HDCP_V2_1

HDCP version 2.1 Type 1.

Constant Value: 4 (0x00000004)

HDCP_V2_2

added in API level 28
public static final int HDCP_V2_2

HDCP version 2.2 Type 1.

Constant Value: 5 (0x00000005)

KEY_TYPE_OFFLINE

added in API level 18
public static final int KEY_TYPE_OFFLINE

This key request type specifies that the keys will be for offline use, they will be saved to the device for use when the device is not connected to a network.

Constant Value: 2 (0x00000002)

KEY_TYPE_RELEASE

added in API level 18
public static final int KEY_TYPE_RELEASE

This key request type specifies that previously saved offline keys should be released.

Constant Value: 3 (0x00000003)

KEY_TYPE_STREAMING

added in API level 18
public static final int KEY_TYPE_STREAMING

This key request type species that the keys will be for online use, they will not be saved to the device for subsequent use when the device is not connected to a network.

Constant Value: 1 (0x00000001)

PROPERTY_ALGORITHMS

added in API level 18
public static final String PROPERTY_ALGORITHMS

String property name: a comma-separated list of cipher and mac algorithms supported by CryptoSession. The list may be empty if the DRM plugin does not support CryptoSession operations.

Constant Value: "algorithms"

PROPERTY_DESCRIPTION

added in API level 18
public static final String PROPERTY_DESCRIPTION

String property name: describes the DRM plugin

Constant Value: "description"

PROPERTY_DEVICE_UNIQUE_ID

added in API level 18
public static final String PROPERTY_DEVICE_UNIQUE_ID

Byte array property name: the device unique identifier is established during device provisioning and provides a means of uniquely identifying each device.

Constant Value: "deviceUniqueId"

PROPERTY_VENDOR

added in API level 18
public static final String PROPERTY_VENDOR

String property name: identifies the maker of the DRM plugin

Constant Value: "vendor"

PROPERTY_VERSION

added in API level 18
public static final String PROPERTY_VERSION

String property name: identifies the version of the DRM plugin

Constant Value: "version"

SECURITY_LEVEL_HW_SECURE_ALL

added in API level 28
public static final int SECURITY_LEVEL_HW_SECURE_ALL

DRM key management, crypto operations, decoding of content and all handling of the media (compressed and uncompressed) is handled within a hardware backed trusted execution environment.

Constant Value: 5 (0x00000005)

SECURITY_LEVEL_HW_SECURE_CRYPTO

added in API level 28
public static final int SECURITY_LEVEL_HW_SECURE_CRYPTO

DRM key management and crypto operations are performed within a hardware backed trusted execution environment.

Constant Value: 3 (0x00000003)

SECURITY_LEVEL_HW_SECURE_DECODE

added in API level 28
public static final int SECURITY_LEVEL_HW_SECURE_DECODE

DRM key management, crypto operations and decoding of content are performed within a hardware backed trusted execution environment.

Constant Value: 4 (0x00000004)

SECURITY_LEVEL_SW_SECURE_CRYPTO

added in API level 28
public static final int SECURITY_LEVEL_SW_SECURE_CRYPTO

DRM key management uses software-based whitebox crypto.

Constant Value: 1 (0x00000001)

SECURITY_LEVEL_SW_SECURE_DECODE

added in API level 28
public static final int SECURITY_LEVEL_SW_SECURE_DECODE

DRM key management and decoding use software-based whitebox crypto.

Constant Value: 2 (0x00000002)

SECURITY_LEVEL_UNKNOWN

added in API level 28
public static final int SECURITY_LEVEL_UNKNOWN

The DRM plugin did not report a security level, or an error occurred accessing it

Constant Value: 0 (0x00000000)

Public constructors

MediaDrm

added in API level 18
public MediaDrm (UUID uuid)

Instantiate a MediaDrm object

Parameters
uuid UUID: The UUID of the crypto scheme.

This value must never be null.

Throws
UnsupportedSchemeException if the device does not support the specified scheme UUID

Public methods

close

added in API level 28
public void close ()

Releases resources associated with the current session of MediaDrm. It is considered good practice to call this method when the MediaDrm object is no longer needed in your application. After this method is called, MediaDrm is no longer usable since it has lost all of its required resource. This method was added in API 28. In API versions 18 through 27, release() should be called instead. There is no need to do anything for API versions prior to 18.

closeSession

added in API level 18
public void closeSession (byte[] sessionId)

Close a session on the MediaDrm object that was previously opened with openSession().

Parameters
sessionId byte

This value must never be null.

getConnectedHdcpLevel

added in API level 28
public int getConnectedHdcpLevel ()

Return the HDCP level negotiated with downstream receivers the device is connected to. If multiple HDCP-capable displays are simultaneously connected to separate interfaces, this method returns the lowest negotiated level of all interfaces.

This method should only be used for informational purposes, not for enforcing compliance with HDCP requirements. Trusted enforcement of HDCP policies must be handled by the DRM system.

Returns
int one of HDCP_LEVEL_UNKNOWN, HDCP_NONE, HDCP_V1, HDCP_V2, HDCP_V2_1, HDCP_V2_2 or HDCP_NO_DIGITAL_OUTPUT.

getCryptoSession

added in API level 18
public MediaDrm.CryptoSession getCryptoSession (byte[] sessionId, 
                String cipherAlgorithm, 
                String macAlgorithm)

Obtain a CryptoSession object which can be used to encrypt, decrypt, sign and verify messages or data using the session keys established for the session using methods getKeyRequest(byte[], byte[], String, int, HashMap) and provideKeyResponse(byte[], byte[]) using a session key server.

Parameters
sessionId byte: the session ID for the session containing keys to be used for encrypt, decrypt, sign and/or verify

This value must never be null.

cipherAlgorithm String: the algorithm to use for encryption and decryption ciphers. The algorithm string conforms to JCA Standard Names for Cipher Transforms and is case insensitive. For example "AES/CBC/NoPadding".

This value must never be null.

macAlgorithm String: the algorithm to use for sign and verify The algorithm string conforms to JCA Standard Names for Mac Algorithms and is case insensitive. For example "HmacSHA256".

The list of supported algorithms for a DRM plugin can be obtained using the method getPropertyString(String) with the property name "algorithms".

This value must never be null.

Returns
MediaDrm.CryptoSession

getKeyRequest

added in API level 18
public MediaDrm.KeyRequest getKeyRequest (byte[] scope, 
                byte[] init, 
                String mimeType, 
                int keyType, 
                HashMap<StringString> optionalParameters)

A key request/response exchange occurs between the app and a license server to obtain or release keys used to decrypt encrypted content.

getKeyRequest() is used to obtain an opaque key request byte array that is delivered to the license server. The opaque key request byte array is returned in KeyRequest.data. The recommended URL to deliver the key request to is returned in KeyRequest.defaultUrl.

After the app has received the key request response from the server, it should deliver to the response to the MediaDrm instance using the method provideKeyResponse(byte[], byte[]).

Parameters
scope byte: may be a sessionId or a keySetId, depending on the specified keyType. When the keyType is KEY_TYPE_STREAMING or KEY_TYPE_OFFLINE, scope should be set to the sessionId the keys will be provided to. When the keyType is KEY_TYPE_RELEASE, scope should be set to the keySetId of the keys being released. Releasing keys from a device invalidates them for all sessions.

This value must never be null.

init byte: container-specific data, its meaning is interpreted based on the mime type provided in the mimeType parameter. It could contain, for example, the content ID, key ID or other data obtained from the content metadata that is required in generating the key request. May be null when keyType is KEY_TYPE_RELEASE or if the request is a renewal, i.e. not the first key request for the session.

mimeType String: identifies the mime type of the content. May be null if the keyType is KEY_TYPE_RELEASE or if the request is a renewal, i.e. not the first key request for the session.

keyType int: specifes the type of the request. The request may be to acquire keys for streaming or offline content, or to release previously acquired keys, which are identified by a keySetId.

optionalParameters HashMap: are included in the key request message to allow a client application to provide additional message parameters to the server. This may be null if no additional parameters are to be sent.

Returns
MediaDrm.KeyRequest

This value will never be null.

Throws
NotProvisionedException if reprovisioning is needed, due to a problem with the certifcate

getMaxHdcpLevel

added in API level 28
public int getMaxHdcpLevel ()

Return the maximum supported HDCP level. The maximum HDCP level is a constant for a given device, it does not depend on downstream receivers that may be connected. If multiple HDCP-capable interfaces are present, it indicates the highest of the maximum HDCP levels of all interfaces.

Returns
int one of HDCP_LEVEL_UNKNOWN, HDCP_NONE, HDCP_V1, HDCP_V2, HDCP_V2_1, HDCP_V2_2 or HDCP_NO_DIGITAL_OUTPUT.

getMaxSecurityLevel

added in API level 28
public static int getMaxSecurityLevel ()

The maximum security level supported by the device. This is the default security level when a session is opened.

Returns
int

getMaxSessionCount

added in API level 28
public int getMaxSessionCount ()

Return the maximum number of MediaDrm sessions that may be opened simultaneosly among all MediaDrm instances for the active DRM scheme. The maximum number of sessions is not affected by any sessions that may have already been opened.

Returns
int maximum sessions.

getMetrics

added in API level 28
public PersistableBundle getMetrics ()

Return Metrics data about the current MediaDrm instance.

Returns
PersistableBundle a PersistableBundle containing the set of attributes and values available for this instance of MediaDrm. The attributes are described in MediaDrm.MetricsConstants. Additional vendor-specific fields may also be present in the return value.

getOpenSessionCount

added in API level 28
public int getOpenSessionCount ()

Return the number of MediaDrm sessions that are currently opened simultaneously among all MediaDrm instances for the active DRM scheme.

Returns
int the number of open sessions.

getPropertyByteArray

added in API level 18
public byte[] getPropertyByteArray (String propertyName)

Read a MediaDrm byte array property value, given the property name string.

Standard fields names are PROPERTY_DEVICE_UNIQUE_ID

Parameters
propertyName String

Value is PROPERTY_DEVICE_UNIQUE_ID.

Returns
byte[]

This value will never be null.

getPropertyString

added in API level 18
public String getPropertyString (String propertyName)

Read a MediaDrm String property value, given the property name string.

Standard fields names are: PROPERTY_VENDOR, PROPERTY_VERSION, PROPERTY_DESCRIPTION, PROPERTY_ALGORITHMS

Parameters
propertyName String

This value must never be null.

Value is PROPERTY_VENDOR, PROPERTY_VERSION, PROPERTY_DESCRIPTION or PROPERTY_ALGORITHMS.

Returns
String

This value will never be null.

getProvisionRequest

added in API level 18
public MediaDrm.ProvisionRequest getProvisionRequest ()

A provision request/response exchange occurs between the app and a provisioning server to retrieve a device certificate. If provisionining is required, the EVENT_PROVISION_REQUIRED event will be sent to the event handler. getProvisionRequest is used to obtain the opaque provision request byte array that should be delivered to the provisioning server. The provision request byte array is returned in ProvisionRequest.data. The recommended URL to deliver the provision request to is returned in ProvisionRequest.defaultUrl.

Returns
MediaDrm.ProvisionRequest

This value will never be null.

getSecureStop

added in API level 22
public byte[] getSecureStop (byte[] ssid)

Access a specific secure stop given its secure stop ID. Each secure stop has a unique ID.

Parameters
ssid byte: the ID of the secure stop to return

This value must never be null.

Returns
byte[] the secure stop identified by ssid

This value will never be null.

getSecureStopIds

added in API level 28
public List<byte[]> getSecureStopIds ()

Return a list of all secure stop IDs currently in persistent memory. The secure stop ID can be used to access or remove the corresponding secure stop.

Returns
List<byte[]> a list of secure stop IDs

This value will never be null.

getSecureStops

added in API level 18
public List<byte[]> getSecureStops ()

Secure stops are a way to enforce limits on the number of concurrent streams per subscriber across devices. They provide secure monitoring of the lifetime of content decryption keys in MediaDrm sessions.

A secure stop is written to secure persistent memory when keys are loaded into a MediaDrm session. The secure stop state indicates that the keys are available for use. When playback completes and the keys are removed or the session is destroyed, the secure stop state is updated to indicate that keys are no longer usable.

After playback, the app can query the secure stop and send it in a message to the license server confirming that the keys are no longer active. The license server returns a secure stop release response message to the app which then deletes the secure stop from persistent memory using releaseSecureStops(byte[]).

Each secure stop has a unique ID that can be used to identify it during enumeration, access and removal.

Returns
List<byte[]> a list of all secure stops from secure persistent memory

This value will never be null.

getSecurityLevel

added in API level 28
public int getSecurityLevel (byte[] sessionId)

Return the current security level of a session. A session has an initial security level determined by the robustness of the DRM system's implementation on the device. The security level may be changed at the time a session is opened using openSession().

Parameters
sessionId byte: the session to query.

This value must never be null.

Returns
int one of SECURITY_LEVEL_UNKNOWN, SECURITY_LEVEL_SW_SECURE_CRYPTO, SECURITY_LEVEL_SW_SECURE_DECODE, SECURITY_LEVEL_HW_SECURE_CRYPTO, SECURITY_LEVEL_HW_SECURE_DECODE or SECURITY_LEVEL_HW_SECURE_ALL.

isCryptoSchemeSupported

added in API level 19
public static boolean isCryptoSchemeSupported (UUID uuid, 
                String mimeType)

Query if the given scheme identified by its UUID is supported on this device, and whether the DRM plugin is able to handle the media container format specified by mimeType.

Parameters
uuid UUID: The UUID of the crypto scheme.

This value must never be null.

mimeType String: The MIME type of the media container, e.g. "video/mp4" or "video/webm"

This value must never be null.

Returns
boolean

isCryptoSchemeSupported

added in API level 18
public static boolean isCryptoSchemeSupported (UUID uuid)

Query if the given scheme identified by its UUID is supported on this device.

Parameters
uuid UUID: The UUID of the crypto scheme.

This value must never be null.

Returns
boolean

openSession

added in API level 18
public byte[] openSession ()

Open a new session with the MediaDrm object. A session ID is returned. By default, sessions are opened at the native security level of the device.

Returns
byte[]

This value will never be null.

Throws
NotProvisionedException if provisioning is needed
ResourceBusyException if required resources are in use

openSession

added in API level 28
public byte[] openSession (int level)

Open a new session at a requested security level. The security level represents the robustness of the device's DRM implementation. By default, sessions are opened at the native security level of the device. Overriding the security level is necessary when the decrypted frames need to be manipulated, such as for image compositing. The security level parameter must be lower than the native level. Reducing the security level will typically limit the content to lower resolutions, as determined by the license policy. If the requested level is not supported, the next lower supported security level will be set. The level can be queried using getSecurityLevel(byte[]). A session ID is returned.

Parameters
level int: the new security level, one of SECURITY_LEVEL_SW_SECURE_CRYPTO, SECURITY_LEVEL_SW_SECURE_DECODE, SECURITY_LEVEL_HW_SECURE_CRYPTO, SECURITY_LEVEL_HW_SECURE_DECODE or SECURITY_LEVEL_HW_SECURE_ALL.

Returns
byte[]

This value will never be null.

Throws
NotProvisionedException if provisioning is needed
ResourceBusyException if required resources are in use
IllegalArgumentException if the requested security level is higher than the native level or lower than the lowest supported level or if the device does not support specifying the security level when opening a session

provideKeyResponse

added in API level 18
public byte[] provideKeyResponse (byte[] scope, 
                byte[] response)

A key response is received from the license server by the app, then it is provided to the MediaDrm instance using provideKeyResponse. When the response is for an offline key request, a keySetId is returned that can be used to later restore the keys to a new session with the method restoreKeys(byte[], byte[]). When the response is for a streaming or release request, an empty byte array is returned.

Parameters
scope byte: may be a sessionId or keySetId depending on the type of the response. Scope should be set to the sessionId when the response is for either streaming or offline key requests. Scope should be set to the keySetId when the response is for a release request.

This value must never be null.

response byte: the byte array response from the server

This value must never be null.

Returns
byte[] If the response is for an offline request, the keySetId for the offline keys will be returned. If the response is for a streaming or release request an empty byte array will be returned.

This value may be null.

Throws
NotProvisionedException if the response indicates that reprovisioning is required
DeniedByServerException if the response indicates that the server rejected the request

provideProvisionResponse

added in API level 18
public void provideProvisionResponse (byte[] response)

After a provision response is received by the app, it is provided to the MediaDrm instance using this method.

Parameters
response byte: the opaque provisioning response byte array to provide to the MediaDrm instance.

This value must never be null.

Throws
DeniedByServerException if the response indicates that the server rejected the request

queryKeyStatus

added in API level 18
public HashMap<StringString> queryKeyStatus (byte[] sessionId)

Request an informative description of the key status for the session. The status is in the form of {name, value} pairs. Since DRM license policies vary by vendor, the specific status field names are determined by each DRM vendor. Refer to your DRM provider documentation for definitions of the field names for a particular DRM plugin.

Parameters
sessionId byte: the session ID for the DRM session

This value must never be null.

Returns
HashMap<StringString>

This value will never be null.

release

added in API level 18
public void release ()

This method was deprecated in API level 28.
replaced by close().

releaseAllSecureStops

added in API level 22
public void releaseAllSecureStops ()

This method was deprecated in API level 28.
Remove all secure stops using removeAllSecureStops() instead.

Remove all secure stops without requiring a secure stop release message from the license server.

releaseSecureStops

added in API level 18
public void releaseSecureStops (byte[] ssRelease)

Process the secure stop server response message ssRelease. After authenticating the message, remove the secure stops identified in the response.

Parameters
ssRelease byte: the server response indicating which secure stops to release

This value must never be null.

removeAllSecureStops

added in API level 28
public void removeAllSecureStops ()

Remove all secure stops without requiring a secure stop release message from the license server. This method was added in API 28. In API versions 18 through 27, releaseAllSecureStops() should be called instead. There is no need to do anything for API versions prior to 18.

removeKeys

added in API level 18
public void removeKeys (byte[] sessionId)

Remove the current keys from a session.

Parameters
sessionId byte: the session ID for the DRM session

This value must never be null.

removeSecureStop

added in API level 28
public void removeSecureStop (byte[] ssid)

Remove a specific secure stop without requiring a secure stop release message from the license server.

Parameters
ssid byte: the ID of the secure stop to remove

This value must never be null.

restoreKeys

added in API level 18
public void restoreKeys (byte[] sessionId, 
                byte[] keySetId)

Restore persisted offline keys into a new session. keySetId identifies the keys to load, obtained from a prior call to provideKeyResponse(byte[], byte[]).

Parameters
sessionId byte: the session ID for the DRM session

This value must never be null.

keySetId byte: identifies the saved key set to restore

This value must never be null.

setOnEventListener

added in API level 18
public void setOnEventListener (MediaDrm.OnEventListener listener)

Register a callback to be invoked when an event occurs

Parameters
listener MediaDrm.OnEventListener: the callback that will be run. Use null to stop receiving event callbacks.

setOnExpirationUpdateListener

added in API level 23
public void setOnExpirationUpdateListener (MediaDrm.OnExpirationUpdateListener listener, 
                Handler handler)

Register a callback to be invoked when a session expiration update occurs. The app's OnExpirationUpdateListener will be notified when the expiration time of the keys in the session have changed.

Parameters
listener MediaDrm.OnExpirationUpdateListener: the callback that will be run, or null to unregister the previously registered callback.

handler Handler: the handler on which the listener should be invoked, or null if the listener should be invoked on the calling thread's looper.

setOnKeyStatusChangeListener

added in API level 23
public void setOnKeyStatusChangeListener (MediaDrm.OnKeyStatusChangeListener listener, 
                Handler handler)

Register a callback to be invoked when the state of keys in a session change, e.g. when a license update occurs or when a license expires.

Parameters
listener MediaDrm.OnKeyStatusChangeListener: the callback that will be run when key status changes, or null to unregister the previously registered callback.

handler Handler: the handler on which the listener should be invoked, or null if the listener should be invoked on the calling thread's looper.

setPropertyByteArray

added in API level 18
public void setPropertyByteArray (String propertyName, 
                byte[] value)

Set a MediaDrm byte array property value, given the property name string and new value for the property.

Parameters
propertyName String

This value must never be null.

Value is PROPERTY_DEVICE_UNIQUE_ID.

value byte

This value must never be null.

setPropertyString

added in API level 18
public void setPropertyString (String propertyName, 
                String value)

Set a MediaDrm String property value, given the property name string and new value for the property.

Parameters
propertyName String

This value must never be null.

Value is PROPERTY_VENDOR, PROPERTY_VERSION, PROPERTY_DESCRIPTION or PROPERTY_ALGORITHMS.

value String

This value must never be null.

Protected methods

finalize

added in API level 18
protected void finalize ()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

The general contract of finalize is that it is invoked if and when the Java™ virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

Throws
Throwable