1/**
2 * Copyright (C) 2016 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
17package android.hardware.drm@1.0;
18
19enum Status : uint32_t {
20    /**
21     * The DRM plugin must return OK when an operation completes without any
22     * errors.
23     */
24    OK,
25
26    /**
27     * The DRM plugin must return ERROR_DRM_NO_LICENSE, when decryption is
28     * attempted and no license keys have been provided.
29     */
30    ERROR_DRM_NO_LICENSE,
31
32    /**
33     * ERROR_DRM_LICENSE_EXPIRED must be returned when an attempt is made
34     * to use a license and the keys in that license have expired.
35     */
36    ERROR_DRM_LICENSE_EXPIRED,
37
38    /**
39     * The DRM plugin must return ERROR_DRM_SESSION_NOT_OPENED when an
40     * attempt is made to use a session that has not been opened.
41     */
42    ERROR_DRM_SESSION_NOT_OPENED,
43
44    /**
45     * The DRM plugin must return ERROR_DRM_CANNOT_HANDLE when an unsupported
46     * data format or operation is attempted.
47     */
48    ERROR_DRM_CANNOT_HANDLE,
49
50    /**
51     * ERROR_DRM_INVALID_STATE must be returned when the device is in a state
52     * where it is not able to perform decryption.
53     */
54    ERROR_DRM_INVALID_STATE,
55
56    /**
57     * The DRM plugin must return BAD_VALUE whenever an illegal parameter is
58     * passed to one of the interface functions.
59     */
60    BAD_VALUE,
61
62    /**
63     * The DRM plugin must return ERROR_DRM_NOT_PROVISIONED from getKeyRequest,
64     * openSession or provideKeyResponse when the device has not yet been
65     * provisioned.
66     */
67    ERROR_DRM_NOT_PROVISIONED,
68
69    /**
70     * ERROR_DRM_RESOURCE_BUSY must be returned when resources, such as drm
71     * sessions or secure buffers are not available to perform a requested
72     * operation because they are already in use.
73     */
74    ERROR_DRM_RESOURCE_BUSY,
75
76    /**
77     * The DRM Plugin must return ERROR_DRM_INSUFFICIENT_OUTPUT_PROTECTION
78     * when the output protection level enabled on the device is not
79     * sufficient to meet the requirements in the license policy.  HDCP is an
80     * example of a form of output protection.
81     */
82    ERROR_DRM_INSUFFICIENT_OUTPUT_PROTECTION,
83
84    /**
85     * The DRM Plugin must return ERROR_DRM_DEVICE_REVOKED from
86     * provideProvisionResponse and provideKeyResponse if the response indicates
87     * that the device has been revoked. Device revocation means that the device
88     * is no longer permitted to play content.
89     */
90    ERROR_DRM_DEVICE_REVOKED,
91
92    /**
93     * The DRM Plugin must return ERROR_DRM_DECRYPT if the CryptoPlugin
94     * decrypt operation fails.
95     */
96    ERROR_DRM_DECRYPT,
97
98    /**
99     * ERROR_DRM_UNKNOWN must be returned when a fatal failure occurs and no
100     * other defined error is appropriate.
101     */
102    ERROR_DRM_UNKNOWN,
103};
104
105
106/**
107 * EventType enumerates the events that can be delivered by sendEvent
108 */
109enum EventType : uint32_t {
110    /**
111     * This event type indicates that the app needs to request a certificate
112     * from the provisioning server. The request message data is obtained using
113     * getProvisionRequest().
114     */
115    PROVISION_REQUIRED,
116
117     /**
118     * This event type indicates that the app needs to request keys from a
119     * license server. The request message data is obtained using getKeyRequest.
120     */
121    KEY_NEEDED,
122
123    /**
124     * This event type indicates that the licensed usage duration for keys in a
125     * session has expired. The keys are no longer valid.
126     */
127    KEY_EXPIRED,
128
129    /**
130     * This event may indicate some specific vendor-defined condition, see your
131     * DRM provider documentation for details.
132     */
133    VENDOR_DEFINED,
134
135    /**
136     * This event indicates that a session opened by the app has been reclaimed
137     * by the resource manager.
138     */
139    SESSION_RECLAIMED,
140};
141
142enum KeyType : uint32_t {
143    /**
144     * Drm keys can be for offline content or for online streaming.
145     * Offline keys are persisted on the device and may be used when the device
146     * is disconnected from the network.
147     */
148    OFFLINE,
149
150    /**
151     * Keys for streaming are not persisted and require the device to be
152     * connected to the network for periodic renewal.
153     */
154    STREAMING,
155
156    /**
157     * The Release type is used to request that offline keys be no longer
158     * restricted to offline use.
159     */
160    RELEASE,
161};
162
163/**
164 * Enumerate KeyRequestTypes to allow an app to determine the type of a key
165 * request returned from getKeyRequest.
166 */
167enum KeyRequestType : uint32_t {
168    /**
169     * Key request type is for an initial license request
170     */
171    INITIAL,
172
173    /**
174     * Key request type is for license renewal. Renewal requests are used
175     * to extend the validity period for streaming keys.
176     */
177    RENEWAL,
178
179    /**
180     * Key request type is a release. A key release causes offline keys
181     * to become available for streaming.
182     */
183    RELEASE,
184
185    /**
186     * Key request type is unknown due to some error condition.
187     */
188    UNKNOWN,
189};
190
191/**
192 * Enumerate KeyStatusTypes which indicate the state of a key
193 */
194enum KeyStatusType : uint32_t {
195    /**
196     * The key is currently usable to decrypt media data.
197     */
198    USABLE,
199
200    /**
201     * The key is no longer usable to decrypt media data because its expiration
202     * time has passed.
203     */
204    EXPIRED,
205
206    /**
207     * The key is not currently usable to decrypt media data because its output
208     * requirements cannot currently be met.
209     */
210    OUTPUTNOTALLOWED,
211
212    /**
213     * The status of the key is not yet known and is being determined.
214     */
215    STATUSPENDING,
216
217    /**
218     * The key is not currently usable to decrypt media data because of an
219     * internal error in processing unrelated to input parameters.
220     */
221    INTERNALERROR,
222};
223
224typedef vec<uint8_t> SessionId;
225
226/**
227 * Used by sendKeysChange to report the usability status of each key to the
228 * app.
229 */
230struct KeyStatus
231{
232    vec<uint8_t> keyId;
233    KeyStatusType type;
234};
235
236/**
237 * Simulates a KeyedVector<String8, String8>
238 */
239struct KeyValue {
240    string key;
241    string value;
242};
243
244typedef vec<KeyValue> KeyedVector;
245
246/**
247 * Encapsulates a secure stop opaque object
248 */
249struct SecureStop {
250    vec<uint8_t> opaqueData;
251};
252
253typedef vec<uint8_t> SecureStopId;
254
255
256/**
257 * Enumerate the supported crypto modes
258 */
259enum Mode : uint32_t {
260    UNENCRYPTED = 0, // Samples are unencrypted
261    AES_CTR     = 1, // Samples are encrypted with AES CTR mode
262    AES_CBC_CTS = 2, // Samples are encrypted with AES CBC CTS mode
263    AES_CBC     = 3, // Samples are encrypted with AES CBC mode
264};
265
266/**
267 * A subsample consists of some number of bytes of clear (unencrypted)
268 * data followed by a number of bytes of encrypted data.
269 */
270struct SubSample {
271    uint32_t numBytesOfClearData;
272    uint32_t numBytesOfEncryptedData;
273};
274
275/**
276 * A crypto Pattern is a repeating sequence of encrypted and clear blocks
277 * occuring within the bytes indicated by mNumBytesOfEncryptedDatad bytes
278 * of a subsample. Patterns are used to reduce the CPU overhead of
279 * decrypting samples. As an example, HLS uses 1:9 patterns where every
280 * 10th block is encrypted.
281 */
282struct Pattern {
283    /**
284     * The number of blocks to be encrypted in the pattern. If zero,
285     * pattern encryption is inoperative.
286     */
287    uint32_t encryptBlocks;
288
289    /**
290     * The number of blocks to be skipped (left clear) in the pattern. If
291     * zero, pattern encryption is inoperative.
292     */
293    uint32_t skipBlocks;
294};
295
296enum BufferType : uint32_t {
297    SHARED_MEMORY = 0,
298    NATIVE_HANDLE = 1,
299};
300
301/**
302 * SharedBuffer describes a decrypt buffer which is defined by a bufferId, an
303 * offset and a size.  The offset is relative to the shared memory base for the
304 * memory region identified by bufferId, which is established by
305 * setSharedMemoryBase().
306 */
307struct SharedBuffer {
308    /**
309     * The unique buffer identifier
310     */
311    uint32_t bufferId;
312
313    /**
314     * The offset from the shared memory base
315     */
316    uint64_t offset;
317
318    /**
319     * The size of the shared buffer in bytes
320     */
321    uint64_t size;
322};
323
324
325/**
326 * A decrypt destination buffer can be either normal user-space shared
327 * memory for the non-secure decrypt case, or it can be a secure buffer
328 * which is referenced by a native-handle. The native handle is allocated
329 * by the vendor's buffer allocator.
330 */
331struct DestinationBuffer {
332    /**
333     * The type of the buffer
334     */
335    BufferType type;
336
337    /**
338     * If type == SHARED_MEMORY, the decrypted data must be written
339     * to user-space non-secure shared memory.
340     */
341    SharedBuffer nonsecureMemory;
342
343    /**
344     * If type == NATIVE_HANDLE, the decrypted data must be written
345     * to secure memory referenced by the vendor's buffer allocator.
346     */
347    handle secureMemory;
348};
349