1 /** 2 * Copyright (C) 2016 The Android Open Source Project 3 * 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 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 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. 15 */ 16 package android.hardware.drm@1.0; 17 18 import IDrmPluginListener; 19 20 /** 21 * Ref: frameworks/native/include/media/drm/DrmAPI.h:DrmPlugin 22 * 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 26 * video content. 27 */ 28 interface IDrmPlugin { 29 30 /** 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 41 */ 42 openSession() generates (Status status, SessionId sessionId); 43 44 /** 45 * Close a session on the DrmPlugin object 46 * 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. 52 */ 53 closeSession(SessionId sessionId) generates (Status status); 54 55 /** 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. 60 * 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 76 * the server. 77 * 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 91 * released. 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 94 * URL. 95 */ 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); 100 101 /** 102 * After a key response is received by the app, it is provided to the 103 * Drm plugin using provideKeyResponse. 104 * 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. 111 * 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 124 * returned. 125 */ 126 provideKeyResponse(vec<uint8_t> scope, vec<uint8_t> response) 127 generates (Status status, vec<uint8_t> keySetId); 128 129 /** 130 * Remove the current keys from a session 131 * 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. 137 */ 138 removeKeys(SessionId sessionId) generates (Status status); 139 140 /** 141 * Restore persisted offline keys into a new session 142 * 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. 150 */ 151 restoreKeys(SessionId sessionId, 152 vec<uint8_t> keySetId) generates (Status status); 153 154 /** 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. 160 * 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 167 */ 168 queryKeyStatus(SessionId sessionId) 169 generates (Status status, KeyedVector infoList); 170 171 /** 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. 176 * 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 186 * is returned 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. 190 */ 191 getProvisionRequest(string certificateType, string certificateAuthority) 192 generates (Status status, vec<uint8_t> request, string defaultUrl); 193 194 /** 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. 199 * 200 * @param response the opaque provisioning response received by the 201 * app from a provisioning server. 202 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 210 * returned. 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. 214 */ 215 provideProvisionResponse(vec<uint8_t> response) generates (Status status, 216 vec<uint8_t> certificate, vec<uint8_t> wrappedKey); 217 218 /** 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. 223 * 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 227 * tampering. 228 * 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. 235 */ 236 237 /** 238 * Get all secure stops on the device 239 * 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 244 */ 245 getSecureStops() generates 246 (Status status, vec<SecureStop> secureStops); 247 248 /** 249 * Get all secure stops by secure stop ID 250 * 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. 254 * 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 260 */ 261 262 getSecureStop(SecureStopId secureStopId) 263 generates (Status status, SecureStop secureStop); 264 265 /** 266 * Release all secure stops on the device 267 * 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. 271 */ 272 releaseAllSecureStops() generates (Status status); 273 274 /** 275 * Release a secure stop by secure stop ID 276 * 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. 280 * 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. 285 */ 286 releaseSecureStop(vec<uint8_t> secureStopId) generates (Status status); 287 288 /** 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. 292 * 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. 300 * 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. 304 */ 305 306 /** 307 * Read a string property value given the property name. 308 * 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 316 */ 317 getPropertyString(string propertyName) 318 generates (Status status, string value); 319 320 /** 321 * Read a byte array property value given the property name. 322 * 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 330 */ 331 getPropertyByteArray(string propertyName) 332 generates (Status status, vec<uint8_t> value); 333 334 /** 335 * Write a property string value given the property name 336 * 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 343 * cannot be set. 344 */ 345 setPropertyString(string propertyName, string value) 346 generates (Status status); 347 348 /** 349 * Write a property byte array value given the property name 350 * 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 357 * cannot be set. 358 */ 359 setPropertyByteArray(string propertyName, vec<uint8_t> value ) 360 generates (Status status); 361 362 /** 363 * The following methods implement operations on a CryptoSession to support 364 * encrypt, decrypt, sign verify operations on operator-provided 365 * session keys. 366 */ 367 368 /** 369 * Set the cipher algorithm to be used for the specified session. 370 * 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. 379 */ 380 setCipherAlgorithm(SessionId sessionId, string algorithm) 381 generates (Status status); 382 383 /** 384 * Set the MAC algorithm to be used for computing hashes in a session. 385 * 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. 394 */ 395 setMacAlgorithm(SessionId sessionId, string algorithm) 396 generates (Status status); 397 398 /** 399 * Encrypt the provided input buffer with the cipher algorithm specified by 400 * setCipherAlgorithm and the key selected by keyId, and return the 401 * encrypted data. 402 * 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 412 */ 413 encrypt(SessionId sessionId, vec<uint8_t> keyId, vec<uint8_t> input, 414 vec<uint8_t> iv) generates (Status status, vec<uint8_t> output); 415 416 /** 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. 420 * 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 429 * performed. 430 * @return output the decrypted data 431 */ 432 decrypt(SessionId sessionId, vec<uint8_t> keyId, vec<uint8_t> input, 433 vec<uint8_t> iv) generates (Status status, vec<uint8_t> output); 434 435 /** 436 * Compute a signature over the provided message using the mac algorithm 437 * specified by setMacAlgorithm and the key selected by keyId and return 438 * the signature. 439 * 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 447 * performed. 448 * @return signature the computed signature 449 */ 450 sign(SessionId sessionId, vec<uint8_t> keyId, vec<uint8_t> message) 451 generates (Status status, vec<uint8_t> signature); 452 453 /** 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 456 * expected result. 457 * 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 466 * performed. 467 * @return match true if the signature is verified positively, 468 * false otherwise. 469 */ 470 verify(SessionId sessionId, vec<uint8_t> keyId, vec<uint8_t> message, 471 vec<uint8_t> signature) generates (Status status, bool match); 472 473 /** 474 * Compute an RSA signature on the provided message using the specified 475 * algorithm. 476 * 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 489 */ 490 signRSA(SessionId sessionId, string algorithm, vec<uint8_t> message, 491 vec<uint8_t> wrappedkey) 492 generates (Status status, vec<uint8_t> signature); 493 494 /** 495 * Plugins call the following methods to deliver events to the 496 * java app. 497 */ 498 499 /** 500 * Set a listener for a drm session. This allows the drm HAL to 501 * make asynchronous calls back to the client of IDrm. 502 * 503 * @param listener instance of IDrmPluginListener to receive the events 504 */ 505 setListener(IDrmPluginListener listener); 506 507 /** 508 * Legacy event sending method, it sends events of various types using a 509 * single overloaded set of parameters. This form is deprecated. 510 * 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 514 */ 515 sendEvent(EventType eventType, SessionId sessionId, vec<uint8_t> data); 516 517 /** 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. 521 * 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. 526 */ 527 sendExpirationUpdate(SessionId sessionId, int64_t expiryTimeInMS); 528 529 /** 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. 533 * 534 * @param sessionId identifies the session the event originated from 535 * @param keyStatusList indicates the status for each key ID in the 536 * session. 537 * @param hasNewUsableKey indicates if the event includes at least one 538 * key that has become usable. 539 */ 540 sendKeysChange(SessionId sessionId, vec<KeyStatus> keyStatusList, 541 bool hasNewUsableKey); 542 }; 543
