Package: android.hardware.drm@1.0

IDrmPlugin

interface IDrmPlugin

Ref:frameworks/native/include/media/drm/DrmAPI.h:DrmPlugin

IDrmPlugin is used to interact with a specific drm plugin that was created by IDrm::createPlugin.A drm plugin provides methods for obtaining drm keys that may be used by a codec to decrypt protected video content.

Methods

openSession

openSession ()
generates (Status status, SessionId sessionId)

Open a new session with the DrmPlugin object.A session ID is returned in the sessionId parameter.

Details
Generates
status
the status of the call.The status must be OK or one of the following errors:ERROR_DRM_NOT_PROVISIONED if the device requires provisioning before it can open a session, ERROR_DRM_RESOURCE_BUSY if there are insufficent resources available to open a session, ERROR_DRM_CANNOT_HANDLE, if openSession is not supported at the time of the call or ERROR_DRM_INVALID_STATE if the HAL is in a state where a session cannot be opened.
sessionId
the session ID for the newly opened session

closeSession

closeSession (SessionId sessionId)
generates (Status status)

Close a session on the DrmPlugin object

Details
Parameters
sessionId
the session id the call applies to
Generates
status
the status of the call.The status must be OK or one of the following errors:ERROR_DRM_SESSION_NOT_OPENED if the session is not opened, BAD_VALUE if the sessionId is invalid or ERROR_DRM_INVALID_STATE if the HAL is in a state where the session cannot be closed.

getKeyRequest

getKeyRequest (vec<uint8_t> scope, vec<uint8_t> initData, string mimeType, KeyType keyType, KeyedVector optionalParameters)
generates (Status status, vec<uint8_t> request, KeyRequestType requestType, string defaultUrl)

A key request/response exchange occurs between the app and a License Server to obtain the keys required to decrypt the content.getKeyRequest() is used to obtain an opaque key request blob that is delivered to the license server.

Details
Parameters
scope
may be a sessionId or a keySetId, depending on the specified keyType.When the keyType is OFFLINE or STREAMING, scope should be set to the sessionId the keys will be provided to.When the keyType is RELEASE, scope should be set to the keySetId of the keys being released.
initData
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 to generate the key request.initData may be empty when keyType is RELEASE.
mimeType
identifies the mime type of the content
keyType
specifies if the keys are to be used for streaming, offline or a release
optionalParameters
included in the key request message to allow a client application to provide additional message parameters to the server.
Generates
status
the status of the call.The status must be OK or one of the following errors:ERROR_DRM_SESSION_NOT_OPENED if the session is not opened, ERROR_DRM_NOT_PROVISIONED if the device requires provisioning before it can generate a key request, ERROR_DRM_CANNOT_HANDLE if getKeyRequest is not supported at the time of the call, BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE if the HAL is in a state where a key request cannot be generated.
request
if successful, the opaque key request blob is returned
requestType
indicates type information about the returned request.The type may be one of INITIAL, RENEWAL or RELEASE.An INITIAL request is the first key request for a license.RENEWAL is a subsequent key request used to refresh the keys in a license.RELEASE corresponds to a keyType of RELEASE, which indicates keys are being released.
defaultUrl
the URL that the request may be sent to, if provided by the drm HAL.The app may choose to override this URL.

provideKeyResponse

provideKeyResponse (vec<uint8_t> scope, vec<uint8_t> response)
generates (Status status, vec<uint8_t> keySetId)

After a key response is received by the app, it is provided to the Drm plugin using provideKeyResponse.

Details
Parameters
scope
may be a sessionId or a 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
the response from the key server that is being provided to the drm HAL.
Generates
status
the status of the call.The status must be OK or one of the following errors:ERROR_DRM_SESSION_NOT_OPENED if the session is not opened, ERROR_DRM_NOT_PROVISIONED if the device requires provisioning before it can handle the key response, ERROR_DRM_DEVICE_REVOKED if the device has been disabled by the license policy, ERROR_DRM_CANNOT_HANDLE if provideKeyResponse is not supported at the time of the call, BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE if the HAL is in a state where a key response cannot be handled.
keySetId
when the response is for an offline key request, a keySetId is returned in the keySetId vector parameter 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, no keySetId is returned.

removeKeys

removeKeys (SessionId sessionId)
generates (Status status)

Remove the current keys from a session

