/**
|
* Copyright (C) 2016 The Android Open Source Project
|
*
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
* you may not use this file except in compliance with the License.
|
* You may obtain a copy of the License at
|
*
|
* http://www.apache.org/licenses/LICENSE-2.0
|
*
|
* Unless required by applicable law or agreed to in writing, software
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
* See the License for the specific language governing permissions and
|
* limitations under the License.
|
*/
|
package android.hardware.drm@1.0;
|
|
import IDrmPluginListener;
|
|
/**
|
* 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.
|
*/
|
interface IDrmPlugin {
|
|
/**
|
* Open a new session with the DrmPlugin object. A session ID is returned
|
* in the sessionId parameter.
|
* @return 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.
|
* @return sessionId the session ID for the newly opened session
|
*/
|
openSession() generates (Status status, SessionId sessionId);
|
|
/**
|
* Close a session on the DrmPlugin object
|
*
|
* @param sessionId the session id the call applies to
|
* @return 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.
|
*/
|
closeSession(SessionId sessionId) generates (Status status);
|
|
/**
|
* 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.
|
*
|
* @param 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.
|
* @param 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.
|
* @param mimeType identifies the mime type of the content
|
* @param keyType specifies if the keys are to be used for streaming,
|
* offline or a release
|
* @param optionalParameters included in the key request message to
|
* allow a client application to provide additional message parameters to
|
* the server.
|
*
|
* @return 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.
|
* @return request if successful, the opaque key request blob is returned
|
* @return 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.
|
* @return defaultUrl the URL that the request may be sent to, if
|
* provided by the drm HAL. The app may choose to override this
|
* URL.
|
*/
|
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);
|
|
/**
|
* After a key response is received by the app, it is provided to the
|
* Drm plugin using provideKeyResponse.
|
*
|
* @param 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.
|
* @param response the response from the key server that is being
|
* provided to the drm HAL.
|
*
|
* @return 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.
|
* @return 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.
|
*/
|
provideKeyResponse(vec<uint8_t> scope, vec<uint8_t> response)
|
generates (Status status, vec<uint8_t> keySetId);
|
|
/**
|
* Remove the current keys from a session
|
*
|
* @param sessionId the session id the call applies to
|
* @return 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.
|
*/
|
removeKeys(SessionId sessionId) generates (Status status);
|
|
/**
|
* Restore persisted offline keys into a new session
|
*
|
* @param sessionId the session id the call applies to
|
* @param keySetId identifies the keys to load, obtained from a prior
|
* call to provideKeyResponse().
|
* @return 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.
|
*/
|
restoreKeys(SessionId sessionId,
|
vec<uint8_t> keySetId) generates (Status status);
|
|
/**
|
* 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.
|
*
|
* @param sessionId the session id the call applies to
|
* @return 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.
|
* @return infoList a list of name value pairs describing the license
|
*/
|
queryKeyStatus(SessionId sessionId)
|
generates (Status status, KeyedVector infoList);
|
|
/**
|
* 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.
|
*
|
* @param certificateType the type of certificate requested, e.g. "X.509"
|
* @param 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.
|
* @return 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.
|
* @return request if successful the opaque certificate request blob
|
* is returned
|
* @return 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.
|
*/
|
getProvisionRequest(string certificateType, string certificateAuthority)
|
generates (Status status, vec<uint8_t> request, string defaultUrl);
|
|
/**
|
* 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.
|
*
|
* @param response the opaque provisioning response received by the
|
* app from a provisioning server.
|
|
* @return 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.
|
* @return certificate the public certificate resulting from the provisioning
|
* operation, if any. An empty vector indicates that no certificate was
|
* returned.
|
* @return 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.
|
*/
|
provideProvisionResponse(vec<uint8_t> response) generates (Status status,
|
vec<uint8_t> certificate, vec<uint8_t> wrappedKey);
|
|
/**
|
* SecureStop is a way of enforcing the concurrent stream limit per
|
* subscriber. It can securely monitor the lifetime of sessions across
|
* device reboots by periodically persisting the session lifetime
|
* status in secure storage.
|
*
|
* A signed version of the sessionID is written to persistent storage on the
|
* device when each MediaCrypto object is created and periodically during
|
* playback. The sessionID is signed by the device private key to prevent
|
* tampering.
|
*
|
* When playback is completed the session is destroyed, and the secure
|
* stops are queried by the app. The app then delivers the secure stop
|
* message to a server which verifies the signature to confirm that the
|
* session and its keys have been removed from the device. The persisted
|
* record on the device is removed after receiving and verifying the
|
* signed response from the server.
|
*/
|
|
/**
|
* Get all secure stops on the device
|
*
|
* @return 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.
|
* @return secureStops a list of the secure stop opaque objects
|
*/
|
getSecureStops() generates
|
(Status status, vec<SecureStop> secureStops);
|
|
/**
|
* Get all secure stops by secure stop ID
|
*
|
* @param 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.
|
*
|
* @return 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.
|
* @return secureStop the secure stop opaque object
|
*/
|
|
getSecureStop(SecureStopId secureStopId)
|
generates (Status status, SecureStop secureStop);
|
|
/**
|
* Release all secure stops on the device
|
*
|
* @return 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.
|
*/
|
releaseAllSecureStops() generates (Status status);
|
|
/**
|
* Release a secure stop by secure stop ID
|
*
|
* @param 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.
|
*
|
* @return 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.
|
*/
|
releaseSecureStop(vec<uint8_t> secureStopId) generates (Status status);
|
|
/**
|
* A drm scheme can have properties that are settable and readable
|
* by an app. There are a few forms of property access methods,
|
* depending on the data type of the property.
|
*
|
* Property values defined by the public API are:
|
* "vendor" [string] identifies the maker of the drm scheme
|
* "version" [string] identifies the version of the drm scheme
|
* "description" [string] describes the drm scheme
|
* 'deviceUniqueId' [byte array] The device unique identifier is
|
* established during device provisioning and provides a means of
|
* uniquely identifying each device.
|
*
|
* Since drm scheme properties may vary, additional field names may be
|
* defined by each DRM vendor. Refer to your DRM provider documentation
|
* for definitions of its additional field names.
|
*/
|
|
/**
|
* Read a string property value given the property name.
|
*
|
* @param propertyName the name of the property
|
* @return 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.
|
* @return value the property value string
|
*/
|
getPropertyString(string propertyName)
|
generates (Status status, string value);
|
|
/**
|
* Read a byte array property value given the property name.
|
*
|
* @param propertyName the name of the property
|
* @return 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.
|
* @return value the property value byte array
|
*/
|
getPropertyByteArray(string propertyName)
|
generates (Status status, vec<uint8_t> value);
|
|
/**
|
* Write a property string value given the property name
|
*
|
* @param propertyName the name of the property
|
* @param value the value to write
|
* @return 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.
|
*/
|
setPropertyString(string propertyName, string value)
|
generates (Status status);
|
|
/**
|
* Write a property byte array value given the property name
|
*
|
* @param propertyName the name of the property
|
* @param value the value to write
|
* @return 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(string propertyName, vec<uint8_t> value )
|
generates (Status status);
|
|
/**
|
* The following methods implement operations on a CryptoSession to support
|
* encrypt, decrypt, sign verify operations on operator-provided
|
* session keys.
|
*/
|
|
/**
|
* Set the cipher algorithm to be used for the specified session.
|
*
|
* @param sessionId the session id the call applies to
|
* @param 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".
|
* @return 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.
|
*/
|
setCipherAlgorithm(SessionId sessionId, string algorithm)
|
generates (Status status);
|
|
/**
|
* Set the MAC algorithm to be used for computing hashes in a session.
|
*
|
* @param sessionId the session id the call applies to
|
* @param 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".
|
* @return 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(SessionId sessionId, string algorithm)
|
generates (Status status);
|
|
/**
|
* Encrypt the provided input buffer with the cipher algorithm specified by
|
* setCipherAlgorithm and the key selected by keyId, and return the
|
* encrypted data.
|
*
|
* @param sessionId the session id the call applies to
|
* @param keyId the ID of the key to use for encryption
|
* @param input the input data to encrypt
|
* @param iv the initialization vector to use for encryption
|
* @return 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.
|
* @return output the decrypted data
|
*/
|
encrypt(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.
|
*
|
* @param sessionId the session id the call applies to
|
* @param keyId the ID of the key to use for decryption
|
* @param input the input data to decrypt
|
* @param iv the initialization vector to use for decryption
|
* @return 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.
|
* @return output the decrypted data
|
*/
|
decrypt(SessionId sessionId, vec<uint8_t> keyId, vec<uint8_t> input,
|
vec<uint8_t> iv) generates (Status status, vec<uint8_t> output);
|
|
/**
|
* Compute a signature over the provided message using the mac algorithm
|
* specified by setMacAlgorithm and the key selected by keyId and return
|
* the signature.
|
*
|
* @param sessionId the session id the call applies to
|
* @param keyId the ID of the key to use for decryption
|
* @param message the message to compute a signature over
|
* @return 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.
|
* @return signature the computed signature
|
*/
|
sign(SessionId sessionId, vec<uint8_t> keyId, vec<uint8_t> message)
|
generates (Status status, vec<uint8_t> signature);
|
|
/**
|
* 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.
|
*
|
* @param sessionId the session id the call applies to
|
* @param keyId the ID of the key to use for decryption
|
* @param message the message to compute a hash of
|
* @param signature the signature to verify
|
* @return 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.
|
* @return match true if the signature is verified positively,
|
* false otherwise.
|
*/
|
verify(SessionId sessionId, vec<uint8_t> keyId, vec<uint8_t> message,
|
vec<uint8_t> signature) generates (Status status, bool match);
|
|
/**
|
* Compute an RSA signature on the provided message using the specified
|
* algorithm.
|
*
|
* @param sessionId the session id the call applies to
|
* @param algorithm the signing algorithm, such as "RSASSA-PSS-SHA1"
|
* or "PKCS1-BlockType1"
|
* @param message the message to compute the signature on
|
* @param wrappedKey the private key returned during provisioning as
|
* returned by provideProvisionResponse.
|
* @return 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.
|
* @return signature the RSA signature computed over the message
|
*/
|
signRSA(SessionId sessionId, string algorithm, vec<uint8_t> message,
|
vec<uint8_t> wrappedkey)
|
generates (Status status, vec<uint8_t> signature);
|
|
/**
|
* Plugins call the following methods to deliver events to the
|
* java app.
|
*/
|
|
/**
|
* Set a listener for a drm session. This allows the drm HAL to
|
* make asynchronous calls back to the client of IDrm.
|
*
|
* @param listener instance of IDrmPluginListener to receive the events
|
*/
|
setListener(IDrmPluginListener listener);
|
|
/**
|
* Legacy event sending method, it sends events of various types using a
|
* single overloaded set of parameters. This form is deprecated.
|
*
|
* @param eventType the type of the event
|
* @param sessionId identifies the session the event originated from
|
* @param data event-specific data blob
|
*/
|
sendEvent(EventType eventType, SessionId sessionId, vec<uint8_t> data);
|
|
/**
|
* 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.
|
*
|
* @param sessionId identifies the session the event originated from
|
* @param 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.
|
*/
|
sendExpirationUpdate(SessionId sessionId, int64_t expiryTimeInMS);
|
|
/**
|
* 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.
|
*
|
* @param sessionId identifies the session the event originated from
|
* @param keyStatusList indicates the status for each key ID in the
|
* session.
|
* @param hasNewUsableKey indicates if the event includes at least one
|
* key that has become usable.
|
*/
|
sendKeysChange(SessionId sessionId, vec<KeyStatus> keyStatusList,
|
bool hasNewUsableKey);
|
};
|
