Skip to content

Most visited

Recently visited

navigation

NdkMediaDrm.h File Reference

NdkMediaDrm.h File Reference

Data Structures

struct  AMediaDrmByteArray
 
struct  AMediaDrmKeyValuePair
 

Typedefs

typedef struct AMediaDrm AMediaDrm
 
typedef AMediaDrmByteArray AMediaDrmSessionId
 
typedef AMediaDrmByteArray AMediaDrmScope
 
typedef AMediaDrmByteArray AMediaDrmKeySetId
 
typedef AMediaDrmByteArray AMediaDrmSecureStop
 
typedef enum AMediaDrmEventType AMediaDrmEventType
 
typedef void(* AMediaDrmEventListener) (AMediaDrm *, const AMediaDrmSessionId *sessionId, AMediaDrmEventType eventType, int extra, const uint8_t *data, size_t dataSize)
 
typedef enum AMediaDrmKeyType AMediaDrmKeyType
 
typedef struct AMediaDrmKeyValuePair AMediaDrmKeyValue
 

Enumerations

enum  AMediaDrmEventType { EVENT_PROVISION_REQUIRED = 1, EVENT_KEY_REQUIRED = 2, EVENT_KEY_EXPIRED = 3, EVENT_VENDOR_DEFINED = 4 }
 
enum  AMediaDrmKeyType { KEY_TYPE_STREAMING = 1, KEY_TYPE_OFFLINE = 2, KEY_TYPE_RELEASE = 3 }
 

Functions

bool AMediaDrm_isCryptoSchemeSupported (const uint8_t *uuid, const char *mimeType)
 
AMediaDrmAMediaDrm_createByUUID (const uint8_t *uuid)
 
void AMediaDrm_release (AMediaDrm *)
 
media_status_t AMediaDrm_setOnEventListener (AMediaDrm *, AMediaDrmEventListener listener)
 
media_status_t AMediaDrm_openSession (AMediaDrm *, AMediaDrmSessionId *sessionId)
 
media_status_t AMediaDrm_closeSession (AMediaDrm *, const AMediaDrmSessionId *sessionId)
 
media_status_t AMediaDrm_getKeyRequest (AMediaDrm *, const AMediaDrmScope *scope, const uint8_t *init, size_t initSize, const char *mimeType, AMediaDrmKeyType keyType, const AMediaDrmKeyValue *optionalParameters, size_t numOptionalParameters, const uint8_t **keyRequest, size_t *keyRequestSize)
 
media_status_t AMediaDrm_provideKeyResponse (AMediaDrm *, const AMediaDrmScope *scope, const uint8_t *response, size_t responseSize, AMediaDrmKeySetId *keySetId)
 
media_status_t AMediaDrm_restoreKeys (AMediaDrm *, const AMediaDrmSessionId *sessionId, const AMediaDrmKeySetId *keySetId)
 
media_status_t AMediaDrm_removeKeys (AMediaDrm *, const AMediaDrmSessionId *keySetId)
 
media_status_t AMediaDrm_queryKeyStatus (AMediaDrm *, const AMediaDrmSessionId *sessionId, AMediaDrmKeyValue *keyValuePairs, size_t *numPairs)
 
media_status_t AMediaDrm_getProvisionRequest (AMediaDrm *, const uint8_t **provisionRequest, size_t *provisionRequestSize, const char **serverUrl)
 
media_status_t AMediaDrm_provideProvisionResponse (AMediaDrm *, const uint8_t *response, size_t responseSize)
 
media_status_t AMediaDrm_getSecureStops (AMediaDrm *, AMediaDrmSecureStop *secureStops, size_t *numSecureStops)
 
media_status_t AMediaDrm_releaseSecureStops (AMediaDrm *, const AMediaDrmSecureStop *ssRelease)
 
media_status_t AMediaDrm_getPropertyString (AMediaDrm *, const char *propertyName, const char **propertyValue)
 
media_status_t AMediaDrm_getPropertyByteArray (AMediaDrm *, const char *propertyName, AMediaDrmByteArray *propertyValue)
 
media_status_t AMediaDrm_setPropertyString (AMediaDrm *, const char *propertyName, const char *value)
 