Details
Parameters
sessionId
the session id the call applies to
Generates
status
the status of the call.The status must be OK or one of the following errors:ERROR_DRM_SESSION_NOT_OPENED if the session is not opened, BAD_VALUE if the sessionId is invalid or ERROR_DRM_INVALID_STATE if the HAL is in a state where the keys cannot be removed.

restoreKeys

restoreKeys (SessionId sessionId, vec<uint8_t> keySetId)
generates (Status status)

Restore persisted offline keys into a new session

Details
Parameters
sessionId
the session id the call applies to
keySetId
identifies the keys to load, obtained from a prior call to provideKeyResponse().
Generates
status
the status of the call.The status must be OK or one of the following errors:ERROR_DRM_SESSION_NOT_OPENED if the session is not opened, BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE if the HAL is in a state where keys cannot be restored.

queryKeyStatus

queryKeyStatus (SessionId sessionId)
generates (Status status, KeyedVector infoList)

Request an informative description of the license 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 scheme.

Details
Parameters
sessionId
the session id the call applies to
Generates
status
the status of the call.The status must be OK or one of the following errors:ERROR_DRM_SESSION_NOT_OPENED if the session is not opened, BAD_VALUE if the sessionId is invalid or ERROR_DRM_INVALID_STATE if the HAL is in a state where key status cannot be queried.
infoList
a list of name value pairs describing the license

getProvisionRequest

getProvisionRequest (string certificateType, string certificateAuthority)
generates (Status status, vec<uint8_t> request, string defaultUrl)

A provision request/response exchange occurs between the app and a provisioning server to retrieve a device certificate.getProvisionRequest is used to obtain an opaque provisioning request blob that is delivered to the provisioning server.

Details
Parameters
certificateType
the type of certificate requested, e.g."X.509"
certificateAuthority
identifies the certificate authority.A certificate authority(CA)is an entity which issues digital certificates for use by other parties.It is an example of a trusted third party.
Generates
status
the status of the call.The status must be OK or one of the following errors:ERROR_DRM_CANNOT_HANDLE if the drm scheme does not require provisioning or ERROR_DRM_INVALID_STATE if the HAL is in a state where the provision request cannot be generated.
request
if successful the opaque certificate request blob is returned
defaultUrl
URL that the provisioning request should be sent to, if known by the HAL implementation.If the HAL implementation does not provide a defaultUrl, the returned string must be empty.

provideProvisionResponse

provideProvisionResponse (vec<uint8_t> response)
generates (Status status, vec<uint8_t> certificate, vec<uint8_t> wrappedKey)

After a provision response is received by the app from a provisioning server, it is provided to the Drm HAL using provideProvisionResponse.The HAL implementation must receive the provision request and store the provisioned credentials.

Details
Parameters
response
the opaque provisioning response received by the app from a provisioning server.
Generates
status
the status of the call.The status must be OK or one of the following errors:ERROR_DRM_DEVICE_REVOKED if the device has been disabled by the license policy, BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE if the HAL is in a state where the provision response cannot be handled.
certificate
the public certificate resulting from the provisioning operation, if any.An empty vector indicates that no certificate was returned.
wrappedKey
an opaque object containing encrypted private key material to be used by signRSA when computing an RSA signature on a message, see the signRSA method.

getSecureStops

getSecureStops ()
generates (Status status, vec<SecureStop> secureStops)

Get all secure stops on the device

Details
Generates
status
the status of the call.The status must be OK or ERROR_DRM_INVALID_STATE if the HAL is in a state where the secure stops cannot be returned.
secureStops
a list of the secure stop opaque objects

getSecureStop

getSecureStop (SecureStopId secureStopId)
generates (Status status, SecureStop secureStop)

Get all secure stops by secure stop ID

Details
Parameters
secureStopId
the ID of the secure stop to return.The secure stop ID is delivered by the key server as part of the key response and must also be known by the app.
Generates
status
the status of the call.The status must be OK or one of the following errors:BAD_VALUE if the secureStopId is invalid or ERROR_DRM_INVALID_STATE if the HAL is in a state where the secure stop cannot be returned.
secureStop
the secure stop opaque object

releaseAllSecureStops

releaseAllSecureStops ()
generates (Status status)

Release all secure stops on the device

