blob: 95bdf776225abfda84ace93def657a601b30c59c [file] [log] [blame]
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -07001/*
Jeff Tinker56c78c42013-02-07 17:46:18 -08002 * 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>
Jeff Tinker7eafcae2013-04-02 13:16:21 -070025#include <utils/Mutex.h>
Jeff Tinker56c78c42013-02-07 17:46:18 -080026#include <media/stagefright/foundation/ABase.h>
27
28// Loadable DrmEngine shared libraries should define the entry points
29// createDrmFactory and createCryptoFactory as shown below:
30//
31// extern "C" {
32// extern android::DrmFactory *createDrmFactory();
33// extern android::CryptoFactory *createCryptoFactory();
34// }
35
36namespace android {
37
Jeff Tinker7eafcae2013-04-02 13:16:21 -070038 class DrmPlugin;
39 class DrmPluginListener;
Jeff Tinker56c78c42013-02-07 17:46:18 -080040
41 // DRMs are implemented in DrmEngine plugins, which are dynamically
42 // loadable shared libraries that implement the entry points
43 // createDrmFactory and createCryptoFactory. createDrmFactory
44 // constructs and returns an instance of a DrmFactory object. Similarly,
45 // createCryptoFactory creates an instance of a CryptoFactory object.
46 // When a MediaCrypto or MediaDrm object needs to be constructed, all
47 // available DrmEngines present in the plugins directory on the device
48 // are scanned for a matching DrmEngine that can support the crypto
49 // scheme. When a match is found, the DrmEngine's createCryptoPlugin and
50 // createDrmPlugin methods are used to create CryptoPlugin or
51 // DrmPlugin instances to support that DRM scheme.
52
53 class DrmFactory {
54 public:
55 DrmFactory() {}
56 virtual ~DrmFactory() {}
57
58 // DrmFactory::isCryptoSchemeSupported can be called to determine
59 // if the plugin factory is able to construct plugins that support a
60 // given crypto scheme, which is specified by a UUID.
61 virtual bool isCryptoSchemeSupported(const uint8_t uuid[16]) = 0;
62
Jeff Tinker611d3d42013-08-21 11:57:40 -070063 // DrmFactory::isContentTypeSupported can be called to determine
64 // if the plugin factory is able to construct plugins that support a
65 // given media container format specified by mimeType
66 virtual bool isContentTypeSupported(const String8 &mimeType) = 0;
67
Jeff Tinker56c78c42013-02-07 17:46:18 -080068 // Construct a DrmPlugin for the crypto scheme specified by UUID.
69 virtual status_t createDrmPlugin(
70 const uint8_t uuid[16], DrmPlugin **plugin) = 0;
71
72 private:
73 DrmFactory(const DrmFactory &);
74 DrmFactory &operator=(const DrmFactory &);
75 };
76
77 class DrmPlugin {
78 public:
79 enum EventType {
Jeff Tinker7eafcae2013-04-02 13:16:21 -070080 kDrmPluginEventProvisionRequired = 1,
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -070081 kDrmPluginEventKeyNeeded,
82 kDrmPluginEventKeyExpired,
Jeff Tinker56c78c42013-02-07 17:46:18 -080083 kDrmPluginEventVendorDefined
84 };
85
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -070086 // Drm keys can be for offline content or for online streaming.
87 // Offline keys are persisted on the device and may be used when the device
Jeff Tinkerb84d1ca2013-05-07 14:07:10 -070088 // is disconnected from the network. The Release type is used to request
89 // that offline keys be no longer restricted to offline use.
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -070090 enum KeyType {
91 kKeyType_Offline,
Jeff Tinkerb84d1ca2013-05-07 14:07:10 -070092 kKeyType_Streaming,
93 kKeyType_Release
Jeff Tinker56c78c42013-02-07 17:46:18 -080094 };
95
96 DrmPlugin() {}
97 virtual ~DrmPlugin() {}
98
99 // Open a new session with the DrmPlugin object. A session ID is returned
100 // in the sessionId parameter.
101 virtual status_t openSession(Vector<uint8_t> &sessionId) = 0;
102
103 // Close a session on the DrmPlugin object.
104 virtual status_t closeSession(Vector<uint8_t> const &sessionId) = 0;
105
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700106 // A key request/response exchange occurs between the app and a License
107 // Server to obtain the keys required to decrypt the content. getKeyRequest()
108 // is used to obtain an opaque key request blob that is delivered to the
Jeff Tinker56c78c42013-02-07 17:46:18 -0800109 // license server.
110 //
Jeff Tinkerb84d1ca2013-05-07 14:07:10 -0700111 // The scope parameter may be a sessionId or a keySetId, depending on the
112 // specified keyType. When the keyType is kKeyType_Offline or
113 // kKeyType_Streaming, scope should be set to the sessionId the keys will be
114 // provided to. When the keyType is kKeyType_Release, scope should be set to
115 // the keySetId of the keys being released. Releasing keys from a device
116 // invalidates them for all sessions.
117 //
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700118 // The init data passed to getKeyRequest is container-specific and its
Jeff Tinker56c78c42013-02-07 17:46:18 -0800119 // meaning is interpreted based on the mime type provided in the mimeType
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700120 // parameter to getKeyRequest. It could contain, for example, the content
Jeff Tinker56c78c42013-02-07 17:46:18 -0800121 // ID, key ID or other data obtained from the content metadata that is required
Jeff Tinkerb84d1ca2013-05-07 14:07:10 -0700122 // in generating the key request. Init may be null when keyType is
123 // kKeyType_Release.
Jeff Tinker56c78c42013-02-07 17:46:18 -0800124 //
Jeff Tinkerb84d1ca2013-05-07 14:07:10 -0700125 // mimeType identifies the mime type of the content
126 //
127 // keyType specifies if the keys are to be used for streaming or offline content
Jeff Tinker56c78c42013-02-07 17:46:18 -0800128 //
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700129 // optionalParameters are included in the key request message to allow a
130 // client application to provide additional message parameters to the server.
Jeff Tinker56c78c42013-02-07 17:46:18 -0800131 //
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700132 // If successful, the opaque key request blob is returned to the caller.
Jeff Tinker56c78c42013-02-07 17:46:18 -0800133 virtual status_t
Jeff Tinkerb84d1ca2013-05-07 14:07:10 -0700134 getKeyRequest(Vector<uint8_t> const &scope,
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700135 Vector<uint8_t> const &initData,
136 String8 const &mimeType, KeyType keyType,
137 KeyedVector<String8, String8> const &optionalParameters,
138 Vector<uint8_t> &request, String8 &defaultUrl) = 0;
Jeff Tinker56c78c42013-02-07 17:46:18 -0800139
Jeff Tinkerb84d1ca2013-05-07 14:07:10 -0700140 //
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700141 // After a key response is received by the app, it is provided to the
Jeff Tinkerb84d1ca2013-05-07 14:07:10 -0700142 // Drm plugin using provideKeyResponse.
143 //
144 // scope may be a sessionId or a keySetId depending on the type of the
145 // response. Scope should be set to the sessionId when the response is
146 // for either streaming or offline key requests. Scope should be set to the
147 // keySetId when the response is for a release request.
148 //
149 // When the response is for an offline key request, a keySetId is returned
150 // in the keySetId vector parameter that can be used to later restore the
151 // keys to a new session with the method restoreKeys. When the response is
152 // for a streaming or release request, no keySetId is returned.
153 //
154 virtual status_t provideKeyResponse(Vector<uint8_t> const &scope,
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700155 Vector<uint8_t> const &response,
156 Vector<uint8_t> &keySetId) = 0;
Jeff Tinker56c78c42013-02-07 17:46:18 -0800157
Jeff Tinkerb84d1ca2013-05-07 14:07:10 -0700158 // Remove the current keys from a session
159 virtual status_t removeKeys(Vector<uint8_t> const &sessionId) = 0;
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700160
161 // Restore persisted offline keys into a new session. keySetId identifies
162 // the keys to load, obtained from a prior call to provideKeyResponse().
163 virtual status_t restoreKeys(Vector<uint8_t> const &sessionId,
164 Vector<uint8_t> const &keySetId) = 0;
Jeff Tinker56c78c42013-02-07 17:46:18 -0800165
166 // Request an informative description of the license for the session. The status
167 // is in the form of {name, value} pairs. Since DRM license policies vary by
168 // vendor, the specific status field names are determined by each DRM vendor.
169 // Refer to your DRM provider documentation for definitions of the field names
170 // for a particular DrmEngine.
171 virtual status_t
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700172 queryKeyStatus(Vector<uint8_t> const &sessionId,
173 KeyedVector<String8, String8> &infoMap) const = 0;
Jeff Tinker56c78c42013-02-07 17:46:18 -0800174
175 // A provision request/response exchange occurs between the app and a
176 // provisioning server to retrieve a device certificate. getProvisionRequest
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700177 // is used to obtain an opaque key request blob that is delivered to the
Jeff Tinker56c78c42013-02-07 17:46:18 -0800178 // provisioning server.
179 //
180 // If successful, the opaque provision request blob is returned to the caller.
181 virtual status_t getProvisionRequest(Vector<uint8_t> &request,
182 String8 &defaultUrl) = 0;
183
184 // After a provision response is received by the app, it is provided to the
185 // Drm plugin using provideProvisionResponse.
186 virtual status_t provideProvisionResponse(Vector<uint8_t> const &response) = 0;
187
188 // A means of enforcing the contractual requirement for a concurrent stream
189 // limit per subscriber across devices is provided via SecureStop. SecureStop
190 // is a means of securely monitoring the lifetime of sessions. Since playback
191 // on a device can be interrupted due to reboot, power failure, etc. a means
192 // of persisting the lifetime information on the device is needed.
193 //
194 // A signed version of the sessionID is written to persistent storage on the
195 // device when each MediaCrypto object is created. The sessionID is signed by
196 // the device private key to prevent tampering.
197 //
198 // In the normal case, playback will be completed, the session destroyed and
199 // the Secure Stops will be queried. The App queries secure stops and forwards
200 // the secure stop message to the server which verifies the signature and
201 // notifies the server side database that the session destruction has been
202 // confirmed. The persisted record on the client is only removed after positive
203 // confirmation that the server received the message using releaseSecureStops().
204 virtual status_t getSecureStops(List<Vector<uint8_t> > &secureStops) = 0;
205 virtual status_t releaseSecureStops(Vector<uint8_t> const &ssRelease) = 0;
206
207 // Read a property value given the device property string. There are a few forms
208 // of property access methods, depending on the data type returned.
209 // Since DRM plugin properties may vary, additional field names may be defined
210 // by each DRM vendor. Refer to your DRM provider documentation for definitions
211 // of its additional field names.
212 //
213 // Standard values are:
214 // "vendor" [string] identifies the maker of the plugin
215 // "version" [string] identifies the version of the plugin
216 // "description" [string] describes the plugin
217 // 'deviceUniqueId' [byte array] The device unique identifier is established
218 // during device provisioning and provides a means of uniquely identifying
219 // each device.
220 virtual status_t getPropertyString(String8 const &name, String8 &value ) const = 0;
221 virtual status_t getPropertyByteArray(String8 const &name,
222 Vector<uint8_t> &value ) const = 0;
223
224 // Write a property value given the device property string. There are a few forms
225 // of property setting methods, depending on the data type.
226 // Since DRM plugin properties may vary, additional field names may be defined
227 // by each DRM vendor. Refer to your DRM provider documentation for definitions
228 // of its field names.
229 virtual status_t setPropertyString(String8 const &name,
230 String8 const &value ) = 0;
231 virtual status_t setPropertyByteArray(String8 const &name,
232 Vector<uint8_t> const &value ) = 0;
233
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700234 // The following methods implement operations on a CryptoSession to support
235 // encrypt, decrypt, sign verify operations on operator-provided
236 // session keys.
237
238 //
239 // The algorithm string conforms to JCA Standard Names for Cipher
240 // Transforms and is case insensitive. For example "AES/CBC/PKCS5Padding".
241 //
242 // Return OK if the algorithm is supported, otherwise return BAD_VALUE
243 //
244 virtual status_t setCipherAlgorithm(Vector<uint8_t> const &sessionId,
245 String8 const &algorithm) = 0;
246
247 //
248 // The algorithm string conforms to JCA Standard Names for Mac
249 // Algorithms and is case insensitive. For example "HmacSHA256".
250 //
251 // Return OK if the algorithm is supported, otherwise return BAD_VALUE
252 //
253 virtual status_t setMacAlgorithm(Vector<uint8_t> const &sessionId,
254 String8 const &algorithm) = 0;
255
256 // Encrypt the provided input buffer with the cipher algorithm
257 // specified by setCipherAlgorithm and the key selected by keyId,
258 // and return the encrypted data.
259 virtual status_t encrypt(Vector<uint8_t> const &sessionId,
260 Vector<uint8_t> const &keyId,
261 Vector<uint8_t> const &input,
262 Vector<uint8_t> const &iv,
263 Vector<uint8_t> &output) = 0;
264
265 // Decrypt the provided input buffer with the cipher algorithm
266 // specified by setCipherAlgorithm and the key selected by keyId,
267 // and return the decrypted data.
268 virtual status_t decrypt(Vector<uint8_t> const &sessionId,
269 Vector<uint8_t> const &keyId,
270 Vector<uint8_t> const &input,
271 Vector<uint8_t> const &iv,
272 Vector<uint8_t> &output) = 0;
273
274 // Compute a signature on the provided message using the mac algorithm
275 // specified by setMacAlgorithm and the key selected by keyId,
276 // and return the signature.
277 virtual status_t sign(Vector<uint8_t> const &sessionId,
278 Vector<uint8_t> const &keyId,
279 Vector<uint8_t> const &message,
280 Vector<uint8_t> &signature) = 0;
281
282 // Compute a signature on the provided message using the mac algorithm
283 // specified by setMacAlgorithm and the key selected by keyId,
284 // and compare with the expected result. Set result to true or
285 // false depending on the outcome.
286 virtual status_t verify(Vector<uint8_t> const &sessionId,
287 Vector<uint8_t> const &keyId,
288 Vector<uint8_t> const &message,
289 Vector<uint8_t> const &signature,
290 bool &match) = 0;
291
292
Jeff Tinker7eafcae2013-04-02 13:16:21 -0700293 status_t setListener(const sp<DrmPluginListener>& listener) {
294 Mutex::Autolock lock(mEventLock);
295 mListener = listener;
296 return OK;
297 }
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700298
Jeff Tinker7eafcae2013-04-02 13:16:21 -0700299 protected:
300 // Plugins call sendEvent to deliver events to the java app
301 void sendEvent(EventType eventType, int extra,
302 Vector<uint8_t> const *sessionId,
303 Vector<uint8_t> const *data);
304
Jeff Tinker56c78c42013-02-07 17:46:18 -0800305 private:
Jeff Tinker7eafcae2013-04-02 13:16:21 -0700306 Mutex mEventLock;
307 sp<DrmPluginListener> mListener;
308
Jeff Tinker56c78c42013-02-07 17:46:18 -0800309 DISALLOW_EVIL_CONSTRUCTORS(DrmPlugin);
310 };
311
Jeff Tinker7eafcae2013-04-02 13:16:21 -0700312 class DrmPluginListener: virtual public RefBase
313 {
314 public:
315 virtual void sendEvent(DrmPlugin::EventType eventType, int extra,
316 Vector<uint8_t> const *sesionId,
317 Vector<uint8_t> const *data) = 0;
318 };
319
320 inline void DrmPlugin::sendEvent(EventType eventType, int extra,
321 Vector<uint8_t> const *sessionId,
322 Vector<uint8_t> const *data) {
323
324 mEventLock.lock();
325 sp<DrmPluginListener> listener = mListener;
326 mEventLock.unlock();
327
328 if (listener != NULL) {
329 listener->sendEvent(eventType, extra, sessionId, data);
330 }
331 }
332
Jeff Tinker56c78c42013-02-07 17:46:18 -0800333} // namespace android
334
335#endif // DRM_API_H_