media_status_t AMediaDrm_setPropertyByteArray (AMediaDrm *, const char *propertyName, const uint8_t *value, size_t valueSize)
 
media_status_t AMediaDrm_encrypt (AMediaDrm *, const AMediaDrmSessionId *sessionId, const char *cipherAlgorithm, uint8_t *keyId, uint8_t *iv, const uint8_t *input, uint8_t *output, size_t dataSize)
 
media_status_t AMediaDrm_decrypt (AMediaDrm *, const AMediaDrmSessionId *sessionId, const char *cipherAlgorithm, uint8_t *keyId, uint8_t *iv, const uint8_t *input, uint8_t *output, size_t dataSize)
 
media_status_t AMediaDrm_sign (AMediaDrm *, const AMediaDrmSessionId *sessionId, const char *macAlgorithm, uint8_t *keyId, uint8_t *message, size_t messageSize, uint8_t *signature, size_t *signatureSize)
 
media_status_t AMediaDrm_verify (AMediaDrm *, const AMediaDrmSessionId *sessionId, const char *macAlgorithm, uint8_t *keyId, const uint8_t *message, size_t messageSize, const uint8_t *signature, size_t signatureSize)
 

Typedef Documentation

§ AMediaDrm

typedef struct AMediaDrm AMediaDrm

§ AMediaDrmEventListener

typedef void(* AMediaDrmEventListener) (AMediaDrm *, const AMediaDrmSessionId *sessionId, AMediaDrmEventType eventType, int extra, const uint8_t *data, size_t dataSize)

§ AMediaDrmEventType

§ AMediaDrmKeySetId

§ AMediaDrmKeyType

§ AMediaDrmKeyValue

Data type containing {key, value} pair

§ AMediaDrmScope

§ AMediaDrmSecureStop

§ AMediaDrmSessionId

Enumeration Type Documentation

§ AMediaDrmEventType

Enumerator
EVENT_PROVISION_REQUIRED 

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

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

EVENT_KEY_EXPIRED 

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

EVENT_VENDOR_DEFINED 

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

§ AMediaDrmKeyType

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

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.

KEY_TYPE_RELEASE 

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

Function Documentation

§ AMediaDrm_closeSession()

media_status_t AMediaDrm_closeSession ( AMediaDrm ,
const AMediaDrmSessionId sessionId 
)

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

§ AMediaDrm_createByUUID()

AMediaDrm* AMediaDrm_createByUUID ( const uint8_t *  uuid)

Create a MediaDrm instance from a UUID uuid identifies the universal unique ID of the crypto scheme. uuid must be 16 bytes.

§ AMediaDrm_decrypt()

media_status_t AMediaDrm_decrypt ( AMediaDrm ,
const AMediaDrmSessionId sessionId,
const char *  cipherAlgorithm,
uint8_t *  keyId,
uint8_t *  iv,
const uint8_t *  input,
uint8_t *  output,
size_t  dataSize 
)

§ AMediaDrm_encrypt()

media_status_t AMediaDrm_encrypt ( AMediaDrm ,
const AMediaDrmSessionId sessionId,
const char *  cipherAlgorithm,
uint8_t *  keyId,
uint8_t *  iv,
const uint8_t *  input,
uint8_t *  output,
size_t  dataSize 
)

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.

Operators create session key servers that receive session key requests and provide encrypted session keys which can be used for general purpose crypto operations.

Generic encrypt/decrypt/sign/verify methods are based on the established session keys. These keys are exchanged using the getKeyRequest/provideKeyResponse methods.

Applications of this capability include securing various types of purchased or private content, such as applications, books and other media, photos or media delivery protocols.

§ AMediaDrm_getKeyRequest()

media_status_t AMediaDrm_getKeyRequest ( AMediaDrm ,
const AMediaDrmScope scope,
const uint8_t *  init,
size_t  initSize,
const char *  mimeType,
AMediaDrmKeyType  keyType,
const AMediaDrmKeyValue optionalParameters,
size_t  numOptionalParameters,
const uint8_t **  keyRequest,
size_t *  keyRequestSize 
)

A key request/response exchange occurs between the app and a license server to obtain or release keys used to decrypt encrypted content. AMediaDrm_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.

