drm/1.0/types.hal

   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 };