Details
Generates
status
the status of the call.The status must be OK or ERROR_DRM_INVALID_STATE if the HAL is in a state where the secure stops cannot be released.

releaseSecureStop

releaseSecureStop (vec<uint8_t> secureStopId)
generates (Status status)

Release a secure stop by secure stop ID

Details
Parameters
secureStopId
the ID of the secure stop to release.The secure stop ID is delivered by the key server as part of the key response and must also be known by the app.
Generates
status
the status of the call.The status must be OK or one of the following errors:BAD_VALUE if the secureStopId is invalid or ERROR_DRM_INVALID_STATE if the HAL is in a state where the secure stop cannot be released.

getPropertyString

getPropertyString (string propertyName)
generates (Status status, string value)

Read a string property value given the property name.

Details
Parameters
propertyName
the name of the property
Generates
status
the status of the call.The status must be OK or one of the following errors:BAD_VALUE if the property name is invalid, ERROR_DRM_CANNOT_HANDLE if the property is not supported, or ERROR_DRM_INVALID_STATE if the HAL is in a state where the property cannot be obtained.
value
the property value string

getPropertyByteArray

getPropertyByteArray (string propertyName)
generates (Status status, vec<uint8_t> value)

Read a byte array property value given the property name.

Details
Parameters
propertyName
the name of the property
Generates
status
the status of the call.The status must be OK or one of the following errors:BAD_VALUE if the property name is invalid, ERROR_DRM_CANNOT_HANDLE if the property is not supported, or ERROR_DRM_INVALID_STATE if the HAL is in a state where the property cannot be obtained.
value
the property value byte array

setPropertyString

setPropertyString (string propertyName, string value)
generates (Status status)

Write a property string value given the property name

Details
Parameters
propertyName
the name of the property
value
the value to write
Generates
status
the status of the call.The status must be OK or one of the following errors:BAD_VALUE if the property name is invalid, ERROR_DRM_CANNOT_HANDLE if the property is not supported, or ERROR_DRM_INVALID_STATE if the HAL is in a state where the property cannot be set.

setPropertyByteArray

setPropertyByteArray (string propertyName, vec<uint8_t> value)
generates (Status status)

Write a property byte array value given the property name

Details
Parameters
propertyName
the name of the property
value
the value to write
Generates
status
the status of the call.The status must be OK or one of the following errors:BAD_VALUE if the property name is invalid, ERROR_DRM_CANNOT_HANDLE if the property is not supported, or ERROR_DRM_INVALID_STATE if the HAL is in a state where the property cannot be set.

setCipherAlgorithm

setCipherAlgorithm (SessionId sessionId, string algorithm)
generates (Status status)

Set the cipher algorithm to be used for the specified session.

Details
Parameters
sessionId
the session id the call applies to
algorithm
the algorithm to use.The string conforms to JCA Standard Names for Cipher Transforms and is case insensitive.An example algorithm is "AES/CBC/PKCS5Padding".
Generates
status
the status of the call.The status must be OK or one of the following errors:ERROR_DRM_SESSION_NOT_OPENED if the session is not opened, BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE if the HAL is in a state where the algorithm cannot be set.

setMacAlgorithm

setMacAlgorithm (SessionId sessionId, string algorithm)
generates (Status status)

Set the MAC algorithm to be used for computing hashes in a session.

Details
Parameters
sessionId
the session id the call applies to
algorithm
the algorithm to use.The string conforms to JCA Standard Names for Mac Algorithms and is case insensitive.An example MAC algorithm string is "HmacSHA256".
Generates
status
the status of the call.The status must be OK or one of the following errors:ERROR_DRM_SESSION_NOT_OPENED if the session is not opened, BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE if the HAL is in a state where the algorithm cannot be set.

encrypt

encrypt (SessionId sessionId, vec<uint8_t> keyId, vec<uint8_t> input, vec<uint8_t> iv)
generates (Status status, vec<uint8_t> output)

Encrypt the provided input buffer with the cipher algorithm specified by setCipherAlgorithm and the key selected by keyId, and return the encrypted data.

Details
Parameters
sessionId
the session id the call applies to
keyId
the ID of the key to use for encryption
input
the input data to encrypt
iv
the initialization vector to use for encryption
Generates
status
the status of the call.The status must be OK or one of the following errors:ERROR_DRM_SESSION_NOT_OPENED if the session is not opened, BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE if the HAL is in a state where the encrypt operation cannot be performed.
output
the decrypted data

