DrmAPI.h revision 56c78c47d8c22621a8a23375d8a6c63d99a9335d
1 /* 2 * Copyright (C) 2013 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#ifndef DRM_API_H_ 18#define DRM_API_H_ 19 20#include <utils/List.h> 21#include <utils/String8.h> 22#include <utils/Vector.h> 23#include <utils/KeyedVector.h> 24#include <utils/RefBase.h> 25#include <media/stagefright/foundation/ABase.h> 26 27// Loadable DrmEngine shared libraries should define the entry points 28// createDrmFactory and createCryptoFactory as shown below: 29// 30// extern "C" { 31// extern android::DrmFactory *createDrmFactory(); 32// extern android::CryptoFactory *createCryptoFactory(); 33// } 34 35namespace android { 36 37 struct DrmPlugin; 38 39 // DRMs are implemented in DrmEngine plugins, which are dynamically 40 // loadable shared libraries that implement the entry points 41 // createDrmFactory and createCryptoFactory. createDrmFactory 42 // constructs and returns an instance of a DrmFactory object. Similarly, 43 // createCryptoFactory creates an instance of a CryptoFactory object. 44 // When a MediaCrypto or MediaDrm object needs to be constructed, all 45 // available DrmEngines present in the plugins directory on the device 46 // are scanned for a matching DrmEngine that can support the crypto 47 // scheme. When a match is found, the DrmEngine's createCryptoPlugin and 48 // createDrmPlugin methods are used to create CryptoPlugin or 49 // DrmPlugin instances to support that DRM scheme. 50 51 class DrmFactory { 52 public: 53 DrmFactory() {} 54 virtual ~DrmFactory() {} 55 56 // DrmFactory::isCryptoSchemeSupported can be called to determine 57 // if the plugin factory is able to construct plugins that support a 58 // given crypto scheme, which is specified by a UUID. 59 virtual bool isCryptoSchemeSupported(const uint8_t uuid[16]) = 0; 60 61 // Construct a DrmPlugin for the crypto scheme specified by UUID. 62 virtual status_t createDrmPlugin( 63 const uint8_t uuid[16], DrmPlugin **plugin) = 0; 64 65 private: 66 DrmFactory(const DrmFactory &); 67 DrmFactory &operator=(const DrmFactory &); 68 }; 69 70 class DrmPlugin { 71 public: 72 enum EventType { 73 kDrmPluginEventProvisionRequired, 74 kDrmPluginEventLicenseNeeded, 75 kDrmPluginEventLicenseExpired, 76 kDrmPluginEventVendorDefined 77 }; 78 79 // A license can be for offline content or for online streaming. 80 // Offline licenses are persisted on the device and may be used when the device 81 // is disconnected from the network. 82 enum LicenseType { 83 kLicenseType_Offline, 84 kLicenseType_Streaming 85 }; 86 87 DrmPlugin() {} 88 virtual ~DrmPlugin() {} 89 90 // Open a new session with the DrmPlugin object. A session ID is returned 91 // in the sessionId parameter. 92 virtual status_t openSession(Vector<uint8_t> &sessionId) = 0; 93 94 // Close a session on the DrmPlugin object. 95 virtual status_t closeSession(Vector<uint8_t> const &sessionId) = 0; 96 97 // A license request/response exchange occurs between the app and a License 98 // Server to obtain the keys required to decrypt the content. getLicenseRequest() 99 // is used to obtain an opaque license request blob that is delivered to the 100 // license server. 101 // 102 // The init data passed to getLicenseRequest is container-specific and its 103 // meaning is interpreted based on the mime type provided in the mimeType 104 // parameter to getLicenseRequest. It could contain, for example, the content 105 // ID, key ID or other data obtained from the content metadata that is required 106 // in generating the license request. 107 // 108 // licenseType specifes if the license is for streaming or offline content 109 // 110 // optionalParameters are included in the license server request message to 111 // allow a client application to provide additional message parameters to the 112 // server. 113 // 114 // If successful, the opaque license request blob is returned to the caller. 115 virtual status_t 116 getLicenseRequest(Vector<uint8_t> const &sessionId, 117 Vector<uint8_t> const &initData, 118 String8 const &mimeType, LicenseType licenseType, 119 KeyedVector<String8, String8> const &optionalParameters, 120 Vector<uint8_t> &request, String8 &defaultUrl) = 0; 121 122 // After a license response is received by the app, it is provided to the 123 // Drm plugin using provideLicenseResponse. 124 virtual status_t provideLicenseResponse(Vector<uint8_t> const &sessionId, 125 Vector<uint8_t> const &response) = 0; 126 127 // Remove the keys associated with a license. 128 virtual status_t removeLicense(Vector<uint8_t> const &sessionId) = 0; 129 130 // Request an informative description of the license for the session. The status 131 // is in the form of {name, value} pairs. Since DRM license policies vary by 132 // vendor, the specific status field names are determined by each DRM vendor. 133 // Refer to your DRM provider documentation for definitions of the field names 134 // for a particular DrmEngine. 135 virtual status_t 136 queryLicenseStatus(Vector<uint8_t> const &sessionId, 137 KeyedVector<String8, String8> &infoMap) const = 0; 138 139 // A provision request/response exchange occurs between the app and a 140 // provisioning server to retrieve a device certificate. getProvisionRequest 141 // is used to obtain an opaque license request blob that is delivered to the 142 // provisioning server. 143 // 144 // If successful, the opaque provision request blob is returned to the caller. 145 virtual status_t getProvisionRequest(Vector<uint8_t> &request, 146 String8 &defaultUrl) = 0; 147 148 // After a provision response is received by the app, it is provided to the 149 // Drm plugin using provideProvisionResponse. 150 virtual status_t provideProvisionResponse(Vector<uint8_t> const &response) = 0; 151 152 // A means of enforcing the contractual requirement for a concurrent stream 153 // limit per subscriber across devices is provided via SecureStop. SecureStop 154 // is a means of securely monitoring the lifetime of sessions. Since playback 155 // on a device can be interrupted due to reboot, power failure, etc. a means 156 // of persisting the lifetime information on the device is needed. 157 // 158 // A signed version of the sessionID is written to persistent storage on the 159 // device when each MediaCrypto object is created. The sessionID is signed by 160 // the device private key to prevent tampering. 161 // 162 // In the normal case, playback will be completed, the session destroyed and 163 // the Secure Stops will be queried. The App queries secure stops and forwards 164 // the secure stop message to the server which verifies the signature and 165 // notifies the server side database that the session destruction has been 166 // confirmed. The persisted record on the client is only removed after positive 167 // confirmation that the server received the message using releaseSecureStops(). 168 virtual status_t getSecureStops(List<Vector<uint8_t> > &secureStops) = 0; 169 virtual status_t releaseSecureStops(Vector<uint8_t> const &ssRelease) = 0; 170 171 // Read a property value given the device property string. There are a few forms 172 // of property access methods, depending on the data type returned. 173 // Since DRM plugin properties may vary, additional field names may be defined 174 // by each DRM vendor. Refer to your DRM provider documentation for definitions 175 // of its additional field names. 176 // 177 // Standard values are: 178 // "vendor" [string] identifies the maker of the plugin 179 // "version" [string] identifies the version of the plugin 180 // "description" [string] describes the plugin 181 // 'deviceUniqueId' [byte array] The device unique identifier is established 182 // during device provisioning and provides a means of uniquely identifying 183 // each device. 184 virtual status_t getPropertyString(String8 const &name, String8 &value ) const = 0; 185 virtual status_t getPropertyByteArray(String8 const &name, 186 Vector<uint8_t> &value ) const = 0; 187 188 // Write a property value given the device property string. There are a few forms 189 // of property setting methods, depending on the data type. 190 // Since DRM plugin properties may vary, additional field names may be defined 191 // by each DRM vendor. Refer to your DRM provider documentation for definitions 192 // of its field names. 193 virtual status_t setPropertyString(String8 const &name, 194 String8 const &value ) = 0; 195 virtual status_t setPropertyByteArray(String8 const &name, 196 Vector<uint8_t> const &value ) = 0; 197 198 // TODO: provide way to send an event 199 private: 200 DISALLOW_EVIL_CONSTRUCTORS(DrmPlugin); 201 }; 202 203} // namespace android 204 205#endif // DRM_API_H_ 206