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 * Introduced in API 33. 116 */ 117 typedef enum AMediaDrmKeyRequestType : int32_t { 118 /** 119 * Key request type is initial license request. 120 * An initial license request is necessary to load keys. 121 */ 122 KEY_REQUEST_TYPE_INITIAL, 123 124 /** 125 * Key request type is license renewal. 126 * A renewal license request is necessary to prevent the keys from expiring. 127 */ 128 KEY_REQUEST_TYPE_RENEWAL, 129 130 /** 131 * Key request type is license release. 132 * A license release request indicates that keys are removed. 133 */ 134 KEY_REQUEST_TYPE_RELEASE, 135 136 /** 137 * Keys are already loaded and are available for use. No license request is necessary, and 138 * no key request data is returned. 139 */ 140 KEY_REQUEST_TYPE_NONE, 141 142 /** 143 * Keys have been loaded but an additional license request is needed 144 * to update their values. 145 */ 146 KEY_REQUEST_TYPE_UPDATE 147 } AMediaDrmKeyRequestType; 148 149 /** 150 * Data type containing {key, value} pair 151 */ 152 typedef struct AMediaDrmKeyValuePair { 153 const char *mKey; 154 const char *mValue; 155 } AMediaDrmKeyValue; 156 157 typedef enum AMediaKeyStatusType { 158 /** 159 * The key is currently usable to decrypt media data. 160 */ 161 KEY_STATUS_TYPE_USABLE, 162 163 /** 164 * The key is no longer usable to decrypt media data because its expiration 165 * time has passed. 166 */ 167 KEY_STATUS_TYPE_EXPIRED, 168 169 /** 170 * The key is not currently usable to decrypt media data because its output 171 * requirements cannot currently be met. 172 */ 173 KEY_STATUS_TYPE_OUTPUTNOTALLOWED, 174 175 /** 176 * The status of the key is not yet known and is being determined. 177 */ 178 KEY_STATUS_TYPE_STATUSPENDING, 179 180 /** 181 * The key is not currently usable to decrypt media data because of an 182 * internal error in processing unrelated to input parameters. 183 */ 184 KEY_STATUS_TYPE_INTERNALERROR, 185 186 } AMediaDrmKeyStatusType; 187 188 typedef struct AMediaDrmKeyStatus { 189 AMediaDrmKeyId keyId; 190 AMediaDrmKeyStatusType keyType; 191 } AMediaDrmKeyStatus; 192 193 typedef void (*AMediaDrmEventListener)(AMediaDrm *, const AMediaDrmSessionId *sessionId, 194 AMediaDrmEventType eventType, int extra, const uint8_t *data, size_t dataSize); 195 196 typedef void (*AMediaDrmExpirationUpdateListener)(AMediaDrm *, 197 const AMediaDrmSessionId *sessionId, int64_t expiryTimeInMS); 198 199 typedef void (*AMediaDrmKeysChangeListener)(AMediaDrm *, 200 const AMediaDrmSessionId *sessionId, const AMediaDrmKeyStatus *keyStatus, 201 size_t numKeys, bool hasNewUsableKey); 202 203 /** 204 * Query if the given scheme identified by its UUID is supported on this device, and 205 * whether the drm plugin is able to handle the media container format specified by mimeType. 206 * 207 * uuid identifies the universal unique ID of the crypto scheme. uuid must be 16 bytes. 208 * mimeType is the MIME type of the media container, e.g. "video/mp4". If mimeType 209 * is not known or required, it can be provided as NULL. 210 * 211 * Available since API level 21. 212 */ 213 bool AMediaDrm_isCryptoSchemeSupported(const uint8_t *uuid, 214 const char *mimeType) __INTRODUCED_IN(21); 215 216 /** 217 * Create a MediaDrm instance from a UUID. 218 * uuid identifies the universal unique ID of the crypto scheme. uuid must be 16 bytes. 219 * 220 * Available since API level 21. 221 */ 222 AMediaDrm* AMediaDrm_createByUUID(const uint8_t *uuid) __INTRODUCED_IN(21); 223 224 /** 225 * Release a MediaDrm object. 226 * 227 * Available since API level 21. 228 */ 229 void AMediaDrm_release(AMediaDrm *) __INTRODUCED_IN(21); 230 231 /** 232 * Register a callback to be invoked when an event occurs. 233 * 234 * listener is the callback that will be invoked on event. 235 * 236 * Available since API level 21. 237 */ 238 media_status_t AMediaDrm_setOnEventListener(AMediaDrm *, 239 AMediaDrmEventListener listener) __INTRODUCED_IN(21); 240 241 /** 242 * Register a callback to be invoked when an expiration update event occurs. 243 * 244 * listener is the callback that will be invoked on event. 245 * 246 * Available since API level 29. 247 */ 248 media_status_t AMediaDrm_setOnExpirationUpdateListener(AMediaDrm *, 249 AMediaDrmExpirationUpdateListener listener) __INTRODUCED_IN(29); 250 251 /** 252 * Register a callback to be invoked when a key status change event occurs. 253 * 254 * listener is the callback that will be invoked on event. 255 * 256 * Available since API level 29. 257 */ 258 media_status_t AMediaDrm_setOnKeysChangeListener(AMediaDrm *, 259 AMediaDrmKeysChangeListener listener) __INTRODUCED_IN(29); 260 261 /** 262 * Open a new session with the MediaDrm object. A session ID is returned. 263 * 264 * Returns MEDIADRM_NOT_PROVISIONED_ERROR if provisioning is needed. 265 * Returns MEDIADRM_RESOURCE_BUSY_ERROR if required resources are in use. 266 * 267 * Available since API level 21. 268 */ 269 media_status_t AMediaDrm_openSession(AMediaDrm *, 270 AMediaDrmSessionId *sessionId) __INTRODUCED_IN(21); 271 272 /** 273 * Close a session on the MediaDrm object that was previously opened 274 * with AMediaDrm_openSession. 275 * 276 * Available since API level 21. 277 */ 278 media_status_t AMediaDrm_closeSession(AMediaDrm *, 279 const AMediaDrmSessionId *sessionId) __INTRODUCED_IN(21); 280 281 /** 282 * A key request/response exchange occurs between the app and a license server 283 * to obtain or release keys used to decrypt encrypted content. 284 * AMediaDrm_getKeyRequest is used to obtain an opaque key request byte array that 285 * is delivered to the license server. The opaque key request byte array is 286 * returned in *keyRequest and the number of bytes in the request is 287 * returned in *keyRequestSize. 288 * This API has same functionality as AMediaDrm_getKeyRequestWithDefaultUrlAndType() 289 * when defaultUrl and keyRequestType are passed in as NULL. 290 * 291 * After the app has received the key request response from the server, 292 * it should deliver to the response to the DRM engine plugin using the method 293 * AMediaDrm_provideKeyResponse. 294 * 295 * scope may be a sessionId or a keySetId, depending on the specified keyType. 296 * When the keyType is KEY_TYPE_STREAMING or KEY_TYPE_OFFLINE, scope should be set 297 * to the sessionId the keys will be provided to. When the keyType is 298 * KEY_TYPE_RELEASE, scope should be set to the keySetId of the keys being released. 299 * Releasing keys from a device invalidates them for all sessions. 300 * 301 * init container-specific data, its meaning is interpreted based on the mime type 302 * provided in the mimeType parameter. It could contain, for example, the content 303 * ID, key ID or other data obtained from the content metadata that is required in 304 * generating the key request. init may be null when keyType is KEY_TYPE_RELEASE. 305 * 306 * initSize is the number of bytes of initData 307 * 308 * mimeType identifies the mime type of the content. 309 * 310 * keyType specifes the type of the request. The request may be to acquire keys for 311 * streaming or offline content, or to release previously acquired keys, which are 312 * identified by a keySetId. 313 * 314 * optionalParameters are included in the key request message to allow a client 315 * application to provide additional message parameters to the server. 316 * 317 * numOptionalParameters indicates the number of optional parameters provided 318 * by the caller 319 * 320 * On exit: 321 * If this returns AMEDIA_OK, 322 * 1. The keyRequest pointer will reference the opaque key request data. It 323 * will reside in memory owned by the AMediaDrm object, and will remain 324 * accessible until the next call to AMediaDrm_getKeyRequest 325 * or AMediaDrm_getKeyRequestWithDefaultUrlAndType or until the 326 * MediaDrm object is released. 327 * 2. keyRequestSize will be set to the size of the request 328 * If this does not return AMEDIA_OK, value of these parameters should not be used. 329 * 330 * Returns MEDIADRM_NOT_PROVISIONED_ERROR if reprovisioning is needed, due to a 331 * problem with the device certificate. 332 * 333 * Available since API level 21. 334 */ 335 media_status_t AMediaDrm_getKeyRequest(AMediaDrm *, const AMediaDrmScope *scope, 336 const uint8_t *init, size_t initSize, const char *mimeType, AMediaDrmKeyType keyType, 337 const AMediaDrmKeyValue *optionalParameters, size_t numOptionalParameters, 338 const uint8_t **keyRequest, size_t *keyRequestSize) __INTRODUCED_IN(21); 339 340 /** 341 * A key request/response exchange occurs between the app and a license server 342 * to obtain or release keys used to decrypt encrypted content. 343 * AMediaDrm_getKeyRequest is used to obtain an opaque key request byte array that 344 * is delivered to the license server. The opaque key request byte array is 345 * returned in *keyRequest and the number of bytes in the request is 346 * returned in *keyRequestSize. 347 * 348 * After the app has received the key request response from the server, 349 * it should deliver to the response to the DRM engine plugin using the method 350 * AMediaDrm_provideKeyResponse. 351 * 352 * scope may be a sessionId or a keySetId, depending on the specified keyType. 353 * When the keyType is KEY_TYPE_STREAMING or KEY_TYPE_OFFLINE, scope should be set 354 * to the sessionId the keys will be provided to. When the keyType is 355 * KEY_TYPE_RELEASE, scope should be set to the keySetId of the keys being released. 356 * Releasing keys from a device invalidates them for all sessions. 357 * 358 * init container-specific data, its meaning is interpreted based on the mime type 359 * provided in the mimeType parameter. It could contain, for example, the content 360 * ID, key ID or other data obtained from the content metadata that is required in 361 * generating the key request. init may be null when keyType is KEY_TYPE_RELEASE. 362 * 363 * initSize is the number of bytes of initData 364 * 365 * mimeType identifies the mime type of the content. 366 * 367 * keyType specifes the type of the request. The request may be to acquire keys for 368 * streaming or offline content, or to release previously acquired keys, which are 369 * identified by a keySetId. 370 * 371 * optionalParameters are included in the key request message to allow a client 372 * application to provide additional message parameters to the server. 373 * 374 * numOptionalParameters indicates the number of optional parameters provided 375 * by the caller 376 * 377 * On exit: 378 * If this returns AMEDIA_OK, 379 * 1. The keyRequest pointer will reference the opaque key request data. It 380 * will reside in memory owned by the AMediaDrm object, and will remain 381 * accessible until the next call to either AMediaDrm_getKeyRequest 382 * or AMediaDrm_getKeyRequestWithDefaultUrlAndType or until the 383 * MediaDrm object is released. 384 * 2. keyRequestSize will be set to the size of the request. 385 * 3. defaultUrl will be set to the recommended URL to deliver the key request. 386 * The defaultUrl pointer will reference a NULL terminated URL string. 387 * It will be UTF-8 encoded and have same lifetime with the key request data 388 * KeyRequest pointer references to. Passing in NULL means you don't need it 389 * to be reported. 390 * 4. keyRequestType will be set to the key request type. Passing in NULL means 391 * you don't need it to be reported. 392 * 393 * Returns MEDIADRM_NOT_PROVISIONED_ERROR if reprovisioning is needed, due to a 394 * problem with the device certificate. 395 * 396 * Available since API level 33. 397 */ 398 media_status_t AMediaDrm_getKeyRequestWithDefaultUrlAndType(AMediaDrm *, 399 const AMediaDrmScope *scope, const uint8_t *init, size_t initSize, 400 const char *mimeType, AMediaDrmKeyType keyType, 401 const AMediaDrmKeyValue *optionalParameters, 402 size_t numOptionalParameters, const uint8_t **keyRequest, 403 size_t *keyRequestSize, const char **defaultUrl, 404 AMediaDrmKeyRequestType *keyRequestType) __INTRODUCED_IN(__ANDROID_API_T__); 405 406 /** 407 * A key response is received from the license server by the app, then it is 408 * provided to the DRM engine plugin using provideKeyResponse. When the 409 * response is for an offline key request, a keySetId is returned that can be 410 * used to later restore the keys to a new session with AMediaDrm_restoreKeys. 411 * When the response is for a streaming or release request, a null keySetId is 412 * returned. 413 * 414 * scope may be a sessionId or keySetId depending on the type of the 415 * response. Scope should be set to the sessionId when the response is for either 416 * streaming or offline key requests. Scope should be set to the keySetId when 417 * the response is for a release request. 418 * 419 * response points to the opaque response from the server 420 * responseSize should be set to the size of the response in bytes 421 * 422 * Available since API level 21. 423 */ 424 media_status_t AMediaDrm_provideKeyResponse(AMediaDrm *, const AMediaDrmScope *scope, 425 const uint8_t *response, size_t responseSize, 426 AMediaDrmKeySetId *keySetId) __INTRODUCED_IN(21); 427 428 /** 429 * Restore persisted offline keys into a new session. keySetId identifies the 430 * keys to load, obtained from a prior call to AMediaDrm_provideKeyResponse. 431 * 432 * sessionId is the session ID for the DRM session. 433 * keySetId identifies the saved key set to restore. 434 * 435 * Available since API level 21. 436 */ 437 media_status_t AMediaDrm_restoreKeys(AMediaDrm *, const AMediaDrmSessionId *sessionId, 438 const AMediaDrmKeySetId *keySetId) __INTRODUCED_IN(21); 439 440 /** 441 * Remove the current keys from a session. 442 * 443 * keySetId identifies keys to remove. 444 * 445 * Available since API level 21. 446 */ 447 media_status_t AMediaDrm_removeKeys(AMediaDrm *, 448 const AMediaDrmSessionId *keySetId) __INTRODUCED_IN(21); 449 450 /** 451 * Request an informative description of the key status for the session. The status is 452 * in the form of {key, value} pairs. Since DRM license policies vary by vendor, 453 * the specific status field names are determined by each DRM vendor. Refer to your 454 * DRM provider documentation for definitions of the field names for a particular 455 * DRM engine plugin. 456 * 457 * On entry, numPairs should be set by the caller to the maximum number of pairs 458 * that can be returned (the size of the array). On exit, numPairs will be set 459 * to the number of entries written to the array. If the number of {key, value} pairs 460 * to be returned is greater than *numPairs, MEDIADRM_SHORT_BUFFER will be returned 461 * and numPairs will be set to the number of pairs available. 462 * 463 * Available since API level 21. 464 */ 465 media_status_t AMediaDrm_queryKeyStatus(AMediaDrm *, const AMediaDrmSessionId *sessionId, 466 AMediaDrmKeyValue *keyValuePairs, size_t *numPairs) __INTRODUCED_IN(21); 467 468 469 /** 470 * A provision request/response exchange occurs between the app and a provisioning 471 * server to retrieve a device certificate. If provisionining is required, the 472 * EVENT_PROVISION_REQUIRED event will be sent to the event handler. 473 * getProvisionRequest is used to obtain the opaque provision request byte array that 474 * should be delivered to the provisioning server. 475 * On exit: 476 * 1. The provision request data will be referenced by provisionRequest, in 477 * memory owned by the AMediaDrm object. It will remain accessible until the 478 * next call to getProvisionRequest. 479 * 2. provisionRequestSize will be set to the size of the request data. 480 * 3. serverUrl will reference a NULL terminated string containing the URL 481 * the provisioning request should be sent to. It will remain accessible until 482 * the next call to getProvisionRequest. 483 * 484 * Available since API level 21. 485 */ 486 media_status_t AMediaDrm_getProvisionRequest(AMediaDrm *, const uint8_t **provisionRequest, 487 size_t *provisionRequestSize, const char **serverUrl) __INTRODUCED_IN(21); 488 489 490 /** 491 * After a provision response is received by the app, it is provided to the DRM 492 * engine plugin using this method. 493 * 494 * response is the opaque provisioning response byte array to provide to the 495 * DRM engine plugin. 496 * responseSize is the length of the provisioning response in bytes. 497 * 498 * Returns MEDIADRM_DEVICE_REVOKED_ERROR if the response indicates that the 499 * server rejected the request 500 * 501 * Available since API level 21. 502 */ 503 media_status_t AMediaDrm_provideProvisionResponse(AMediaDrm *, 504 const uint8_t *response, size_t responseSize) __INTRODUCED_IN(21); 505 506 507 /** 508 * A means of enforcing limits on the number of concurrent streams per subscriber 509 * across devices is provided via SecureStop. This is achieved by securely 510 * monitoring the lifetime of sessions. 511 * 512 * Information from the server related to the current playback session is written 513 * to persistent storage on the device when each MediaCrypto object is created. 514 * 515 * In the normal case, playback will be completed, the session destroyed and the 516 * Secure Stops will be queried. The app queries secure stops and forwards the 517 * secure stop message to the server which verifies the signature and notifies the 518 * server side database that the session destruction has been confirmed. The persisted 519 * record on the client is only removed after positive confirmation that the server 520 * received the message using releaseSecureStops(). 521 * 522 * numSecureStops is set by the caller to the maximum number of secure stops to 523 * return. On exit, *numSecureStops will be set to the number actually returned. 524 * If *numSecureStops is too small for the number of secure stops available, 525 * MEDIADRM_SHORT_BUFFER will be returned and *numSecureStops will be set to the 526 * number required. 527 * 528 * Available since API level 21. 529 */ 530 media_status_t AMediaDrm_getSecureStops(AMediaDrm *, 531 AMediaDrmSecureStop *secureStops, size_t *numSecureStops) __INTRODUCED_IN(21); 532 533 /** 534 * Process the SecureStop server response message ssRelease. After authenticating 535 * the message, remove the SecureStops identified in the response. 536 * 537 * ssRelease is the server response indicating which secure stops to release 538 * 539 * Available since API level 21. 540 */ 541 media_status_t AMediaDrm_releaseSecureStops(AMediaDrm *, 542 const AMediaDrmSecureStop *ssRelease) __INTRODUCED_IN(21); 543 544 /** 545 * String property name: identifies the maker of the DRM engine plugin 546 */ 547 #define PROPERTY_VENDOR "vendor" 548 549 /** 550 * String property name: identifies the version of the DRM engine plugin 551 */ 552 #define PROPERTY_VERSION "version" 553 554 /** 555 * String property name: describes the DRM engine plugin 556 */ 557 #define PROPERTY_DESCRIPTION "description" 558 559 /** 560 * String property name: a comma-separated list of cipher and mac algorithms 561 * supported by CryptoSession. The list may be empty if the DRM engine 562 * plugin does not support CryptoSession operations. 563 */ 564 #define PROPERTY_ALGORITHMS "algorithms" 565 566 /** 567 * Read a DRM engine plugin String property value, given the property name string. 568 * 569 * propertyName identifies the property to query 570 * On return, propertyValue will be set to point to the property value. The 571 * memory that the value resides in is owned by the NDK MediaDrm API and 572 * will remain valid until the next call to AMediaDrm_getPropertyString. 573 * 574 * Available since API level 21. 575 */ 576 media_status_t AMediaDrm_getPropertyString(AMediaDrm *, const char *propertyName, 577 const char **propertyValue) __INTRODUCED_IN(21); 578 579 /** 580 * Byte array property name: the device unique identifier is established during 581 * device provisioning and provides a means of uniquely identifying each device. 582 */ 583 #define PROPERTY_DEVICE_UNIQUE_ID "deviceUniqueId" 584 585 /** 586 * Read a DRM engine plugin byte array property value, given the property name string. 587 * On return, *propertyValue will be set to point to the property value. The 588 * memory that the value resides in is owned by the NDK MediaDrm API and 589 * will remain valid until the next call to AMediaDrm_getPropertyByteArray. 590 * 591 * Available since API level 21. 592 */ 593 media_status_t AMediaDrm_getPropertyByteArray(AMediaDrm *, const char *propertyName, 594 AMediaDrmByteArray *propertyValue) __INTRODUCED_IN(21); 595 596 /** 597 * Set a DRM engine plugin String property value. 598 * 599 * Available since API level 21. 600 */ 601 media_status_t AMediaDrm_setPropertyString(AMediaDrm *, const char *propertyName, 602 const char *value) __INTRODUCED_IN(21); 603 604 /** 605 * Set a DRM engine plugin byte array property value. 606 * 607 * Available since API level 21. 608 */ 609 media_status_t AMediaDrm_setPropertyByteArray(AMediaDrm *, const char *propertyName, 610 const uint8_t *value, size_t valueSize) __INTRODUCED_IN(21); 611 612 /** 613 * In addition to supporting decryption of DASH Common Encrypted Media, the 614 * MediaDrm APIs provide the ability to securely deliver session keys from 615 * an operator's session key server to a client device, based on the factory-installed 616 * root of trust, and then perform encrypt, decrypt, sign and verify operations 617 * with the session key on arbitrary user data. 618 * 619 * Operators create session key servers that receive session key requests and provide 620 * encrypted session keys which can be used for general purpose crypto operations. 621 * 622 * Generic encrypt/decrypt/sign/verify methods are based on the established session 623 * keys. These keys are exchanged using the getKeyRequest/provideKeyResponse methods. 624 * 625 * Applications of this capability include securing various types of purchased or 626 * private content, such as applications, books and other media, photos or media 627 * delivery protocols. 628 */ 629 630 /* 631 * Encrypt the data referenced by input of length dataSize using algorithm specified 632 * by cipherAlgorithm, and write the encrypted result into output. The caller must 633 * ensure that the output buffer is large enough to accept dataSize bytes. The key 634 * to use is identified by the 16 byte keyId. The key must have been loaded into 635 * the session using provideKeyResponse. 636 * 637 * Available since API level 21. 638 */ 639 media_status_t AMediaDrm_encrypt(AMediaDrm *, const AMediaDrmSessionId *sessionId, 640 const char *cipherAlgorithm, uint8_t *keyId, uint8_t *iv, 641 const uint8_t *input, uint8_t *output, size_t dataSize) __INTRODUCED_IN(21); 642 643 /* 644 * Decrypt the data referenced by input of length dataSize using algorithm specified 645 * by cipherAlgorithm, and write the decrypted result into output. The caller must 646 * ensure that the output buffer is large enough to accept dataSize bytes. The key 647 * to use is identified by the 16 byte keyId. The key must have been loaded into 648 * the session using provideKeyResponse. 649 * 650 * Available since API level 21. 651 */ 652 media_status_t AMediaDrm_decrypt(AMediaDrm *, const AMediaDrmSessionId *sessionId, 653 const char *cipherAlgorithm, uint8_t *keyId, uint8_t *iv, 654 const uint8_t *input, uint8_t *output, size_t dataSize) __INTRODUCED_IN(21); 655 656 /* 657 * Generate a signature using the specified macAlgorithm over the message data 658 * referenced by message of size messageSize and store the signature in the 659 * buffer referenced signature of max size *signatureSize. If the buffer is not 660 * large enough to hold the signature, MEDIADRM_SHORT_BUFFER is returned and 661 * *signatureSize is set to the buffer size required. The key to use is identified 662 * by the 16 byte keyId. The key must have been loaded into the session using 663 * provideKeyResponse. 664 * 665 * Available since API level 21. 666 */ 667 media_status_t AMediaDrm_sign(AMediaDrm *, const AMediaDrmSessionId *sessionId, 668 const char *macAlgorithm, uint8_t *keyId, uint8_t *message, size_t messageSize, 669 uint8_t *signature, size_t *signatureSize) __INTRODUCED_IN(21); 670 671 /* 672 * Perform a signature verification using the specified macAlgorithm over the message 673 * data referenced by the message parameter of size messageSize. Returns MEDIADRM_OK 674 * if the signature matches, otherwise MEDAIDRM_VERIFY_FAILED is returned. The key to 675 * use is identified by the 16 byte keyId. The key must have been loaded into the 676 * session using provideKeyResponse. 677 * 678 * Available since API level 21. 679 */ 680 media_status_t AMediaDrm_verify(AMediaDrm *, const AMediaDrmSessionId *sessionId, 681 const char *macAlgorithm, uint8_t *keyId, const uint8_t *message, size_t messageSize, 682 const uint8_t *signature, size_t signatureSize) __INTRODUCED_IN(21); 683 684 __END_DECLS 685 686 #endif //_NDK_MEDIA_DRM_H 687 688 /** @} */ 689