decrypt

decrypt (SessionId sessionId, vec<uint8_t> keyId, vec<uint8_t> input, vec<uint8_t> iv)
generates (Status status, vec<uint8_t> output)

Decrypt the provided input buffer with the cipher algorithm specified by setCipherAlgorithm and the key selected by keyId, and return the decrypted data.

Details
Parameters
sessionId
the session id the call applies to
keyId
the ID of the key to use for decryption
input
the input data to decrypt
iv
the initialization vector to use for decryption
Generates
status
the status of the call.The status must be OK or one of the following errors:ERROR_DRM_SESSION_NOT_OPENED if the session is not opened, BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE if the HAL is in a state where the decrypt operation cannot be performed.
output
the decrypted data

sign

sign (SessionId sessionId, vec<uint8_t> keyId, vec<uint8_t> message)
generates (Status status, vec<uint8_t> signature)

Compute a signature over the provided message using the mac algorithm specified by setMacAlgorithm and the key selected by keyId and return the signature.

Details
Parameters
sessionId
the session id the call applies to
keyId
the ID of the key to use for decryption
message
the message to compute a signature over
Generates
status
the status of the call.The status must be OK or one of the following errors:ERROR_DRM_SESSION_NOT_OPENED if the session is not opened, BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE if the HAL is in a state where the sign operation cannot be performed.
signature
the computed signature

verify

verify (SessionId sessionId, vec<uint8_t> keyId, vec<uint8_t> message, vec<uint8_t> signature)
generates (Status status, bool match)

Compute a hash of the provided message using the mac algorithm specified by setMacAlgorithm and the key selected by keyId, and compare with the expected result.

Details
Parameters
sessionId
the session id the call applies to
keyId
the ID of the key to use for decryption
message
the message to compute a hash of
signature
the signature to verify
Generates
status
the status of the call.The status must be OK or one of the following errors:ERROR_DRM_SESSION_NOT_OPENED if the session is not opened, BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE if the HAL is in a state where the verify operation cannot be performed.
match
true if the signature is verified positively, false otherwise.

signRSA

signRSA (SessionId sessionId, string algorithm, vec<uint8_t> message, vec<uint8_t> wrappedkey)
generates (Status status, vec<uint8_t> signature)

Compute an RSA signature on the provided message using the specified algorithm.

Details
Parameters
sessionId
the session id the call applies to
algorithm
the signing algorithm, such as "RSASSA-PSS-SHA1" or "PKCS1-BlockType1"
message
the message to compute the signature on
wrappedkey
Generates
status
the status of the call.The status must be OK or one of the following errors:ERROR_DRM_SESSION_NOT_OPENED if the session is not opened, BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE if the HAL is in a state where the signRSA operation cannot be performed.
signature
the RSA signature computed over the message

setListener

setListener (IDrmPluginListener listener)

Set a listener for a drm session.This allows the drm HAL to make asynchronous calls back to the client of IDrm.

Details
Parameters
listener
instance of IDrmPluginListener to receive the events

sendEvent

sendEvent (EventType eventType, SessionId sessionId, vec<uint8_t> data)

Legacy event sending method, it sends events of various types using a single overloaded set of parameters.This form is deprecated.

Details
Parameters
eventType
the type of the event
sessionId
identifies the session the event originated from
data
event-specific data blob

sendExpirationUpdate

sendExpirationUpdate (SessionId sessionId, int64_t expiryTimeInMS)

Send a license expiration update to the listener.The expiration update indicates how long the current license is valid before it needs to be renewed.

Details
Parameters
sessionId
identifies the session the event originated from
expiryTimeInMS
the time when the keys need to be renewed.The time is in milliseconds, relative to the Unix epoch.A time of 0 indicates that the keys never expire.

sendKeysChange

sendKeysChange (SessionId sessionId, vec<KeyStatus> keyStatusList, bool hasNewUsableKey)

Send a keys change event to the listener.The keys change event indicates the status of each key in the session.Keys can be indicated as being usable, expired, outputnotallowed or statuspending.

Details
Parameters
sessionId
identifies the session the event originated from
keyStatusList
indicates the status for each key ID in the session.
hasNewUsableKey
indicates if the event includes at least one key that has become usable.