MediaDrm

EVENT_KEY_EXPIRED

static val EVENT_KEY_EXPIRED: Int

Deprecated: Use OnKeyStatusChangeListener.onKeyStatusChange 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.

Value: 3

EVENT_KEY_REQUIRED

static val EVENT_KEY_REQUIRED: Int

This event type indicates that the app needs to request keys from a license server. The request message data is obtained using getKeyRequest.

Value: 2

EVENT_PROVISION_REQUIRED

static val EVENT_PROVISION_REQUIRED: Int

Deprecated: Handle provisioning via android.media.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

Value: 1

EVENT_SESSION_RECLAIMED

static val EVENT_SESSION_RECLAIMED: Int

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

Value: 5

EVENT_VENDOR_DEFINED

static val EVENT_VENDOR_DEFINED: Int

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

Value: 4

HDCP_LEVEL_UNKNOWN

static val HDCP_LEVEL_UNKNOWN: Int

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

Value: 0

HDCP_NONE

static val HDCP_NONE: Int

HDCP is not supported on this device, content is unprotected

Value: 1

HDCP_NO_DIGITAL_OUTPUT

static val HDCP_NO_DIGITAL_OUTPUT: Int

No digital output, implicitly secure

Value: 2147483647

HDCP_V1

static val HDCP_V1: Int

HDCP version 1.0

Value: 2

HDCP_V2

static val HDCP_V2: Int

HDCP version 2.0 Type 1.

Value: 3

HDCP_V2_1

static val HDCP_V2_1: Int

HDCP version 2.1 Type 1.

Value: 4

HDCP_V2_2

static val HDCP_V2_2: Int

HDCP version 2.2 Type 1.

Value: 5

HDCP_V2_3

static val HDCP_V2_3: Int

HDCP version 2.3 Type 1.

Value: 6

KEY_TYPE_OFFLINE

static val KEY_TYPE_OFFLINE: Int

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.

Value: 2

KEY_TYPE_RELEASE

static val KEY_TYPE_RELEASE: Int

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

Value: 3

KEY_TYPE_STREAMING

static val KEY_TYPE_STREAMING: Int

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.

Value: 1

OFFLINE_LICENSE_STATE_RELEASED

static val OFFLINE_LICENSE_STATE_RELEASED: Int

Offline license is released, the keys have been marked for release using getKeyRequest with KEY_TYPE_RELEASE but the key response has not been received.

Value: 2

OFFLINE_LICENSE_STATE_UNKNOWN

static val OFFLINE_LICENSE_STATE_UNKNOWN: Int

Offline license state is unknown, an error occurred while trying to access it.

Value: 0

OFFLINE_LICENSE_STATE_USABLE

static val OFFLINE_LICENSE_STATE_USABLE: Int

Offline license is usable, the keys may be used for decryption.

Value: 1

PROPERTY_ALGORITHMS

static val PROPERTY_ALGORITHMS: String

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.

Value: "algorithms"

PROPERTY_DESCRIPTION

static val PROPERTY_DESCRIPTION: String

String property name: describes the DRM plugin

Value: "description"

PROPERTY_DEVICE_UNIQUE_ID

static val PROPERTY_DEVICE_UNIQUE_ID: String

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

Value: "deviceUniqueId"

PROPERTY_VENDOR

static val PROPERTY_VENDOR: String

String property name: identifies the maker of the DRM plugin

Value: "vendor"

PROPERTY_VERSION

static val PROPERTY_VERSION: String

String property name: identifies the version of the DRM plugin

Value: "version"

SECURITY_LEVEL_HW_SECURE_ALL

static val SECURITY_LEVEL_HW_SECURE_ALL: Int

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.

Value: 5

SECURITY_LEVEL_HW_SECURE_CRYPTO

static val SECURITY_LEVEL_HW_SECURE_CRYPTO: Int

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

Value: 3

SECURITY_LEVEL_HW_SECURE_DECODE

static val SECURITY_LEVEL_HW_SECURE_DECODE: Int

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

Value: 4

SECURITY_LEVEL_SW_SECURE_CRYPTO

static val SECURITY_LEVEL_SW_SECURE_CRYPTO: Int

DRM key management uses software-based whitebox crypto.

Value: 1

SECURITY_LEVEL_SW_SECURE_DECODE

static val SECURITY_LEVEL_SW_SECURE_DECODE: Int

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

Value: 2

SECURITY_LEVEL_UNKNOWN

static val SECURITY_LEVEL_UNKNOWN: Int

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

Value: 0

MediaDrm

MediaDrm(uuid: UUID)

Instantiate a MediaDrm object

clearOnEventListener

fun clearOnEventListener(): Unit

Clear the OnEventListener.

clearOnExpirationUpdateListener

fun clearOnExpirationUpdateListener(): Unit

Clear the OnExpirationUpdateListener.

clearOnKeyStatusChangeListener

fun clearOnKeyStatusChangeListener(): Unit

Clear the OnKeyStatusChangeListener.

