From bcbd78bd246f1e68e44b4a6d6257dbfcec8e65b3 Mon Sep 17 00:00:00 2001 From: Jeff Tinker Date: Sat, 30 Mar 2013 16:28:20 -0700 Subject: [PATCH] MediaDrm API update Clarify offline usage of sessions and keys and implement implement CryptoSession to support additional crypto use cases. Change-Id: I418ffbb37e3036a2b5eea5a86ac88a5af1a9da07 --- include/media/drm/DrmAPI.h | 133 ++++++++++++++++++++++++++++--------- 1 file changed, 100 insertions(+), 33 deletions(-) diff --git a/include/media/drm/DrmAPI.h b/include/media/drm/DrmAPI.h index 77da0bfa9..81d1ec02d 100644 --- a/include/media/drm/DrmAPI.h +++ b/include/media/drm/DrmAPI.h @@ -1,4 +1,4 @@ - /* +/* * Copyright (C) 2013 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); @@ -71,17 +71,17 @@ namespace android { public: enum EventType { kDrmPluginEventProvisionRequired, - kDrmPluginEventLicenseNeeded, - kDrmPluginEventLicenseExpired, + kDrmPluginEventKeyNeeded, + kDrmPluginEventKeyExpired, kDrmPluginEventVendorDefined }; - // A license can be for offline content or for online streaming. - // Offline licenses are persisted on the device and may be used when the device + // Drm keys can be for offline content or for online streaming. + // Offline keys are persisted on the device and may be used when the device // is disconnected from the network. - enum LicenseType { - kLicenseType_Offline, - kLicenseType_Streaming + enum KeyType { + kKeyType_Offline, + kKeyType_Streaming }; DrmPlugin() {} @@ -94,38 +94,45 @@ namespace android { // Close a session on the DrmPlugin object. virtual status_t closeSession(Vector const &sessionId) = 0; - // A license request/response exchange occurs between the app and a License - // Server to obtain the keys required to decrypt the content. getLicenseRequest() - // is used to obtain an opaque license request blob that is delivered to the + // A key request/response exchange occurs between the app and a License + // Server to obtain the keys required to decrypt the content. getKeyRequest() + // is used to obtain an opaque key request blob that is delivered to the // license server. // - // The init data passed to getLicenseRequest is container-specific and its + // The init data passed to getKeyRequest is container-specific and its // meaning is interpreted based on the mime type provided in the mimeType - // parameter to getLicenseRequest. It could contain, for example, the content + // parameter to getKeyRequest. It could contain, for example, the content // ID, key ID or other data obtained from the content metadata that is required - // in generating the license request. + // in generating the key request. // - // licenseType specifes if the license is for streaming or offline content + // keyType specifes if the keys are to be used for streaming or offline content // - // optionalParameters are included in the license server request message to - // allow a client application to provide additional message parameters to the - // server. + // optionalParameters are included in the key request message to allow a + // client application to provide additional message parameters to the server. // - // If successful, the opaque license request blob is returned to the caller. + // If successful, the opaque key request blob is returned to the caller. virtual status_t - getLicenseRequest(Vector const &sessionId, - Vector const &initData, - String8 const &mimeType, LicenseType licenseType, - KeyedVector const &optionalParameters, - Vector &request, String8 &defaultUrl) = 0; + getKeyRequest(Vector const &sessionId, + Vector const &initData, + String8 const &mimeType, KeyType keyType, + KeyedVector const &optionalParameters, + Vector &request, String8 &defaultUrl) = 0; - // After a license response is received by the app, it is provided to the - // Drm plugin using provideLicenseResponse. - virtual status_t provideLicenseResponse(Vector const &sessionId, - Vector const &response) = 0; + // After a key response is received by the app, it is provided to the + // Drm plugin using provideKeyResponse. Returns the id of the key set + // in keySetId. The keySetId can be used by removeKeys or restoreKeys + // when the keys are used for offline content. + virtual status_t provideKeyResponse(Vector const &sessionId, + Vector const &response, + Vector &keySetId) = 0; - // Remove the keys associated with a license. - virtual status_t removeLicense(Vector const &sessionId) = 0; + // Remove the persisted keys associated with an offline license for a session. + virtual status_t removeKeys(Vector const &keySetId) = 0; + + // Restore persisted offline keys into a new session. keySetId identifies + // the keys to load, obtained from a prior call to provideKeyResponse(). + virtual status_t restoreKeys(Vector const &sessionId, + Vector const &keySetId) = 0; // Request an informative description of the license for the session. The status // is in the form of {name, value} pairs. Since DRM license policies vary by @@ -133,12 +140,12 @@ namespace android { // Refer to your DRM provider documentation for definitions of the field names // for a particular DrmEngine. virtual status_t - queryLicenseStatus(Vector const &sessionId, - KeyedVector &infoMap) const = 0; + queryKeyStatus(Vector const &sessionId, + KeyedVector &infoMap) const = 0; // A provision request/response exchange occurs between the app and a // provisioning server to retrieve a device certificate. getProvisionRequest - // is used to obtain an opaque license request blob that is delivered to the + // is used to obtain an opaque key request blob that is delivered to the // provisioning server. // // If successful, the opaque provision request blob is returned to the caller. @@ -195,6 +202,66 @@ namespace android { virtual status_t setPropertyByteArray(String8 const &name, Vector const &value ) = 0; + // The following methods implement operations on a CryptoSession to support + // encrypt, decrypt, sign verify operations on operator-provided + // session keys. + + // + // The algorithm string conforms to JCA Standard Names for Cipher + // Transforms and is case insensitive. For example "AES/CBC/PKCS5Padding". + // + // Return OK if the algorithm is supported, otherwise return BAD_VALUE + // + virtual status_t setCipherAlgorithm(Vector const &sessionId, + String8 const &algorithm) = 0; + + // + // The algorithm string conforms to JCA Standard Names for Mac + // Algorithms and is case insensitive. For example "HmacSHA256". + // + // Return OK if the algorithm is supported, otherwise return BAD_VALUE + // + virtual status_t setMacAlgorithm(Vector const &sessionId, + String8 const &algorithm) = 0; + + // Encrypt the provided input buffer with the cipher algorithm + // specified by setCipherAlgorithm and the key selected by keyId, + // and return the encrypted data. + virtual status_t encrypt(Vector const &sessionId, + Vector const &keyId, + Vector const &input, + Vector const &iv, + Vector &output) = 0; + + // Decrypt the provided input buffer with the cipher algorithm + // specified by setCipherAlgorithm and the key selected by keyId, + // and return the decrypted data. + virtual status_t decrypt(Vector const &sessionId, + Vector const &keyId, + Vector const &input, + Vector const &iv, + Vector &output) = 0; + + // Compute a signature on the provided message using the mac algorithm + // specified by setMacAlgorithm and the key selected by keyId, + // and return the signature. + virtual status_t sign(Vector const &sessionId, + Vector const &keyId, + Vector const &message, + Vector &signature) = 0; + + // Compute a signature on the provided message using the mac algorithm + // specified by setMacAlgorithm and the key selected by keyId, + // and compare with the expected result. Set result to true or + // false depending on the outcome. + virtual status_t verify(Vector const &sessionId, + Vector const &keyId, + Vector const &message, + Vector const &signature, + bool &match) = 0; + + + // TODO: provide way to send an event private: DISALLOW_EVIL_CONSTRUCTORS(DrmPlugin);