After the app has received the key request response from the server, it should deliver to the response to the DRM engine plugin using the method AMediaDrm_provideKeyResponse.

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

init 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. init may be null when keyType is KEY_TYPE_RELEASE.

initSize is the number of bytes of initData

mimeType identifies the mime type of the content.

keyType 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 are included in the key request message to allow a client application to provide additional message parameters to the server.

numOptionalParameters indicates the number of optional parameters provided by the caller

On exit:

  1. The keyRequest pointer will reference the opaque key request data. It will reside in memory owned by the AMediaDrm object, and will remain accessible until the next call to AMediaDrm_getKeyRequest or until the MediaDrm object is released.
  2. keyRequestSize will be set to the size of the request

returns MEDIADRM_NOT_PROVISIONED_ERROR if reprovisioning is needed, due to a problem with the device certificate.

§ AMediaDrm_getPropertyByteArray()

media_status_t AMediaDrm_getPropertyByteArray ( AMediaDrm ,
const char *  propertyName,
AMediaDrmByteArray propertyValue 
)

Read a DRM engine plugin byte array property value, given the property name string. On return, *propertyValue will be set to point to the property value. The memory that the value resides in is owned by the NDK MediaDrm API and will remain valid until the next call to AMediaDrm_getPropertyByteArray.

§ AMediaDrm_getPropertyString()

media_status_t AMediaDrm_getPropertyString ( AMediaDrm ,
const char *  propertyName,
const char **  propertyValue 
)

Read a DRM engine plugin String property value, given the property name string.

propertyName identifies the property to query On return, propertyValue will be set to point to the property value. The memory that the value resides in is owned by the NDK MediaDrm API and will remain valid until the next call to AMediaDrm_getPropertyString.

§ AMediaDrm_getProvisionRequest()

media_status_t AMediaDrm_getProvisionRequest ( AMediaDrm ,
const uint8_t **  provisionRequest,
size_t *  provisionRequestSize,
const char **  serverUrl 
)

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. On exit:

  1. The provision request data will be referenced by provisionRequest, in memory owned by the AMediaDrm object. It will remain accessible until the next call to getProvisionRequest.
  2. provisionRequestSize will be set to the size of the request data.
  3. serverUrl will reference a NULL terminated string containing the URL the provisioning request should be sent to. It will remain accessible until the next call to getProvisionRequest.

§ AMediaDrm_getSecureStops()

media_status_t AMediaDrm_getSecureStops ( AMediaDrm ,
AMediaDrmSecureStop secureStops,
size_t *  numSecureStops 
)

A means of enforcing limits on the number of concurrent streams per subscriber across devices is provided via SecureStop. This is achieved by securely monitoring the lifetime of sessions.

Information from the server related to the current playback session is written to persistent storage on the device when each MediaCrypto object is created.

In the normal case, playback will be completed, the session destroyed and the Secure Stops will be queried. The app queries secure stops and forwards the secure stop message to the server which verifies the signature and notifies the server side database that the session destruction has been confirmed. The persisted record on the client is only removed after positive confirmation that the server received the message using releaseSecureStops().

numSecureStops is set by the caller to the maximum number of secure stops to return. On exit, *numSecureStops will be set to the number actually returned. If *numSecureStops is too small for the number of secure stops available, MEDIADRM_SHORT_BUFFER will be returned and *numSecureStops will be set to the number required.

§ AMediaDrm_isCryptoSchemeSupported()

