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 17 package android.hardware.drm@1.0; 18 19 enum 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 */ 109 enum 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 142 enum 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 */ 167 enum 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 */ 194 enum 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 224 typedef vec<uint8_t> SessionId; 225 226 /** 227 * Used by sendKeysChange to report the usability status of each key to the 228 * app. 229 */ 230 struct KeyStatus 231 { 232 vec<uint8_t> keyId; 233 KeyStatusType type; 234 }; 235 236 /** 237 * Simulates a KeyedVector<String8, String8> 238 */ 239 struct KeyValue { 240 string key; 241 string value; 242 }; 243 244 typedef vec<KeyValue> KeyedVector; 245 246 /** 247 * Encapsulates a secure stop opaque object 248 */ 249 struct SecureStop { 250 vec<uint8_t> opaqueData; 251 }; 252 253 typedef vec<uint8_t> SecureStopId; 254 255 256 /** 257 * Enumerate the supported crypto modes 258 */ 259 enum 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 */ 270 struct 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 */ 282 struct 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 296 enum 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 */ 307 struct 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 */ 331 struct 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
