/*
|
* Copyright (C) 2014 The Android Open Source Project
|
*
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
* you may not use this file except in compliance with the License.
|
* You may obtain a copy of the License at
|
*
|
* http://www.apache.org/licenses/LICENSE-2.0
|
*
|
* Unless required by applicable law or agreed to in writing, software
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
* See the License for the specific language governing permissions and
|
* limitations under the License.
|
*/
|
|
/*
|
* This file defines an NDK API.
|
* Do not remove methods.
|
* Do not change method signatures.
|
* Do not change the value of constants.
|
* Do not change the size of any of the classes defined in here.
|
* Do not reference types that are not part of the NDK.
|
* Do not #include files that aren't part of the NDK.
|
*/
|
|
#ifndef _NDK_MEDIA_DRM_H
|
#define _NDK_MEDIA_DRM_H
|
|
#include "NdkMediaError.h"
|
|
#ifdef __cplusplus
|
extern "C" {
|
#endif
|
|
#include <stdint.h>
|
#include <stdbool.h>
|
|
struct AMediaDrm;
|
typedef struct AMediaDrm AMediaDrm;
|
|
typedef struct {
|
const uint8_t *ptr;
|
size_t length;
|
} AMediaDrmByteArray;
|
|
typedef AMediaDrmByteArray AMediaDrmSessionId;
|
typedef AMediaDrmByteArray AMediaDrmScope;
|
typedef AMediaDrmByteArray AMediaDrmKeySetId;
|
typedef AMediaDrmByteArray AMediaDrmSecureStop;
|
|
|
typedef enum AMediaDrmEventType {
|
/**
|
* This event type indicates that the app needs to request a certificate from
|
* the provisioning server. The request message data is obtained using
|
* AMediaDrm_getProvisionRequest.
|
*/
|
EVENT_PROVISION_REQUIRED = 1,
|
|
/**
|
* This event type indicates that the app needs to request keys from a license
|
* server. The request message data is obtained using AMediaDrm_getKeyRequest.
|
*/
|
EVENT_KEY_REQUIRED = 2,
|
|
/**
|
* This event type indicates that the licensed usage duration for keys in a session
|
* has expired. The keys are no longer valid.
|
*/
|
EVENT_KEY_EXPIRED = 3,
|
|
/**
|
* This event may indicate some specific vendor-defined condition, see your
|
* DRM provider documentation for details
|
*/
|
EVENT_VENDOR_DEFINED = 4
|
} AMediaDrmEventType;
|
|
typedef void (*AMediaDrmEventListener)(AMediaDrm *, const AMediaDrmSessionId *sessionId,
|
AMediaDrmEventType eventType, int extra, const uint8_t *data, size_t dataSize);
|
|
|
/**
|
* Query if the given scheme identified by its UUID is supported on this device, and
|
* whether the drm plugin is able to handle the media container format specified by mimeType.
|
*
|
* uuid identifies the universal unique ID of the crypto scheme. uuid must be 16 bytes.
|
* mimeType is the MIME type of the media container, e.g. "video/mp4". If mimeType
|
* is not known or required, it can be provided as NULL.
|
*/
|
bool AMediaDrm_isCryptoSchemeSupported(const uint8_t *uuid, const char *mimeType);
|
|
/**
|
* Create a MediaDrm instance from a UUID
|
* uuid identifies the universal unique ID of the crypto scheme. uuid must be 16 bytes.
|
*/
|
AMediaDrm* AMediaDrm_createByUUID(const uint8_t *uuid);
|
|
/**
|
* Release a MediaDrm object
|
*/
|
void AMediaDrm_release(AMediaDrm *);
|
|
/**
|
* Register a callback to be invoked when an event occurs
|
*
|
* listener is the callback that will be invoked on event
|
*/
|
media_status_t AMediaDrm_setOnEventListener(AMediaDrm *, AMediaDrmEventListener listener);
|
|
/**
|
* Open a new session with the MediaDrm object. A session ID is returned.
|
*
|
* returns MEDIADRM_NOT_PROVISIONED_ERROR if provisioning is needed
|
* returns MEDIADRM_RESOURCE_BUSY_ERROR if required resources are in use
|
*/
|
media_status_t AMediaDrm_openSession(AMediaDrm *, AMediaDrmSessionId *sessionId);
|
|
/**
|
* Close a session on the MediaDrm object that was previously opened
|
* with AMediaDrm_openSession.
|
*/
|
media_status_t AMediaDrm_closeSession(AMediaDrm *, const AMediaDrmSessionId *sessionId);
|
|
typedef enum AMediaDrmKeyType {
|
/**
|
* This key request type species that the keys will be for online use, they will
|
* not be saved to the device for subsequent use when the device is not connected
|
* to a network.
|
*/
|
KEY_TYPE_STREAMING = 1,
|
|
/**
|
* This key request type specifies that the keys will be for offline use, they
|
* will be saved to the device for use when the device is not connected to a network.
|
*/
|
KEY_TYPE_OFFLINE = 2,
|
|
/**
|
* This key request type specifies that previously saved offline keys should be released.
|
*/
|
KEY_TYPE_RELEASE = 3
|
} AMediaDrmKeyType;
|
|
/**
|
* Data type containing {key, value} pair
|
*/
|
typedef struct AMediaDrmKeyValuePair {
|
const char *mKey;
|
const char *mValue;
|
} AMediaDrmKeyValue;
|
|
/**
|
* A key request/response exchange occurs between the app and a license server
|
* to obtain or release keys used to decrypt encrypted content.
|
* AMediaDrm_getKeyRequest is used to obtain an opaque key request byte array that
|
* is delivered to the license server. The opaque key request byte array is
|
* returned in KeyRequest.data. The recommended URL to deliver the key request to
|
* is returned in KeyRequest.defaultUrl.
|
*
|
* After the app has received the key request response from the server,
|
* it should deliver to the response to the DRM engine plugin using the method
|
* AMediaDrm_provideKeyResponse.
|
*
|
* scope may be a sessionId or a keySetId, depending on the specified keyType.
|
* When the keyType is KEY_TYPE_STREAMING or KEY_TYPE_OFFLINE, scope should be set
|
* to the sessionId the keys will be provided to. When the keyType is
|
* KEY_TYPE_RELEASE, scope should be set to the keySetId of the keys being released.
|
* Releasing keys from a device invalidates them for all sessions.
|
*
|
* init container-specific data, its meaning is interpreted based on the mime type
|
* provided in the mimeType parameter. It could contain, for example, the content
|
* ID, key ID or other data obtained from the content metadata that is required in
|
* generating the key request. init may be null when keyType is KEY_TYPE_RELEASE.
|
*
|
* initSize is the number of bytes of initData
|
*
|
* mimeType identifies the mime type of the content.
|
*
|
* keyType specifes the type of the request. The request may be to acquire keys for
|
* streaming or offline content, or to release previously acquired keys, which are
|
* identified by a keySetId.
|
*
|
* optionalParameters are included in the key request message to allow a client
|
* application to provide additional message parameters to the server.
|
*
|
* numOptionalParameters indicates the number of optional parameters provided
|
* by the caller
|
*
|
* On exit:
|
* 1. The keyRequest pointer will reference the opaque key request data. It
|
* will reside in memory owned by the AMediaDrm object, and will remain
|
* accessible until the next call to AMediaDrm_getKeyRequest or until the
|
* MediaDrm object is released.
|
* 2. keyRequestSize will be set to the size of the request
|
*
|
* returns MEDIADRM_NOT_PROVISIONED_ERROR if reprovisioning is needed, due to a
|
* problem with the device certificate.
|
*/
|
media_status_t AMediaDrm_getKeyRequest(AMediaDrm *, const AMediaDrmScope *scope,
|
const uint8_t *init, size_t initSize, const char *mimeType, AMediaDrmKeyType keyType,
|
const AMediaDrmKeyValue *optionalParameters, size_t numOptionalParameters,
|
const uint8_t **keyRequest, size_t *keyRequestSize);
|
|
/**
|
* A key response is received from the license server by the app, then it is
|
* provided to the DRM engine plugin using provideKeyResponse. When the
|
* response is for an offline key request, a keySetId is returned that can be
|
* used to later restore the keys to a new session with AMediaDrm_restoreKeys.
|
* When the response is for a streaming or release request, a null keySetId is
|
* returned.
|
*
|
* scope may be a sessionId or keySetId depending on the type of the
|
* response. Scope should be set to the sessionId when the response is for either
|
* streaming or offline key requests. Scope should be set to the keySetId when
|
* the response is for a release request.
|
*
|
* response points to the opaque response from the server
|
* responseSize should be set to the size of the response in bytes
|
*/
|
|
media_status_t AMediaDrm_provideKeyResponse(AMediaDrm *, const AMediaDrmScope *scope,
|
const uint8_t *response, size_t responseSize, AMediaDrmKeySetId *keySetId);
|
|
/**
|
* Restore persisted offline keys into a new session. keySetId identifies the
|
* keys to load, obtained from a prior call to AMediaDrm_provideKeyResponse.
|
*
|
* sessionId is the session ID for the DRM session
|
* keySetId identifies the saved key set to restore
|
*/
|
media_status_t AMediaDrm_restoreKeys(AMediaDrm *, const AMediaDrmSessionId *sessionId,
|
const AMediaDrmKeySetId *keySetId);
|
|
/**
|
* Remove the current keys from a session.
|
*
|
* keySetId identifies keys to remove
|
*/
|
media_status_t AMediaDrm_removeKeys(AMediaDrm *, const AMediaDrmSessionId *keySetId);
|
|
/**
|
* Request an informative description of the key status for the session. The status is
|
* in the form of {key, value} pairs. Since DRM license policies vary by vendor,
|
* the specific status field names are determined by each DRM vendor. Refer to your
|
* DRM provider documentation for definitions of the field names for a particular
|
* DRM engine plugin.
|
*
|
* On entry, numPairs should be set by the caller to the maximum number of pairs
|
* that can be returned (the size of the array). On exit, numPairs will be set
|
* to the number of entries written to the array. If the number of {key, value} pairs
|
* to be returned is greater than *numPairs, MEDIADRM_SHORT_BUFFER will be returned
|
* and numPairs will be set to the number of pairs available.
|
*/
|
media_status_t AMediaDrm_queryKeyStatus(AMediaDrm *, const AMediaDrmSessionId *sessionId,
|
AMediaDrmKeyValue *keyValuePairs, size_t *numPairs);
|
|
|
/**
|
* A provision request/response exchange occurs between the app and a provisioning
|
* server to retrieve a device certificate. If provisionining is required, the
|
* EVENT_PROVISION_REQUIRED event will be sent to the event handler.
|
* getProvisionRequest is used to obtain the opaque provision request byte array that
|
* should be delivered to the provisioning server.
|
* On exit:
|
* 1. The provision request data will be referenced by provisionRequest, in
|
* memory owned by the AMediaDrm object. It will remain accessible until the
|
* next call to getProvisionRequest.
|
* 2. provisionRequestSize will be set to the size of the request data.
|
* 3. serverUrl will reference a NULL terminated string containing the URL
|
* the provisioning request should be sent to. It will remain accessible until
|
* the next call to getProvisionRequest.
|
*/
|
media_status_t AMediaDrm_getProvisionRequest(AMediaDrm *, const uint8_t **provisionRequest,
|
size_t *provisionRequestSize, const char **serverUrl);
|
|
|
/**
|
* After a provision response is received by the app, it is provided to the DRM
|
* engine plugin using this method.
|
*
|
* response is the opaque provisioning response byte array to provide to the
|
* DRM engine plugin.
|
* responseSize is the length of the provisioning response in bytes.
|
*
|
* returns MEDIADRM_DEVICE_REVOKED_ERROR if the response indicates that the
|
* server rejected the request
|
*/
|
media_status_t AMediaDrm_provideProvisionResponse(AMediaDrm *,
|
const uint8_t *response, size_t responseSize);
|
|
|
/**
|
* A means of enforcing limits on the number of concurrent streams per subscriber
|
* across devices is provided via SecureStop. This is achieved by securely
|
* monitoring the lifetime of sessions.
|
*
|
* Information from the server related to the current playback session is written
|
* to persistent storage on the device when each MediaCrypto object is created.
|
*
|
* In the normal case, playback will be completed, the session destroyed and the
|
* Secure Stops will be queried. The app queries secure stops and forwards the
|
* secure stop message to the server which verifies the signature and notifies the
|
* server side database that the session destruction has been confirmed. The persisted
|
* record on the client is only removed after positive confirmation that the server
|
* received the message using releaseSecureStops().
|
*
|
* numSecureStops is set by the caller to the maximum number of secure stops to
|
* return. On exit, *numSecureStops will be set to the number actually returned.
|
* If *numSecureStops is too small for the number of secure stops available,
|
* MEDIADRM_SHORT_BUFFER will be returned and *numSecureStops will be set to the
|
* number required.
|
*/
|
media_status_t AMediaDrm_getSecureStops(AMediaDrm *,
|
AMediaDrmSecureStop *secureStops, size_t *numSecureStops);
|
|
/**
|
* Process the SecureStop server response message ssRelease. After authenticating
|
* the message, remove the SecureStops identified in the response.
|
*
|
* ssRelease is the server response indicating which secure stops to release
|
*/
|
media_status_t AMediaDrm_releaseSecureStops(AMediaDrm *,
|
const AMediaDrmSecureStop *ssRelease);
|
|
/**
|
* String property name: identifies the maker of the DRM engine plugin
|
*/
|
const char *PROPERTY_VENDOR = "vendor";
|
|
/**
|
* String property name: identifies the version of the DRM engine plugin
|
*/
|
const char *PROPERTY_VERSION = "version";
|
|
/**
|
* String property name: describes the DRM engine plugin
|
*/
|
const char *PROPERTY_DESCRIPTION = "description";
|
|
/**
|
* String property name: a comma-separated list of cipher and mac algorithms
|
* supported by CryptoSession. The list may be empty if the DRM engine
|
* plugin does not support CryptoSession operations.
|
*/
|
const char *PROPERTY_ALGORITHMS = "algorithms";
|
|
/**
|
* Read a DRM engine plugin String property value, given the property name string.
|
*
|
* propertyName identifies the property to query
|
* On return, propertyValue will be set to point to the property value. The
|
* memory that the value resides in is owned by the NDK MediaDrm API and
|
* will remain valid until the next call to AMediaDrm_getPropertyString.
|
*/
|
media_status_t AMediaDrm_getPropertyString(AMediaDrm *, const char *propertyName,
|
const char **propertyValue);
|
|
/**
|
* Byte array property name: the device unique identifier is established during
|
* device provisioning and provides a means of uniquely identifying each device.
|
*/
|
const char *PROPERTY_DEVICE_UNIQUE_ID = "deviceUniqueId";
|
|
/**
|
* Read a DRM engine plugin byte array property value, given the property name string.
|
* On return, *propertyValue will be set to point to the property value. The
|
* memory that the value resides in is owned by the NDK MediaDrm API and
|
* will remain valid until the next call to AMediaDrm_getPropertyByteArray.
|
*/
|
media_status_t AMediaDrm_getPropertyByteArray(AMediaDrm *, const char *propertyName,
|
AMediaDrmByteArray *propertyValue);
|
|
/**
|
* Set a DRM engine plugin String property value.
|
*/
|
media_status_t AMediaDrm_setPropertyString(AMediaDrm *, const char *propertyName,
|
const char *value);
|
|
/**
|
* Set a DRM engine plugin byte array property value.
|
*/
|
media_status_t AMediaDrm_setPropertyByteArray(AMediaDrm *, const char *propertyName,
|
const uint8_t *value, size_t valueSize);
|
|
/**
|
* In addition to supporting decryption of DASH Common Encrypted Media, the
|
* MediaDrm APIs provide the ability to securely deliver session keys from
|
* an operator's session key server to a client device, based on the factory-installed
|
* root of trust, and then perform encrypt, decrypt, sign and verify operations
|
* with the session key on arbitrary user data.
|
*
|
* Operators create session key servers that receive session key requests and provide
|
* encrypted session keys which can be used for general purpose crypto operations.
|
*
|
* Generic encrypt/decrypt/sign/verify methods are based on the established session
|
* keys. These keys are exchanged using the getKeyRequest/provideKeyResponse methods.
|
*
|
* Applications of this capability include securing various types of purchased or
|
* private content, such as applications, books and other media, photos or media
|
* delivery protocols.
|
*/
|
|
/*
|
* Encrypt the data referenced by input of length dataSize using algorithm specified
|
* by cipherAlgorithm, and write the encrypted result into output. The caller must
|
* ensure that the output buffer is large enough to accept dataSize bytes. The key
|
* to use is identified by the 16 byte keyId. The key must have been loaded into
|
* the session using provideKeyResponse.
|
*/
|
media_status_t AMediaDrm_encrypt(AMediaDrm *, const AMediaDrmSessionId *sessionId,
|
const char *cipherAlgorithm, uint8_t *keyId, uint8_t *iv,
|
const uint8_t *input, uint8_t *output, size_t dataSize);
|
|
/*
|
* Decrypt the data referenced by input of length dataSize using algorithm specified
|
* by cipherAlgorithm, and write the decrypted result into output. The caller must
|
* ensure that the output buffer is large enough to accept dataSize bytes. The key
|
* to use is identified by the 16 byte keyId. The key must have been loaded into
|
* the session using provideKeyResponse.
|
*/
|
media_status_t AMediaDrm_decrypt(AMediaDrm *, const AMediaDrmSessionId *sessionId,
|
const char *cipherAlgorithm, uint8_t *keyId, uint8_t *iv,
|
const uint8_t *input, uint8_t *output, size_t dataSize);
|
|
/*
|
* Generate a signature using the specified macAlgorithm over the message data
|
* referenced by message of size messageSize and store the signature in the
|
* buffer referenced signature of max size *signatureSize. If the buffer is not
|
* large enough to hold the signature, MEDIADRM_SHORT_BUFFER is returned and
|
* *signatureSize is set to the buffer size required. The key to use is identified
|
* by the 16 byte keyId. The key must have been loaded into the session using
|
* provideKeyResponse.
|
*/
|
media_status_t AMediaDrm_sign(AMediaDrm *, const AMediaDrmSessionId *sessionId,
|
const char *macAlgorithm, uint8_t *keyId, uint8_t *message, size_t messageSize,
|
uint8_t *signature, size_t *signatureSize);
|
|
/*
|
* Perform a signature verification using the specified macAlgorithm over the message
|
* data referenced by the message parameter of size messageSize. Returns MEDIADRM_OK
|
* if the signature matches, otherwise MEDAIDRM_VERIFY_FAILED is returned. The key to
|
* use is identified by the 16 byte keyId. The key must have been loaded into the
|
* session using provideKeyResponse.
|
*/
|
media_status_t AMediaDrm_verify(AMediaDrm *, const AMediaDrmSessionId *sessionId,
|
const char *macAlgorithm, uint8_t *keyId, const uint8_t *message, size_t messageSize,
|
const uint8_t *signature, size_t signatureSize);
|
|
#ifdef __cplusplus
|
} // extern "C"
|
#endif
|
|
#endif //_NDK_MEDIA_DRM_H
|