bool AMediaDrm_isCryptoSchemeSupported ( const uint8_t *  uuid,
const char *  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.

uuid identifies the universal unique ID of the crypto scheme. uuid must be 16 bytes. mimeType is the MIME type of the media container, e.g. "video/mp4". If mimeType is not known or required, it can be provided as NULL.

§ AMediaDrm_openSession()

media_status_t AMediaDrm_openSession ( AMediaDrm ,
AMediaDrmSessionId sessionId 
)

Open a new session with the MediaDrm object. A session ID is returned.

returns MEDIADRM_NOT_PROVISIONED_ERROR if provisioning is needed returns MEDIADRM_RESOURCE_BUSY_ERROR if required resources are in use

§ AMediaDrm_provideKeyResponse()

media_status_t AMediaDrm_provideKeyResponse ( AMediaDrm ,
const AMediaDrmScope scope,
const uint8_t *  response,
size_t  responseSize,
AMediaDrmKeySetId keySetId 
)

A key response is received from the license server by the app, then it is provided to the DRM engine plugin 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 AMediaDrm_restoreKeys. When the response is for a streaming or release request, a null keySetId is returned.

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

response points to the opaque response from the server responseSize should be set to the size of the response in bytes

§ AMediaDrm_provideProvisionResponse()

media_status_t AMediaDrm_provideProvisionResponse ( AMediaDrm ,
const uint8_t *  response,
size_t  responseSize 
)

After a provision response is received by the app, it is provided to the DRM engine plugin using this method.

response is the opaque provisioning response byte array to provide to the DRM engine plugin. responseSize is the length of the provisioning response in bytes.

returns MEDIADRM_DEVICE_REVOKED_ERROR if the response indicates that the server rejected the request

§ AMediaDrm_queryKeyStatus()

media_status_t AMediaDrm_queryKeyStatus ( AMediaDrm ,
const AMediaDrmSessionId sessionId,
AMediaDrmKeyValue keyValuePairs,
size_t *  numPairs 
)

Request an informative description of the key status for the session. The status is in the form of {key, 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 engine plugin.

On entry, numPairs should be set by the caller to the maximum number of pairs that can be returned (the size of the array). On exit, numPairs will be set to the number of entries written to the array. If the number of {key, value} pairs to be returned is greater than *numPairs, MEDIADRM_SHORT_BUFFER will be returned and numPairs will be set to the number of pairs available.

§ AMediaDrm_release()

void AMediaDrm_release ( AMediaDrm )

Release a MediaDrm object

§ AMediaDrm_releaseSecureStops()

media_status_t AMediaDrm_releaseSecureStops ( AMediaDrm ,
const AMediaDrmSecureStop ssRelease 
)

Process the SecureStop server response message ssRelease. After authenticating the message, remove the SecureStops identified in the response.

ssRelease is the server response indicating which secure stops to release

§ AMediaDrm_removeKeys()

media_status_t AMediaDrm_removeKeys ( AMediaDrm ,
const AMediaDrmSessionId keySetId 
)

Remove the current keys from a session.

keySetId identifies keys to remove

§ AMediaDrm_restoreKeys()

media_status_t AMediaDrm_restoreKeys ( AMediaDrm ,
const AMediaDrmSessionId sessionId,
const AMediaDrmKeySetId keySetId 
)

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

sessionId is the session ID for the DRM session keySetId identifies the saved key set to restore

§ AMediaDrm_setOnEventListener()

media_status_t AMediaDrm_setOnEventListener ( AMediaDrm ,
AMediaDrmEventListener  listener 
)

Register a callback to be invoked when an event occurs

listener is the callback that will be invoked on event

§ AMediaDrm_setPropertyByteArray()

media_status_t AMediaDrm_setPropertyByteArray ( AMediaDrm ,
const char *  propertyName,
const uint8_t *  value,
size_t  valueSize 
)

Set a DRM engine plugin byte array property value.

§ AMediaDrm_setPropertyString()

media_status_t AMediaDrm_setPropertyString ( AMediaDrm ,
const char *  propertyName,
const char *  value 
)

Set a DRM engine plugin String property value.

§ AMediaDrm_sign()

media_status_t AMediaDrm_sign ( AMediaDrm ,
const AMediaDrmSessionId sessionId,
const char *  macAlgorithm,
uint8_t *  keyId,
uint8_t *  message,
size_t  messageSize,
uint8_t *  signature,
size_t *  signatureSize 
)

§ AMediaDrm_verify()

media_status_t AMediaDrm_verify ( AMediaDrm ,
const AMediaDrmSessionId sessionId,
const char *  macAlgorithm,
uint8_t *  keyId,
const uint8_t *  message,
size_t  messageSize,
const uint8_t *  signature,
size_t  signatureSize 
)
This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Follow Google Developers on WeChat

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience. (Dec 2017 Android Platform & Tools Survey)