/** * 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 scope, vec initData, string mimeType, KeyType keyType, KeyedVector optionalParameters) generates (Status status, vec 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 scope, vec response) generates (Status status, vec 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 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 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 response) generates (Status status, vec certificate, vec 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 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 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 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 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 keyId, vec input, vec iv) generates (Status status, vec 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 keyId, vec input, vec iv) generates (Status status, vec 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 keyId, vec message) generates (Status status, vec 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 keyId, vec message, vec 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 message, vec wrappedkey) generates (Status status, vec 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 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 keyStatusList, bool hasNewUsableKey); };