blob: b01476a923e28ede0cf23a97fad30f1e7c2403f2 [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,
Ronghua Wu46722ff2015-03-05 09:58:16 -080083 kDrmPluginEventVendorDefined,
84 kDrmPluginEventSessionReclaimed
Jeff Tinker56c78c42013-02-07 17:46:18 -080085 };
86
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -070087 // Drm keys can be for offline content or for online streaming.
88 // Offline keys are persisted on the device and may be used when the device
Jeff Tinkerb84d1ca2013-05-07 14:07:10 -070089 // is disconnected from the network. The Release type is used to request
90 // that offline keys be no longer restricted to offline use.
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -070091 enum KeyType {
92 kKeyType_Offline,
Jeff Tinkerb84d1ca2013-05-07 14:07:10 -070093 kKeyType_Streaming,
94 kKeyType_Release
Jeff Tinker56c78c42013-02-07 17:46:18 -080095 };
96
Jeff Tinker06a8cd62015-03-16 13:04:40 -070097 // Enumerate KeyRequestTypes to allow an app to determine the
98 // type of a key request returned from getKeyRequest.
99 enum KeyRequestType {
100 kKeyRequestType_Unknown,
101 kKeyRequestType_Initial,
102 kKeyRequestType_Renewal,
103 kKeyRequestType_Release
104 };
105
Jeff Tinker56c78c42013-02-07 17:46:18 -0800106 DrmPlugin() {}
107 virtual ~DrmPlugin() {}
108
109 // Open a new session with the DrmPlugin object. A session ID is returned
110 // in the sessionId parameter.
111 virtual status_t openSession(Vector<uint8_t> &sessionId) = 0;
112
113 // Close a session on the DrmPlugin object.
114 virtual status_t closeSession(Vector<uint8_t> const &sessionId) = 0;
115
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700116 // A key request/response exchange occurs between the app and a License
117 // Server to obtain the keys required to decrypt the content. getKeyRequest()
118 // is used to obtain an opaque key request blob that is delivered to the
Jeff Tinker56c78c42013-02-07 17:46:18 -0800119 // license server.
120 //
Jeff Tinkerb84d1ca2013-05-07 14:07:10 -0700121 // The scope parameter may be a sessionId or a keySetId, depending on the
122 // specified keyType. When the keyType is kKeyType_Offline or
123 // kKeyType_Streaming, scope should be set to the sessionId the keys will be
124 // provided to. When the keyType is kKeyType_Release, scope should be set to
125 // the keySetId of the keys being released. Releasing keys from a device
126 // invalidates them for all sessions.
127 //
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700128 // The init data passed to getKeyRequest is container-specific and its
Jeff Tinker56c78c42013-02-07 17:46:18 -0800129 // meaning is interpreted based on the mime type provided in the mimeType
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700130 // parameter to getKeyRequest. It could contain, for example, the content
Jeff Tinker56c78c42013-02-07 17:46:18 -0800131 // ID, key ID or other data obtained from the content metadata that is required
Jeff Tinkerb84d1ca2013-05-07 14:07:10 -0700132 // in generating the key request. Init may be null when keyType is
133 // kKeyType_Release.
Jeff Tinker56c78c42013-02-07 17:46:18 -0800134 //
Jeff Tinkerb84d1ca2013-05-07 14:07:10 -0700135 // mimeType identifies the mime type of the content
136 //
137 // keyType specifies if the keys are to be used for streaming or offline content
Jeff Tinker56c78c42013-02-07 17:46:18 -0800138 //
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700139 // optionalParameters are included in the key request message to allow a
140 // client application to provide additional message parameters to the server.
Jeff Tinker56c78c42013-02-07 17:46:18 -0800141 //
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700142 // If successful, the opaque key request blob is returned to the caller.
Jeff Tinker56c78c42013-02-07 17:46:18 -0800143 virtual status_t
Jeff Tinkerb84d1ca2013-05-07 14:07:10 -0700144 getKeyRequest(Vector<uint8_t> const &scope,
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700145 Vector<uint8_t> const &initData,
146 String8 const &mimeType, KeyType keyType,
147 KeyedVector<String8, String8> const &optionalParameters,
Jeff Tinker06a8cd62015-03-16 13:04:40 -0700148 Vector<uint8_t> &request, String8 &defaultUrl,
149 KeyRequestType *keyRequestType) = 0;
Jeff Tinker56c78c42013-02-07 17:46:18 -0800150
Jeff Tinkerb84d1ca2013-05-07 14:07:10 -0700151 //
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700152 // After a key response is received by the app, it is provided to the
Jeff Tinkerb84d1ca2013-05-07 14:07:10 -0700153 // Drm plugin using provideKeyResponse.
154 //
155 // scope may be a sessionId or a keySetId depending on the type of the
156 // response. Scope should be set to the sessionId when the response is
157 // for either streaming or offline key requests. Scope should be set to the
158 // keySetId when the response is for a release request.
159 //
160 // When the response is for an offline key request, a keySetId is returned
161 // in the keySetId vector parameter that can be used to later restore the
162 // keys to a new session with the method restoreKeys. When the response is
163 // for a streaming or release request, no keySetId is returned.
164 //
165 virtual status_t provideKeyResponse(Vector<uint8_t> const &scope,
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700166 Vector<uint8_t> const &response,
167 Vector<uint8_t> &keySetId) = 0;
Jeff Tinker56c78c42013-02-07 17:46:18 -0800168
Jeff Tinkerb84d1ca2013-05-07 14:07:10 -0700169 // Remove the current keys from a session
170 virtual status_t removeKeys(Vector<uint8_t> const &sessionId) = 0;
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700171
172 // Restore persisted offline keys into a new session. keySetId identifies
173 // the keys to load, obtained from a prior call to provideKeyResponse().
174 virtual status_t restoreKeys(Vector<uint8_t> const &sessionId,
175 Vector<uint8_t> const &keySetId) = 0;
Jeff Tinker56c78c42013-02-07 17:46:18 -0800176
177 // Request an informative description of the license for the session. The status
178 // is in the form of {name, value} pairs. Since DRM license policies vary by
179 // vendor, the specific status field names are determined by each DRM vendor.
180 // Refer to your DRM provider documentation for definitions of the field names
181 // for a particular DrmEngine.
182 virtual status_t
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700183 queryKeyStatus(Vector<uint8_t> const &sessionId,
184 KeyedVector<String8, String8> &infoMap) const = 0;
Jeff Tinker56c78c42013-02-07 17:46:18 -0800185
186 // A provision request/response exchange occurs between the app and a
187 // provisioning server to retrieve a device certificate. getProvisionRequest
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700188 // is used to obtain an opaque key request blob that is delivered to the
Jeff Tinker56c78c42013-02-07 17:46:18 -0800189 // provisioning server.
190 //
191 // If successful, the opaque provision request blob is returned to the caller.
Jeff Tinkerc2f10f22014-03-04 13:23:56 -0800192 virtual status_t getProvisionRequest(String8 const &cert_type,
193 String8 const &cert_authority,
194 Vector<uint8_t> &request,
Jeff Tinker56c78c42013-02-07 17:46:18 -0800195 String8 &defaultUrl) = 0;
196
197 // After a provision response is received by the app, it is provided to the
198 // Drm plugin using provideProvisionResponse.
Jeff Tinkerc2f10f22014-03-04 13:23:56 -0800199 virtual status_t provideProvisionResponse(Vector<uint8_t> const &response,
200 Vector<uint8_t> &certificate,
201 Vector<uint8_t> &wrapped_key) = 0;
Jeff Tinker56c78c42013-02-07 17:46:18 -0800202
Jeff Tinkerbc6b9e72014-04-30 10:21:53 -0700203 // Remove device provisioning.
204 virtual status_t unprovisionDevice() = 0;
205
Jeff Tinker56c78c42013-02-07 17:46:18 -0800206 // A means of enforcing the contractual requirement for a concurrent stream
207 // limit per subscriber across devices is provided via SecureStop. SecureStop
208 // is a means of securely monitoring the lifetime of sessions. Since playback
209 // on a device can be interrupted due to reboot, power failure, etc. a means
210 // of persisting the lifetime information on the device is needed.
211 //
212 // A signed version of the sessionID is written to persistent storage on the
213 // device when each MediaCrypto object is created. The sessionID is signed by
214 // the device private key to prevent tampering.
215 //
216 // In the normal case, playback will be completed, the session destroyed and
217 // the Secure Stops will be queried. The App queries secure stops and forwards
218 // the secure stop message to the server which verifies the signature and
219 // notifies the server side database that the session destruction has been
220 // confirmed. The persisted record on the client is only removed after positive
221 // confirmation that the server received the message using releaseSecureStops().
222 virtual status_t getSecureStops(List<Vector<uint8_t> > &secureStops) = 0;
Jeff Tinker57481592014-10-31 00:42:33 -0700223 virtual status_t getSecureStop(Vector<uint8_t> const &ssid, Vector<uint8_t> &secureStop) = 0;
Jeff Tinker56c78c42013-02-07 17:46:18 -0800224 virtual status_t releaseSecureStops(Vector<uint8_t> const &ssRelease) = 0;
Jeff Tinker57481592014-10-31 00:42:33 -0700225 virtual status_t releaseAllSecureStops() = 0;
Jeff Tinker56c78c42013-02-07 17:46:18 -0800226
227 // Read a property value given the device property string. There are a few forms
228 // of property access methods, depending on the data type returned.
229 // Since DRM plugin properties may vary, additional field names may be defined
230 // by each DRM vendor. Refer to your DRM provider documentation for definitions
231 // of its additional field names.
232 //
233 // Standard values are:
234 // "vendor" [string] identifies the maker of the plugin
235 // "version" [string] identifies the version of the plugin
236 // "description" [string] describes the plugin
237 // 'deviceUniqueId' [byte array] The device unique identifier is established
238 // during device provisioning and provides a means of uniquely identifying
239 // each device.
240 virtual status_t getPropertyString(String8 const &name, String8 &value ) const = 0;
241 virtual status_t getPropertyByteArray(String8 const &name,
242 Vector<uint8_t> &value ) const = 0;
243
244 // Write a property value given the device property string. There are a few forms
245 // of property setting methods, depending on the data type.
246 // Since DRM plugin properties may vary, additional field names may be defined
247 // by each DRM vendor. Refer to your DRM provider documentation for definitions
248 // of its field names.
249 virtual status_t setPropertyString(String8 const &name,
250 String8 const &value ) = 0;
251 virtual status_t setPropertyByteArray(String8 const &name,
252 Vector<uint8_t> const &value ) = 0;
253
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700254 // The following methods implement operations on a CryptoSession to support
255 // encrypt, decrypt, sign verify operations on operator-provided
256 // session keys.
257
258 //
259 // The algorithm string conforms to JCA Standard Names for Cipher
260 // Transforms and is case insensitive. For example "AES/CBC/PKCS5Padding".
261 //
262 // Return OK if the algorithm is supported, otherwise return BAD_VALUE
263 //
264 virtual status_t setCipherAlgorithm(Vector<uint8_t> const &sessionId,
265 String8 const &algorithm) = 0;
266
267 //
268 // The algorithm string conforms to JCA Standard Names for Mac
269 // Algorithms and is case insensitive. For example "HmacSHA256".
270 //
271 // Return OK if the algorithm is supported, otherwise return BAD_VALUE
272 //
273 virtual status_t setMacAlgorithm(Vector<uint8_t> const &sessionId,
274 String8 const &algorithm) = 0;
275
276 // Encrypt the provided input buffer with the cipher algorithm
277 // specified by setCipherAlgorithm and the key selected by keyId,
278 // and return the encrypted data.
279 virtual status_t encrypt(Vector<uint8_t> const &sessionId,
280 Vector<uint8_t> const &keyId,
281 Vector<uint8_t> const &input,
282 Vector<uint8_t> const &iv,
283 Vector<uint8_t> &output) = 0;
284
285 // Decrypt the provided input buffer with the cipher algorithm
286 // specified by setCipherAlgorithm and the key selected by keyId,
287 // and return the decrypted data.
288 virtual status_t decrypt(Vector<uint8_t> const &sessionId,
289 Vector<uint8_t> const &keyId,
290 Vector<uint8_t> const &input,
291 Vector<uint8_t> const &iv,
292 Vector<uint8_t> &output) = 0;
293
294 // Compute a signature on the provided message using the mac algorithm
295 // specified by setMacAlgorithm and the key selected by keyId,
296 // and return the signature.
297 virtual status_t sign(Vector<uint8_t> const &sessionId,
298 Vector<uint8_t> const &keyId,
299 Vector<uint8_t> const &message,
300 Vector<uint8_t> &signature) = 0;
301
302 // Compute a signature on the provided message using the mac algorithm
303 // specified by setMacAlgorithm and the key selected by keyId,
304 // and compare with the expected result. Set result to true or
305 // false depending on the outcome.
306 virtual status_t verify(Vector<uint8_t> const &sessionId,
307 Vector<uint8_t> const &keyId,
308 Vector<uint8_t> const &message,
309 Vector<uint8_t> const &signature,
310 bool &match) = 0;
311
312
Jeff Tinkerc2f10f22014-03-04 13:23:56 -0800313 // Compute an RSA signature on the provided message using the algorithm
314 // specified by algorithm.
315 virtual status_t signRSA(Vector<uint8_t> const &sessionId,
316 String8 const &algorithm,
317 Vector<uint8_t> const &message,
318 Vector<uint8_t> const &wrapped_key,
319 Vector<uint8_t> &signature) = 0;
320
321
Jeff Tinker7eafcae2013-04-02 13:16:21 -0700322 status_t setListener(const sp<DrmPluginListener>& listener) {
323 Mutex::Autolock lock(mEventLock);
324 mListener = listener;
325 return OK;
326 }
Jeff Tinkerbcbd78b2013-03-30 16:28:20 -0700327
Jeff Tinker7eafcae2013-04-02 13:16:21 -0700328 protected:
329 // Plugins call sendEvent to deliver events to the java app
330 void sendEvent(EventType eventType, int extra,
331 Vector<uint8_t> const *sessionId,
332 Vector<uint8_t> const *data);
333
Jeff Tinker56c78c42013-02-07 17:46:18 -0800334 private:
Jeff Tinker7eafcae2013-04-02 13:16:21 -0700335 Mutex mEventLock;
336 sp<DrmPluginListener> mListener;
337
Jeff Tinker56c78c42013-02-07 17:46:18 -0800338 DISALLOW_EVIL_CONSTRUCTORS(DrmPlugin);
339 };
340
Jeff Tinker7eafcae2013-04-02 13:16:21 -0700341 class DrmPluginListener: virtual public RefBase
342 {
343 public:
344 virtual void sendEvent(DrmPlugin::EventType eventType, int extra,
345 Vector<uint8_t> const *sesionId,
346 Vector<uint8_t> const *data) = 0;
347 };
348
349 inline void DrmPlugin::sendEvent(EventType eventType, int extra,
350 Vector<uint8_t> const *sessionId,
351 Vector<uint8_t> const *data) {
352
353 mEventLock.lock();
354 sp<DrmPluginListener> listener = mListener;
355 mEventLock.unlock();
356
357 if (listener != NULL) {
358 listener->sendEvent(eventType, extra, sessionId, data);
359 }
360 }
361
Jeff Tinker56c78c42013-02-07 17:46:18 -0800362} // namespace android
363
364#endif // DRM_API_H_