drm/1.0/IDrmPlugin.hal

   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 };