clearOnSessionLostStateListener

fun clearOnSessionLostStateListener(): Unit

Clear the OnSessionLostStateListener.

close

fun close(): Unit

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

fun closeSession(sessionId: ByteArray): Unit

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

getConnectedHdcpLevel

fun getConnectedHdcpLevel(): Int

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.

getCryptoSession

fun getCryptoSession(
    sessionId: ByteArray, 
    cipherAlgorithm: String, 
    macAlgorithm: String
): MediaDrm.CryptoSession!

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 and provideKeyResponse using a session key server.

getKeyRequest

fun getKeyRequest(
    scope: ByteArray, 
    init: ByteArray?, 
    mimeType: String?, 
    keyType: Int, 
    optionalParameters: HashMap<String!, String!>?
): MediaDrm.KeyRequest

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.

getLogMessages

fun getLogMessages(): MutableList<MediaDrm.LogMessage!>

Returns recent LogMessages associated with this MediaDrm instance.

getMaxHdcpLevel

fun getMaxHdcpLevel(): Int

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.

getMaxSecurityLevel

static fun getMaxSecurityLevel(): Int

Returns a value that may be passed as a parameter to openSession(int) requesting that the session be opened at the maximum security level of the device. This security level is only valid for the application running on the physical Android device (e.g. android.content.Context#DEVICE_ID_DEFAULT). While running on a android.companion.virtual.VirtualDevice the maximum supported security level might be different.

getMaxSessionCount

fun getMaxSessionCount(): Int

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.

getMetrics

fun getMetrics(): PersistableBundle!

Return Metrics data about the current MediaDrm instance.

getOfflineLicenseKeySetIds

fun getOfflineLicenseKeySetIds(): MutableList<ByteArray!>

The keys in an offline license allow protected content to be played even if the device is not connected to a network. Offline licenses are stored on the device after a key request/response exchange when the key request KeyType is OFFLINE. Normally each app is responsible for keeping track of the keySetIds it has created. If an app loses the keySetId for any stored licenses that it created, however, it must be able to recover the stored keySetIds so those licenses can be removed when they expire or when the app is uninstalled.

This method returns a list of the keySetIds for all offline licenses. The offline license keySetId may be used to query the status of an offline license with getOfflineLicenseState or remove it with removeOfflineLicense.

getOfflineLicenseState

fun getOfflineLicenseState(keySetId: ByteArray): Int

Request the state of an offline license. An offline license may be usable or inactive. The keys in a usable offline license are available for decryption. When the offline license state is inactive, the keys have been marked for release using getKeyRequest with KEY_TYPE_RELEASE but the key response has not been received. The keys in an inactive offline license are not usable for decryption.

getOpenSessionCount

fun getOpenSessionCount(): Int

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

getPlaybackComponent

fun getPlaybackComponent(sessionId: ByteArray): MediaDrm.PlaybackComponent?

Obtain a PlaybackComponent associated with a DRM session. Call PlaybackComponent.setLogSessionId(LogSessionId) on the returned object to associate a playback session with the DRM session.

getPropertyByteArray

fun getPropertyByteArray(propertyName: String!): ByteArray

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

Standard fields names are PROPERTY_DEVICE_UNIQUE_ID

getPropertyString

fun getPropertyString(propertyName: String): String

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

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

getProvisionRequest

fun getProvisionRequest(): MediaDrm.ProvisionRequest

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.

getSecureStop

fun getSecureStop(ssid: ByteArray): ByteArray

Deprecated: This method is deprecated and may be removed in a future release. Use renewals by calling getKeyRequest to track concurrent playback. See additional information in getSecureStops

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

getSecureStopIds

fun getSecureStopIds(): MutableList<ByteArray!>

Deprecated: This method is deprecated and may be removed in a future release. Use renewals by calling getKeyRequest to track concurrent playback. See additional information in getSecureStops

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.

getSecureStops

fun getSecureStops(): MutableList<ByteArray!>

Deprecated: This method is deprecated and may be removed in a future release. 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. Limits on concurrent streams may also be enforced by periodically renewing licenses. This can be achieved by calling getKeyRequest to initiate a renewal. MediaDrm users should transition away from secure stops to periodic renewals.

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.

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

getSecurityLevel

fun getSecurityLevel(sessionId: ByteArray): Int

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.

getSupportedCryptoSchemes

static fun getSupportedCryptoSchemes(): MutableList<UUID!>

isCryptoSchemeSupported

static fun isCryptoSchemeSupported(uuid: UUID): Boolean

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

isCryptoSchemeSupported

static fun isCryptoSchemeSupported(
    uuid: UUID, 
    mimeType: String
): Boolean

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.

isCryptoSchemeSupported

static fun isCryptoSchemeSupported(
    uuid: UUID, 
    mimeType: String, 
    securityLevel: Int
): Boolean

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 at the requested security level. Calling this method while the application is running on the physical Android device or a android.companion.virtual.VirtualDevice may lead to different results, based on the different DRM capabilities of the devices.

openSession

fun openSession(): ByteArray

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. If the application is currently running on a android.companion.virtual.VirtualDevice the security level will be adjusted accordingly to the maximum supported level for the display.

openSession

fun openSession(level: Int): ByteArray

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. A session ID is returned. If the application is currently running on a android.companion.virtual.VirtualDevice the security level will be adjusted accordingly to the maximum supported level for the display.

provideKeyResponse

fun provideKeyResponse(
    scope: ByteArray, 
    response: ByteArray
): ByteArray?

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. When the response is for a streaming or release request, an empty byte array is returned.

provideProvisionResponse

fun provideProvisionResponse(response: ByteArray): Unit

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

queryKeyStatus

fun queryKeyStatus(sessionId: ByteArray): HashMap<String!, String!>

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.

release

fun release(): Unit

Deprecated: replaced by close().

releaseAllSecureStops

fun releaseAllSecureStops(): Unit

Deprecated: Remove all secure stops using removeAllSecureStops instead.

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

releaseSecureStops

fun releaseSecureStops(ssRelease: ByteArray): Unit

Deprecated: This method is deprecated and may be removed in a future release. Use renewals by calling getKeyRequest to track concurrent playback. See additional information in getSecureStops

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

removeAllSecureStops

fun removeAllSecureStops(): Unit

Deprecated: This method is deprecated and may be removed in a future release. Use renewals by calling getKeyRequest to track concurrent playback. See additional information in getSecureStops

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

fun removeKeys(sessionId: ByteArray): Unit

Remove the current keys from a session.

removeOfflineLicense

fun removeOfflineLicense(keySetId: ByteArray): Unit

Normally offline licenses are released using a key request/response exchange using getKeyRequest where the key type is KEY_TYPE_RELEASE, followed by provideKeyResponse. This allows the server to cryptographically confirm that the license has been removed and then adjust the count of offline licenses allocated to the device.

In some exceptional situations it may be necessary to directly remove offline licenses without notifying the server, which may be performed using this method.

removeSecureStop

fun removeSecureStop(ssid: ByteArray): Unit

Deprecated: This method is deprecated and may be removed in a future release. Use renewals by calling getKeyRequest to track concurrent playback. See additional information in getSecureStops

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

requiresSecureDecoder

fun requiresSecureDecoder(mime: String): Boolean

Query if the crypto scheme requires the use of a secure decoder to decode data of the given mime type at the default security level. The default security level is defined as the highest security level supported on the device.

requiresSecureDecoder

fun requiresSecureDecoder(
    mime: String, 
    level: Int
): Boolean

Query if the crypto scheme requires the use of a secure decoder to decode data of the given mime type at the given security level.

restoreKeys

fun restoreKeys(
    sessionId: ByteArray, 
    keySetId: ByteArray
): Unit

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

setOnEventListener

fun setOnEventListener(listener: MediaDrm.OnEventListener?): Unit

Register a callback to be invoked when an event occurs

setOnEventListener

fun setOnEventListener(
    listener: MediaDrm.OnEventListener?, 
    handler: Handler?
): Unit

Register a callback to be invoked when an event occurs

setOnEventListener

fun setOnEventListener(
    executor: Executor, 
    listener: MediaDrm.OnEventListener
): Unit

Register a callback to be invoked when an event occurs

setOnExpirationUpdateListener

fun setOnExpirationUpdateListener(
    listener: MediaDrm.OnExpirationUpdateListener?, 
    handler: Handler?
): Unit

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.

setOnExpirationUpdateListener

fun setOnExpirationUpdateListener(
    executor: Executor, 
    listener: MediaDrm.OnExpirationUpdateListener
): Unit

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

setOnKeyStatusChangeListener

fun setOnKeyStatusChangeListener(
    listener: MediaDrm.OnKeyStatusChangeListener?, 
    handler: Handler?
): Unit

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.

setOnKeyStatusChangeListener

fun setOnKeyStatusChangeListener(
    executor: Executor, 
    listener: MediaDrm.OnKeyStatusChangeListener
): Unit

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

setOnSessionLostStateListener

fun setOnSessionLostStateListener(
    listener: MediaDrm.OnSessionLostStateListener?, 
    handler: Handler?
): Unit

Register a callback to be invoked when session state has been lost. This event can occur on devices that are not capable of retaining crypto session state across device suspend/resume cycles. When this event occurs, the session must be closed and a new session opened to resume operation.

setOnSessionLostStateListener

fun setOnSessionLostStateListener(
    executor: Executor, 
    listener: MediaDrm.OnSessionLostStateListener?
): Unit

Register a callback to be invoked when session state has been lost.

setPropertyByteArray

fun setPropertyByteArray(
    propertyName: String, 
    value: ByteArray
): Unit

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

setPropertyString

fun setPropertyString(
    propertyName: String, 
    value: String
): Unit

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

finalize

protected fun finalize(): Unit