2 * Copyright (C) 2016 The Android Open Source Project
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
16 package android.hardware.drm@1.0;
18 import IDrmPluginListener;
21 * Ref: frameworks/native/include/media/drm/DrmAPI.h:DrmPlugin
23 * IDrmPlugin is used to interact with a specific drm plugin that was
24 * created by IDrm::createPlugin. A drm plugin provides methods for
25 * obtaining drm keys that may be used by a codec to decrypt protected
28 interface IDrmPlugin {
31 * Open a new session with the DrmPlugin object. A session ID is returned
32 * in the sessionId parameter.
33 * @return status the status of the call. The status must be OK or one of
34 * the following errors: ERROR_DRM_NOT_PROVISIONED if the device requires
35 * provisioning before it can open a session, ERROR_DRM_RESOURCE_BUSY if
36 * there are insufficent resources available to open a session,
37 * ERROR_DRM_CANNOT_HANDLE, if openSession is not supported at the time of
38 * the call or ERROR_DRM_INVALID_STATE if the HAL is in a state where a
39 * session cannot be opened.
40 * @return sessionId the session ID for the newly opened session
42 openSession() generates (Status status, SessionId sessionId);
45 * Close a session on the DrmPlugin object
47 * @param sessionId the session id the call applies to
48 * @return status the status of the call. The status must be OK or one of
49 * the following errors: ERROR_DRM_SESSION_NOT_OPENED if the session is not
50 * opened, BAD_VALUE if the sessionId is invalid or ERROR_DRM_INVALID_STATE
51 * if the HAL is in a state where the session cannot be closed.
53 closeSession(SessionId sessionId) generates (Status status);
56 * A key request/response exchange occurs between the app and a License
57 * Server to obtain the keys required to decrypt the content.
58 * getKeyRequest() is used to obtain an opaque key request blob that is
59 * delivered to the license server.
61 * @param scope may be a sessionId or a keySetId, depending on the
62 * specified keyType. When the keyType is OFFLINE or STREAMING,
63 * scope should be set to the sessionId the keys will be provided to.
64 * When the keyType is RELEASE, scope should be set to the keySetId
65 * of the keys being released.
66 * @param initData container-specific data, its meaning is interpreted
67 * based on the mime type provided in the mimeType parameter. It could
68 * contain, for example, the content ID, key ID or other data obtained
69 * from the content metadata that is required to generate the key request.
70 * initData may be empty when keyType is RELEASE.
71 * @param mimeType identifies the mime type of the content
72 * @param keyType specifies if the keys are to be used for streaming,
73 * offline or a release
74 * @param optionalParameters included in the key request message to
75 * allow a client application to provide additional message parameters to
78 * @return status the status of the call. The status must be OK or one of
79 * the following errors: ERROR_DRM_SESSION_NOT_OPENED if the session is not
80 * opened, ERROR_DRM_NOT_PROVISIONED if the device requires provisioning
81 * before it can generate a key request, ERROR_DRM_CANNOT_HANDLE if
82 * getKeyRequest is not supported at the time of the call, BAD_VALUE if any
83 * parameters are invalid or ERROR_DRM_INVALID_STATE if the HAL is in a state
84 * where a key request cannot be generated.
85 * @return request if successful, the opaque key request blob is returned
86 * @return requestType indicates type information about the returned
87 * request. The type may be one of INITIAL, RENEWAL or RELEASE. An
88 * INITIAL request is the first key request for a license. RENEWAL is a
89 * subsequent key request used to refresh the keys in a license. RELEASE
90 * corresponds to a keyType of RELEASE, which indicates keys are being
92 * @return defaultUrl the URL that the request may be sent to, if
93 * provided by the drm HAL. The app may choose to override this
96 getKeyRequest(vec<uint8_t> scope, vec<uint8_t> initData,
97 string mimeType, KeyType keyType, KeyedVector optionalParameters)
98 generates (Status status, vec<uint8_t> request,
99 KeyRequestType requestType, string defaultUrl);
102 * After a key response is received by the app, it is provided to the
103 * Drm plugin using provideKeyResponse.
105 * @param scope may be a sessionId or a keySetId depending on the type
106 * of the response. Scope should be set to the sessionId when the response
107 * is for either streaming or offline key requests. Scope should be set to
108 * the keySetId when the response is for a release request.
109 * @param response the response from the key server that is being
110 * provided to the drm HAL.
112 * @return status the status of the call. The status must be OK or one of
113 * the following errors: ERROR_DRM_SESSION_NOT_OPENED if the session is not
114 * opened, ERROR_DRM_NOT_PROVISIONED if the device requires provisioning
115 * before it can handle the key response, ERROR_DRM_DEVICE_REVOKED if the
116 * device has been disabled by the license policy, ERROR_DRM_CANNOT_HANDLE
117 * if provideKeyResponse is not supported at the time of the call, BAD_VALUE
118 * if any parameters are invalid or ERROR_DRM_INVALID_STATE if the HAL is
119 * in a state where a key response cannot be handled.
120 * @return keySetId when the response is for an offline key request, a
121 * keySetId is returned in the keySetId vector parameter that can be used
122 * to later restore the keys to a new session with the method restoreKeys.
123 * When the response is for a streaming or release request, no keySetId is
126 provideKeyResponse(vec<uint8_t> scope, vec<uint8_t> response)
127 generates (Status status, vec<uint8_t> keySetId);
130 * Remove the current keys from a session
132 * @param sessionId the session id the call applies to
133 * @return status the status of the call. The status must be OK or one of
134 * the following errors: ERROR_DRM_SESSION_NOT_OPENED if the session is not
135 * opened, BAD_VALUE if the sessionId is invalid or ERROR_DRM_INVALID_STATE
136 * if the HAL is in a state where the keys cannot be removed.
138 removeKeys(SessionId sessionId) generates (Status status);
141 * Restore persisted offline keys into a new session
143 * @param sessionId the session id the call applies to
144 * @param keySetId identifies the keys to load, obtained from a prior
145 * call to provideKeyResponse().
146 * @return status the status of the call. The status must be OK or one of
147 * the following errors: ERROR_DRM_SESSION_NOT_OPENED if the session is not
148 * opened, BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
149 * if the HAL is in a state where keys cannot be restored.
151 restoreKeys(SessionId sessionId,
152 vec<uint8_t> keySetId) generates (Status status);
155 * Request an informative description of the license for the session. The
156 * status is in the form of {name, value} pairs. Since DRM license policies
157 * vary by vendor, the specific status field names are determined by each
158 * DRM vendor. Refer to your DRM provider documentation for definitions of
159 * the field names for a particular drm scheme.
161 * @param sessionId the session id the call applies to
162 * @return status the status of the call. The status must be OK or one of
163 * the following errors: ERROR_DRM_SESSION_NOT_OPENED if the session is not
164 * opened, BAD_VALUE if the sessionId is invalid or ERROR_DRM_INVALID_STATE
165 * if the HAL is in a state where key status cannot be queried.
166 * @return infoList a list of name value pairs describing the license
168 queryKeyStatus(SessionId sessionId)
169 generates (Status status, KeyedVector infoList);
172 * A provision request/response exchange occurs between the app and a
173 * provisioning server to retrieve a device certificate. getProvisionRequest
174 * is used to obtain an opaque provisioning request blob that is delivered
175 * to the provisioning server.
177 * @param certificateType the type of certificate requested, e.g. "X.509"
178 * @param certificateAuthority identifies the certificate authority. A
179 * certificate authority (CA) is an entity which issues digital certificates
180 * for use by other parties. It is an example of a trusted third party.
181 * @return status the status of the call. The status must be OK or one of
182 * the following errors: ERROR_DRM_CANNOT_HANDLE if the drm scheme does not
183 * require provisioning or ERROR_DRM_INVALID_STATE if the HAL is in a state
184 * where the provision request cannot be generated.
185 * @return request if successful the opaque certificate request blob
187 * @return defaultUrl URL that the provisioning request should be
188 * sent to, if known by the HAL implementation. If the HAL implementation
189 * does not provide a defaultUrl, the returned string must be empty.
191 getProvisionRequest(string certificateType, string certificateAuthority)
192 generates (Status status, vec<uint8_t> request, string defaultUrl);
195 * After a provision response is received by the app from a provisioning
196 * server, it is provided to the Drm HAL using provideProvisionResponse.
197 * The HAL implementation must receive the provision request and
198 * store the provisioned credentials.
200 * @param response the opaque provisioning response received by the
201 * app from a provisioning server.
203 * @return status the status of the call. The status must be OK or one of
204 * the following errors: ERROR_DRM_DEVICE_REVOKED if the device has been
205 * disabled by the license policy, BAD_VALUE if any parameters are invalid
206 * or ERROR_DRM_INVALID_STATE if the HAL is in a state where the provision
207 * response cannot be handled.
208 * @return certificate the public certificate resulting from the provisioning
209 * operation, if any. An empty vector indicates that no certificate was
211 * @return wrappedKey an opaque object containing encrypted private key
212 * material to be used by signRSA when computing an RSA signature on a
213 * message, see the signRSA method.
215 provideProvisionResponse(vec<uint8_t> response) generates (Status status,
216 vec<uint8_t> certificate, vec<uint8_t> wrappedKey);
219 * SecureStop is a way of enforcing the concurrent stream limit per
220 * subscriber. It can securely monitor the lifetime of sessions across
221 * device reboots by periodically persisting the session lifetime
222 * status in secure storage.
224 * A signed version of the sessionID is written to persistent storage on the
225 * device when each MediaCrypto object is created and periodically during
226 * playback. The sessionID is signed by the device private key to prevent
229 * When playback is completed the session is destroyed, and the secure
230 * stops are queried by the app. The app then delivers the secure stop
231 * message to a server which verifies the signature to confirm that the
232 * session and its keys have been removed from the device. The persisted
233 * record on the device is removed after receiving and verifying the
234 * signed response from the server.
238 * Get all secure stops on the device
240 * @return status the status of the call. The status must be OK or
241 * ERROR_DRM_INVALID_STATE if the HAL is in a state where the secure stops
242 * cannot be returned.
243 * @return secureStops a list of the secure stop opaque objects
245 getSecureStops() generates
246 (Status status, vec<SecureStop> secureStops);
249 * Get all secure stops by secure stop ID
251 * @param secureStopId the ID of the secure stop to return. The
252 * secure stop ID is delivered by the key server as part of the key
253 * response and must also be known by the app.
255 * @return status the status of the call. The status must be OK or one of
256 * the following errors: BAD_VALUE if the secureStopId is invalid or
257 * ERROR_DRM_INVALID_STATE if the HAL is in a state where the secure stop
258 * cannot be returned.
259 * @return secureStop the secure stop opaque object
262 getSecureStop(SecureStopId secureStopId)
263 generates (Status status, SecureStop secureStop);
266 * Release all secure stops on the device
268 * @return status the status of the call. The status must be OK or
269 * ERROR_DRM_INVALID_STATE if the HAL is in a state where the secure
270 * stops cannot be released.
272 releaseAllSecureStops() generates (Status status);
275 * Release a secure stop by secure stop ID
277 * @param secureStopId the ID of the secure stop to release. The
278 * secure stop ID is delivered by the key server as part of the key
279 * response and must also be known by the app.
281 * @return status the status of the call. The status must be OK or one of
282 * the following errors: BAD_VALUE if the secureStopId is invalid or
283 * ERROR_DRM_INVALID_STATE if the HAL is in a state where the secure stop
284 * cannot be released.
286 releaseSecureStop(vec<uint8_t> secureStopId) generates (Status status);
289 * A drm scheme can have properties that are settable and readable
290 * by an app. There are a few forms of property access methods,
291 * depending on the data type of the property.
293 * Property values defined by the public API are:
294 * "vendor" [string] identifies the maker of the drm scheme
295 * "version" [string] identifies the version of the drm scheme
296 * "description" [string] describes the drm scheme
297 * 'deviceUniqueId' [byte array] The device unique identifier is
298 * established during device provisioning and provides a means of
299 * uniquely identifying each device.
301 * Since drm scheme properties may vary, additional field names may be
302 * defined by each DRM vendor. Refer to your DRM provider documentation
303 * for definitions of its additional field names.
307 * Read a string property value given the property name.
309 * @param propertyName the name of the property
310 * @return status the status of the call. The status must be OK or one of
311 * the following errors: BAD_VALUE if the property name is invalid,
312 * ERROR_DRM_CANNOT_HANDLE if the property is not supported, or
313 * ERROR_DRM_INVALID_STATE if the HAL is in a state where the property
314 * cannot be obtained.
315 * @return value the property value string
317 getPropertyString(string propertyName)
318 generates (Status status, string value);
321 * Read a byte array property value given the property name.
323 * @param propertyName the name of the property
324 * @return status the status of the call. The status must be OK or one of
325 * the following errors: BAD_VALUE if the property name is invalid,
326 * ERROR_DRM_CANNOT_HANDLE if the property is not supported, or
327 * ERROR_DRM_INVALID_STATE if the HAL is in a state where the property
328 * cannot be obtained.
329 * @return value the property value byte array
331 getPropertyByteArray(string propertyName)
332 generates (Status status, vec<uint8_t> value);
335 * Write a property string value given the property name
337 * @param propertyName the name of the property
338 * @param value the value to write
339 * @return status the status of the call. The status must be OK or one of
340 * the following errors: BAD_VALUE if the property name is invalid,
341 * ERROR_DRM_CANNOT_HANDLE if the property is not supported, or
342 * ERROR_DRM_INVALID_STATE if the HAL is in a state where the property
345 setPropertyString(string propertyName, string value)
346 generates (Status status);
349 * Write a property byte array value given the property name
351 * @param propertyName the name of the property
352 * @param value the value to write
353 * @return status the status of the call. The status must be OK or one of
354 * the following errors: BAD_VALUE if the property name is invalid,
355 * ERROR_DRM_CANNOT_HANDLE if the property is not supported, or
356 * ERROR_DRM_INVALID_STATE if the HAL is in a state where the property
359 setPropertyByteArray(string propertyName, vec<uint8_t> value )
360 generates (Status status);
363 * The following methods implement operations on a CryptoSession to support
364 * encrypt, decrypt, sign verify operations on operator-provided
369 * Set the cipher algorithm to be used for the specified session.
371 * @param sessionId the session id the call applies to
372 * @param algorithm the algorithm to use. The string conforms to JCA
373 * Standard Names for Cipher Transforms and is case insensitive. An
374 * example algorithm is "AES/CBC/PKCS5Padding".
375 * @return status the status of the call. The status must be OK or one of
376 * the following errors: ERROR_DRM_SESSION_NOT_OPENED if the session is not
377 * opened, BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
378 * if the HAL is in a state where the algorithm cannot be set.
380 setCipherAlgorithm(SessionId sessionId, string algorithm)
381 generates (Status status);
384 * Set the MAC algorithm to be used for computing hashes in a session.
386 * @param sessionId the session id the call applies to
387 * @param algorithm the algorithm to use. The string conforms to JCA
388 * Standard Names for Mac Algorithms and is case insensitive. An example MAC
389 * algorithm string is "HmacSHA256".
390 * @return status the status of the call. The status must be OK or one of the
391 * following errors: ERROR_DRM_SESSION_NOT_OPENED if the session is not
392 * opened, BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
393 * if the HAL is in a state where the algorithm cannot be set.
395 setMacAlgorithm(SessionId sessionId, string algorithm)
396 generates (Status status);
399 * Encrypt the provided input buffer with the cipher algorithm specified by
400 * setCipherAlgorithm and the key selected by keyId, and return the
403 * @param sessionId the session id the call applies to
404 * @param keyId the ID of the key to use for encryption
405 * @param input the input data to encrypt
406 * @param iv the initialization vector to use for encryption
407 * @return status the status of the call. The status must be OK or one of the
408 * following errors: ERROR_DRM_SESSION_NOT_OPENED if the session is not opened,
409 * BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
410 * if the HAL is in a state where the encrypt operation cannot be performed.
411 * @return output the decrypted data
413 encrypt(SessionId sessionId, vec<uint8_t> keyId, vec<uint8_t> input,
414 vec<uint8_t> iv) generates (Status status, vec<uint8_t> output);
417 * Decrypt the provided input buffer with the cipher algorithm
418 * specified by setCipherAlgorithm and the key selected by keyId,
419 * and return the decrypted data.
421 * @param sessionId the session id the call applies to
422 * @param keyId the ID of the key to use for decryption
423 * @param input the input data to decrypt
424 * @param iv the initialization vector to use for decryption
425 * @return status the status of the call. The status must be OK or one of
426 * the following errors: ERROR_DRM_SESSION_NOT_OPENED if the session is not
427 * opened, BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
428 * if the HAL is in a state where the decrypt operation cannot be
430 * @return output the decrypted data
432 decrypt(SessionId sessionId, vec<uint8_t> keyId, vec<uint8_t> input,
433 vec<uint8_t> iv) generates (Status status, vec<uint8_t> output);
436 * Compute a signature over the provided message using the mac algorithm
437 * specified by setMacAlgorithm and the key selected by keyId and return
440 * @param sessionId the session id the call applies to
441 * @param keyId the ID of the key to use for decryption
442 * @param message the message to compute a signature over
443 * @return status the status of the call. The status must be OK or one of
444 * the following errors: ERROR_DRM_SESSION_NOT_OPENED if the session is not
445 * opened, BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
446 * if the HAL is in a state where the sign operation cannot be
448 * @return signature the computed signature
450 sign(SessionId sessionId, vec<uint8_t> keyId, vec<uint8_t> message)
451 generates (Status status, vec<uint8_t> signature);
454 * Compute a hash of the provided message using the mac algorithm specified
455 * by setMacAlgorithm and the key selected by keyId, and compare with the
458 * @param sessionId the session id the call applies to
459 * @param keyId the ID of the key to use for decryption
460 * @param message the message to compute a hash of
461 * @param signature the signature to verify
462 * @return status the status of the call. The status must be OK or one of
463 * the following errors: ERROR_DRM_SESSION_NOT_OPENED if the session is not
464 * opened, BAD_VALUE if any parameters are invalid or ERROR_DRM_INVALID_STATE
465 * if the HAL is in a state where the verify operation cannot be
467 * @return match true if the signature is verified positively,
470 verify(SessionId sessionId, vec<uint8_t> keyId, vec<uint8_t> message,
471 vec<uint8_t> signature) generates (Status status, bool match);
474 * Compute an RSA signature on the provided message using the specified
477 * @param sessionId the session id the call applies to
478 * @param algorithm the signing algorithm, such as "RSASSA-PSS-SHA1"
479 * or "PKCS1-BlockType1"
480 * @param message the message to compute the signature on
481 * @param wrappedKey the private key returned during provisioning as
482 * returned by provideProvisionResponse.
483 * @return status the status of the call. The status must be OK or one of
484 * the following errors: ERROR_DRM_SESSION_NOT_OPENED if the session is
485 * not opened, BAD_VALUE if any parameters are invalid or
486 * ERROR_DRM_INVALID_STATE if the HAL is in a state where the signRSA
487 * operation cannot be performed.
488 * @return signature the RSA signature computed over the message
490 signRSA(SessionId sessionId, string algorithm, vec<uint8_t> message,
491 vec<uint8_t> wrappedkey)
492 generates (Status status, vec<uint8_t> signature);
495 * Plugins call the following methods to deliver events to the
500 * Set a listener for a drm session. This allows the drm HAL to
501 * make asynchronous calls back to the client of IDrm.
503 * @param listener instance of IDrmPluginListener to receive the events
505 setListener(IDrmPluginListener listener);
508 * Legacy event sending method, it sends events of various types using a
509 * single overloaded set of parameters. This form is deprecated.
511 * @param eventType the type of the event
512 * @param sessionId identifies the session the event originated from
513 * @param data event-specific data blob
515 sendEvent(EventType eventType, SessionId sessionId, vec<uint8_t> data);
518 * Send a license expiration update to the listener. The expiration
519 * update indicates how long the current license is valid before it
520 * needs to be renewed.
522 * @param sessionId identifies the session the event originated from
523 * @param expiryTimeInMS the time when the keys need to be renewed.
524 * The time is in milliseconds, relative to the Unix epoch. A time of 0
525 * indicates that the keys never expire.
527 sendExpirationUpdate(SessionId sessionId, int64_t expiryTimeInMS);
530 * Send a keys change event to the listener. The keys change event
531 * indicates the status of each key in the session. Keys can be
532 * indicated as being usable, expired, outputnotallowed or statuspending.
534 * @param sessionId identifies the session the event originated from
535 * @param keyStatusList indicates the status for each key ID in the
537 * @param hasNewUsableKey indicates if the event includes at least one
538 * key that has become usable.
540 sendKeysChange(SessionId sessionId, vec<KeyStatus> keyStatusList,
541 bool hasNewUsableKey);