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