1 /* 2 * Copyright (C) 2014 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 17 /** 18 * @addtogroup Media 19 * @{ 20 */ 21 22 /** 23 * @file NdkMediaDrm.h 24 */ 25 26 /* 27 * This file defines an NDK API. 28 * Do not remove methods. 29 * Do not change method signatures. 30 * Do not change the value of constants. 31 * Do not change the size of any of the classes defined in here. 32 * Do not reference types that are not part of the NDK. 33 * Do not #include files that aren't part of the NDK. 34 */ 35 36 #ifndef _NDK_MEDIA_DRM_H 37 #define _NDK_MEDIA_DRM_H 38 39 #include <stdbool.h> 40 #include <stdint.h> 41 #include <sys/cdefs.h> 42 43 #include "NdkMediaError.h" 44 45 __BEGIN_DECLS 46 47 struct AMediaDrm; 48 typedef struct AMediaDrm AMediaDrm; 49 50 typedef struct { 51 const uint8_t *ptr; 52 size_t length; 53 } AMediaDrmByteArray; 54 55 typedef AMediaDrmByteArray AMediaDrmSessionId; 56 typedef AMediaDrmByteArray AMediaDrmScope; 57 typedef AMediaDrmByteArray AMediaDrmKeySetId; 58 typedef AMediaDrmByteArray AMediaDrmSecureStop; 59 typedef AMediaDrmByteArray AMediaDrmKeyId; 60 61 typedef enum AMediaDrmEventType { 62 /** 63 * This event type indicates that the app needs to request a certificate from 64 * the provisioning server. The request message data is obtained using 65 * AMediaDrm_getProvisionRequest. 66 */ 67 EVENT_PROVISION_REQUIRED = 1, 68 69 /** 70 * This event type indicates that the app needs to request keys from a license 71 * server. The request message data is obtained using AMediaDrm_getKeyRequest. 72 */ 73 EVENT_KEY_REQUIRED = 2, 74 75 /** 76 * This event type indicates that the licensed usage duration for keys in a session 77 * has expired. The keys are no longer valid. 78 */ 79 EVENT_KEY_EXPIRED = 3, 80 81 /** 82 * This event may indicate some specific vendor-defined condition, see your 83 * DRM provider documentation for details 84 */ 85 EVENT_VENDOR_DEFINED = 4, 86 87 /** 88 * This event indicates that a session opened by the app has been reclaimed 89 * by the resource manager. 90 */ 91 EVENT_SESSION_RECLAIMED = 5, 92 } AMediaDrmEventType; 93 94 typedef enum AMediaDrmKeyType { 95 /** 96 * This key request type specifies that the keys will be for online use, they will 97 * not be saved to the device for subsequent use when the device is not connected 98 * to a network. 99 */ 100 KEY_TYPE_STREAMING = 1, 101 102 /** 103 * This key request type specifies that the keys will be for offline use, they 104 * will be saved to the device for use when the device is not connected to a network. 105 */ 106 KEY_TYPE_OFFLINE = 2, 107 108 /** 109 * This key request type specifies that previously saved offline keys should be released. 110 */ 111 KEY_TYPE_RELEASE = 3 112 } AMediaDrmKeyType; 113 114 /** 115 * Data type containing {key, value} pair 116 */ 117 typedef struct AMediaDrmKeyValuePair { 118 const char *mKey; 119 const char *mValue; 120 } AMediaDrmKeyValue; 121 122 typedef enum AMediaKeyStatusType { 123 /** 124 * The key is currently usable to decrypt media data. 125 */ 126 KEY_STATUS_TYPE_USABLE, 127 128 /** 129 * The key is no longer usable to decrypt media data because its expiration 130 * time has passed. 131 */ 132 KEY_STATUS_TYPE_EXPIRED, 133 134 /** 135 * The key is not currently usable to decrypt media data because its output 136 * requirements cannot currently be met. 137 */ 138 KEY_STATUS_TYPE_OUTPUTNOTALLOWED, 139 140 /** 141 * The status of the key is not yet known and is being determined. 142 */ 143 KEY_STATUS_TYPE_STATUSPENDING, 144 145 /** 146 * The key is not currently usable to decrypt media data because of an 147 * internal error in processing unrelated to input parameters. 148 */ 149 KEY_STATUS_TYPE_INTERNALERROR, 150 151 } AMediaDrmKeyStatusType; 152 153 typedef struct AMediaDrmKeyStatus { 154 AMediaDrmKeyId keyId; 155 AMediaDrmKeyStatusType keyType; 156 } AMediaDrmKeyStatus; 157 158 typedef void (*AMediaDrmEventListener)(AMediaDrm *, const AMediaDrmSessionId *sessionId, 159 AMediaDrmEventType eventType, int extra, const uint8_t *data, size_t dataSize); 160 161 typedef void (*AMediaDrmExpirationUpdateListener)(AMediaDrm *, 162 const AMediaDrmSessionId *sessionId, int64_t expiryTimeInMS); 163 164 typedef void (*AMediaDrmKeysChangeListener)(AMediaDrm *, 165 const AMediaDrmSessionId *sessionId, const AMediaDrmKeyStatus *keyStatus, 166 size_t numKeys, bool hasNewUsableKey); 167 168 /** 169 * Query if the given scheme identified by its UUID is supported on this device, and 170 * whether the drm plugin is able to handle the media container format specified by mimeType. 171 * 172 * uuid identifies the universal unique ID of the crypto scheme. uuid must be 16 bytes. 173 * mimeType is the MIME type of the media container, e.g. "video/mp4". If mimeType 174 * is not known or required, it can be provided as NULL. 175 * 176 * Available since API level 21. 177 */ 178 bool AMediaDrm_isCryptoSchemeSupported(const uint8_t *uuid, 179 const char *mimeType) __INTRODUCED_IN(21); 180 181 /** 182 * Create a MediaDrm instance from a UUID. 183 * uuid identifies the universal unique ID of the crypto scheme. uuid must be 16 bytes. 184 * 185 * Available since API level 21. 186 */ 187 AMediaDrm* AMediaDrm_createByUUID(const uint8_t *uuid) __INTRODUCED_IN(21); 188 189 /** 190 * Release a MediaDrm object. 191 * 192 * Available since API level 21. 193 */ 194 void AMediaDrm_release(AMediaDrm *) __INTRODUCED_IN(21); 195 196 /** 197 * Register a callback to be invoked when an event occurs. 198 * 199 * listener is the callback that will be invoked on event. 200 * 201 * Available since API level 21. 202 */ 203 media_status_t AMediaDrm_setOnEventListener(AMediaDrm *, 204 AMediaDrmEventListener listener) __INTRODUCED_IN(21); 205 206 /** 207 * Register a callback to be invoked when an expiration update event occurs. 208 * 209 * listener is the callback that will be invoked on event. 210 * 211 * Available since API level 29. 212 */ 213 media_status_t AMediaDrm_setOnExpirationUpdateListener(AMediaDrm *, 214 AMediaDrmExpirationUpdateListener listener) __INTRODUCED_IN(29); 215 216 /** 217 * Register a callback to be invoked when a key status change event occurs. 218 * 219 * listener is the callback that will be invoked on event. 220 * 221 * Available since API level 29. 222 */ 223 media_status_t AMediaDrm_setOnKeysChangeListener(AMediaDrm *, 224 AMediaDrmKeysChangeListener listener) __INTRODUCED_IN(29); 225 226 /** 227 * Open a new session with the MediaDrm object. A session ID is returned. 228 * 229 * Returns MEDIADRM_NOT_PROVISIONED_ERROR if provisioning is needed. 230 * Returns MEDIADRM_RESOURCE_BUSY_ERROR if required resources are in use. 231 * 232 * Available since API level 21. 233 */ 234 media_status_t AMediaDrm_openSession(AMediaDrm *, 235 AMediaDrmSessionId *sessionId) __INTRODUCED_IN(21); 236 237 /** 238 * Close a session on the MediaDrm object that was previously opened 239 * with AMediaDrm_openSession. 240 * 241 * Available since API level 21. 242 */ 243 media_status_t AMediaDrm_closeSession(AMediaDrm *, 244 const AMediaDrmSessionId *sessionId) __INTRODUCED_IN(21); 245 246 /** 247 * A key request/response exchange occurs between the app and a license server 248 * to obtain or release keys used to decrypt encrypted content. 249 * AMediaDrm_getKeyRequest is used to obtain an opaque key request byte array that 250 * is delivered to the license server. The opaque key request byte array is 251 * returned in KeyRequest.data. 252 * 253 * After the app has received the key request response from the server, 254 * it should deliver to the response to the DRM engine plugin using the method 255 * AMediaDrm_provideKeyResponse. 256 * 257 * scope may be a sessionId or a keySetId, depending on the specified keyType. 258 * When the keyType is KEY_TYPE_STREAMING or KEY_TYPE_OFFLINE, scope should be set 259 * to the sessionId the keys will be provided to. When the keyType is 260 * KEY_TYPE_RELEASE, scope should be set to the keySetId of the keys being released. 261 * Releasing keys from a device invalidates them for all sessions. 262 * 263 * init container-specific data, its meaning is interpreted based on the mime type 264 * provided in the mimeType parameter. It could contain, for example, the content 265 * ID, key ID or other data obtained from the content metadata that is required in 266 * generating the key request. init may be null when keyType is KEY_TYPE_RELEASE. 267 * 268 * initSize is the number of bytes of initData 269 * 270 * mimeType identifies the mime type of the content. 271 * 272 * keyType specifes the type of the request. The request may be to acquire keys for 273 * streaming or offline content, or to release previously acquired keys, which are 274 * identified by a keySetId. 275 * 276 * optionalParameters are included in the key request message to allow a client 277 * application to provide additional message parameters to the server. 278 * 279 * numOptionalParameters indicates the number of optional parameters provided 280 * by the caller 281 * 282 * On exit: 283 * 1. The keyRequest pointer will reference the opaque key request data. It 284 * will reside in memory owned by the AMediaDrm object, and will remain 285 * accessible until the next call to AMediaDrm_getKeyRequest or until the 286 * MediaDrm object is released. 287 * 2. keyRequestSize will be set to the size of the request 288 * 289 * Returns MEDIADRM_NOT_PROVISIONED_ERROR if reprovisioning is needed, due to a 290 * problem with the device certificate. 291 * 292 * Available since API level 21. 293 */ 294 media_status_t AMediaDrm_getKeyRequest(AMediaDrm *, const AMediaDrmScope *scope, 295 const uint8_t *init, size_t initSize, const char *mimeType, AMediaDrmKeyType keyType, 296 const AMediaDrmKeyValue *optionalParameters, size_t numOptionalParameters, 297 const uint8_t **keyRequest, size_t *keyRequestSize) __INTRODUCED_IN(21); 298 299 /** 300 * A key response is received from the license server by the app, then it is 301 * provided to the DRM engine plugin using provideKeyResponse. When the 302 * response is for an offline key request, a keySetId is returned that can be 303 * used to later restore the keys to a new session with AMediaDrm_restoreKeys. 304 * When the response is for a streaming or release request, a null keySetId is 305 * returned. 306 * 307 * scope may be a sessionId or keySetId depending on the type of the 308 * response. Scope should be set to the sessionId when the response is for either 309 * streaming or offline key requests. Scope should be set to the keySetId when 310 * the response is for a release request. 311 * 312 * response points to the opaque response from the server 313 * responseSize should be set to the size of the response in bytes 314 * 315 * Available since API level 21. 316 */ 317 media_status_t AMediaDrm_provideKeyResponse(AMediaDrm *, const AMediaDrmScope *scope, 318 const uint8_t *response, size_t responseSize, 319 AMediaDrmKeySetId *keySetId) __INTRODUCED_IN(21); 320 321 /** 322 * Restore persisted offline keys into a new session. keySetId identifies the 323 * keys to load, obtained from a prior call to AMediaDrm_provideKeyResponse. 324 * 325 * sessionId is the session ID for the DRM session. 326 * keySetId identifies the saved key set to restore. 327 * 328 * Available since API level 21. 329 */ 330 media_status_t AMediaDrm_restoreKeys(AMediaDrm *, const AMediaDrmSessionId *sessionId, 331 const AMediaDrmKeySetId *keySetId) __INTRODUCED_IN(21); 332 333 /** 334 * Remove the current keys from a session. 335 * 336 * keySetId identifies keys to remove. 337 * 338 * Available since API level 21. 339 */ 340 media_status_t AMediaDrm_removeKeys(AMediaDrm *, 341 const AMediaDrmSessionId *keySetId) __INTRODUCED_IN(21); 342 343 /** 344 * Request an informative description of the key status for the session. The status is 345 * in the form of {key, value} pairs. Since DRM license policies vary by vendor, 346 * the specific status field names are determined by each DRM vendor. Refer to your 347 * DRM provider documentation for definitions of the field names for a particular 348 * DRM engine plugin. 349 * 350 * On entry, numPairs should be set by the caller to the maximum number of pairs 351 * that can be returned (the size of the array). On exit, numPairs will be set 352 * to the number of entries written to the array. If the number of {key, value} pairs 353 * to be returned is greater than *numPairs, MEDIADRM_SHORT_BUFFER will be returned 354 * and numPairs will be set to the number of pairs available. 355 * 356 * Available since API level 21. 357 */ 358 media_status_t AMediaDrm_queryKeyStatus(AMediaDrm *, const AMediaDrmSessionId *sessionId, 359 AMediaDrmKeyValue *keyValuePairs, size_t *numPairs) __INTRODUCED_IN(21); 360 361 362 /** 363 * A provision request/response exchange occurs between the app and a provisioning 364 * server to retrieve a device certificate. If provisionining is required, the 365 * EVENT_PROVISION_REQUIRED event will be sent to the event handler. 366 * getProvisionRequest is used to obtain the opaque provision request byte array that 367 * should be delivered to the provisioning server. 368 * On exit: 369 * 1. The provision request data will be referenced by provisionRequest, in 370 * memory owned by the AMediaDrm object. It will remain accessible until the 371 * next call to getProvisionRequest. 372 * 2. provisionRequestSize will be set to the size of the request data. 373 * 3. serverUrl will reference a NULL terminated string containing the URL 374 * the provisioning request should be sent to. It will remain accessible until 375 * the next call to getProvisionRequest. 376 * 377 * Available since API level 21. 378 */ 379 media_status_t AMediaDrm_getProvisionRequest(AMediaDrm *, const uint8_t **provisionRequest, 380 size_t *provisionRequestSize, const char **serverUrl) __INTRODUCED_IN(21); 381 382 383 /** 384 * After a provision response is received by the app, it is provided to the DRM 385 * engine plugin using this method. 386 * 387 * response is the opaque provisioning response byte array to provide to the 388 * DRM engine plugin. 389 * responseSize is the length of the provisioning response in bytes. 390 * 391 * Returns MEDIADRM_DEVICE_REVOKED_ERROR if the response indicates that the 392 * server rejected the request 393 * 394 * Available since API level 21. 395 */ 396 media_status_t AMediaDrm_provideProvisionResponse(AMediaDrm *, 397 const uint8_t *response, size_t responseSize) __INTRODUCED_IN(21); 398 399 400 /** 401 * A means of enforcing limits on the number of concurrent streams per subscriber 402 * across devices is provided via SecureStop. This is achieved by securely 403 * monitoring the lifetime of sessions. 404 * 405 * Information from the server related to the current playback session is written 406 * to persistent storage on the device when each MediaCrypto object is created. 407 * 408 * In the normal case, playback will be completed, the session destroyed and the 409 * Secure Stops will be queried. The app queries secure stops and forwards the 410 * secure stop message to the server which verifies the signature and notifies the 411 * server side database that the session destruction has been confirmed. The persisted 412 * record on the client is only removed after positive confirmation that the server 413 * received the message using releaseSecureStops(). 414 * 415 * numSecureStops is set by the caller to the maximum number of secure stops to 416 * return. On exit, *numSecureStops will be set to the number actually returned. 417 * If *numSecureStops is too small for the number of secure stops available, 418 * MEDIADRM_SHORT_BUFFER will be returned and *numSecureStops will be set to the 419 * number required. 420 * 421 * Available since API level 21. 422 */ 423 media_status_t AMediaDrm_getSecureStops(AMediaDrm *, 424 AMediaDrmSecureStop *secureStops, size_t *numSecureStops) __INTRODUCED_IN(21); 425 426 /** 427 * Process the SecureStop server response message ssRelease. After authenticating 428 * the message, remove the SecureStops identified in the response. 429 * 430 * ssRelease is the server response indicating which secure stops to release 431 * 432 * Available since API level 21. 433 */ 434 media_status_t AMediaDrm_releaseSecureStops(AMediaDrm *, 435 const AMediaDrmSecureStop *ssRelease) __INTRODUCED_IN(21); 436 437 /** 438 * String property name: identifies the maker of the DRM engine plugin 439 */ 440 #define PROPERTY_VENDOR "vendor" 441 442 /** 443 * String property name: identifies the version of the DRM engine plugin 444 */ 445 #define PROPERTY_VERSION "version" 446 447 /** 448 * String property name: describes the DRM engine plugin 449 */ 450 #define PROPERTY_DESCRIPTION "description" 451 452 /** 453 * String property name: a comma-separated list of cipher and mac algorithms 454 * supported by CryptoSession. The list may be empty if the DRM engine 455 * plugin does not support CryptoSession operations. 456 */ 457 #define PROPERTY_ALGORITHMS "algorithms" 458 459 /** 460 * Read a DRM engine plugin String property value, given the property name string. 461 * 462 * propertyName identifies the property to query 463 * On return, propertyValue will be set to point to the property value. The 464 * memory that the value resides in is owned by the NDK MediaDrm API and 465 * will remain valid until the next call to AMediaDrm_getPropertyString. 466 * 467 * Available since API level 21. 468 */ 469 media_status_t AMediaDrm_getPropertyString(AMediaDrm *, const char *propertyName, 470 const char **propertyValue) __INTRODUCED_IN(21); 471 472 /** 473 * Byte array property name: the device unique identifier is established during 474 * device provisioning and provides a means of uniquely identifying each device. 475 */ 476 #define PROPERTY_DEVICE_UNIQUE_ID "deviceUniqueId" 477 478 /** 479 * Read a DRM engine plugin byte array property value, given the property name string. 480 * On return, *propertyValue will be set to point to the property value. The 481 * memory that the value resides in is owned by the NDK MediaDrm API and 482 * will remain valid until the next call to AMediaDrm_getPropertyByteArray. 483 * 484 * Available since API level 21. 485 */ 486 media_status_t AMediaDrm_getPropertyByteArray(AMediaDrm *, const char *propertyName, 487 AMediaDrmByteArray *propertyValue) __INTRODUCED_IN(21); 488 489 /** 490 * Set a DRM engine plugin String property value. 491 * 492 * Available since API level 21. 493 */ 494 media_status_t AMediaDrm_setPropertyString(AMediaDrm *, const char *propertyName, 495 const char *value) __INTRODUCED_IN(21); 496 497 /** 498 * Set a DRM engine plugin byte array property value. 499 * 500 * Available since API level 21. 501 */ 502 media_status_t AMediaDrm_setPropertyByteArray(AMediaDrm *, const char *propertyName, 503 const uint8_t *value, size_t valueSize) __INTRODUCED_IN(21); 504 505 /** 506 * In addition to supporting decryption of DASH Common Encrypted Media, the 507 * MediaDrm APIs provide the ability to securely deliver session keys from 508 * an operator's session key server to a client device, based on the factory-installed 509 * root of trust, and then perform encrypt, decrypt, sign and verify operations 510 * with the session key on arbitrary user data. 511 * 512 * Operators create session key servers that receive session key requests and provide 513 * encrypted session keys which can be used for general purpose crypto operations. 514 * 515 * Generic encrypt/decrypt/sign/verify methods are based on the established session 516 * keys. These keys are exchanged using the getKeyRequest/provideKeyResponse methods. 517 * 518 * Applications of this capability include securing various types of purchased or 519 * private content, such as applications, books and other media, photos or media 520 * delivery protocols. 521 */ 522 523 /* 524 * Encrypt the data referenced by input of length dataSize using algorithm specified 525 * by cipherAlgorithm, and write the encrypted result into output. The caller must 526 * ensure that the output buffer is large enough to accept dataSize bytes. The key 527 * to use is identified by the 16 byte keyId. The key must have been loaded into 528 * the session using provideKeyResponse. 529 * 530 * Available since API level 21. 531 */ 532 media_status_t AMediaDrm_encrypt(AMediaDrm *, const AMediaDrmSessionId *sessionId, 533 const char *cipherAlgorithm, uint8_t *keyId, uint8_t *iv, 534 const uint8_t *input, uint8_t *output, size_t dataSize) __INTRODUCED_IN(21); 535 536 /* 537 * Decrypt the data referenced by input of length dataSize using algorithm specified 538 * by cipherAlgorithm, and write the decrypted result into output. The caller must 539 * ensure that the output buffer is large enough to accept dataSize bytes. The key 540 * to use is identified by the 16 byte keyId. The key must have been loaded into 541 * the session using provideKeyResponse. 542 * 543 * Available since API level 21. 544 */ 545 media_status_t AMediaDrm_decrypt(AMediaDrm *, const AMediaDrmSessionId *sessionId, 546 const char *cipherAlgorithm, uint8_t *keyId, uint8_t *iv, 547 const uint8_t *input, uint8_t *output, size_t dataSize) __INTRODUCED_IN(21); 548 549 /* 550 * Generate a signature using the specified macAlgorithm over the message data 551 * referenced by message of size messageSize and store the signature in the 552 * buffer referenced signature of max size *signatureSize. If the buffer is not 553 * large enough to hold the signature, MEDIADRM_SHORT_BUFFER is returned and 554 * *signatureSize is set to the buffer size required. The key to use is identified 555 * by the 16 byte keyId. The key must have been loaded into the session using 556 * provideKeyResponse. 557 * 558 * Available since API level 21. 559 */ 560 media_status_t AMediaDrm_sign(AMediaDrm *, const AMediaDrmSessionId *sessionId, 561 const char *macAlgorithm, uint8_t *keyId, uint8_t *message, size_t messageSize, 562 uint8_t *signature, size_t *signatureSize) __INTRODUCED_IN(21); 563 564 /* 565 * Perform a signature verification using the specified macAlgorithm over the message 566 * data referenced by the message parameter of size messageSize. Returns MEDIADRM_OK 567 * if the signature matches, otherwise MEDAIDRM_VERIFY_FAILED is returned. The key to 568 * use is identified by the 16 byte keyId. The key must have been loaded into the 569 * session using provideKeyResponse. 570 * 571 * Available since API level 21. 572 */ 573 media_status_t AMediaDrm_verify(AMediaDrm *, const AMediaDrmSessionId *sessionId, 574 const char *macAlgorithm, uint8_t *keyId, const uint8_t *message, size_t messageSize, 575 const uint8_t *signature, size_t signatureSize) __INTRODUCED_IN(21); 576 577 __END_DECLS 578 579 #endif //_NDK_MEDIA_DRM_H 580 581 /** @} */ 582