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.keymaster@3.0; 18 19 enum TagType : uint32_t { 20 INVALID = 0 << 28, /** Invalid type, used to designate a tag as uninitialized */ 21 ENUM = 1 << 28, 22 ENUM_REP = 2 << 28, /** Repeatable enumeration value. */ 23 UINT = 3 << 28, 24 UINT_REP = 4 << 28, /** Repeatable integer value */ 25 ULONG = 5 << 28, 26 DATE = 6 << 28, 27 BOOL = 7 << 28, 28 BIGNUM = 8 << 28, 29 BYTES = 9 << 28, 30 ULONG_REP = 10 << 28, /** Repeatable long value */ 31 }; 32 33 enum Tag : uint32_t { 34 INVALID = TagType:INVALID | 0, 35 36 /** 37 * Tags that must be semantically enforced by hardware and software implementations. 38 */ 39 40 /** Crypto parameters */ 41 PURPOSE = TagType:ENUM_REP | 1, /** KeyPurpose. */ 42 ALGORITHM = TagType:ENUM | 2, /** Algorithm. */ 43 KEY_SIZE = TagType:UINT | 3, /** Key size in bits. */ 44 BLOCK_MODE = TagType:ENUM_REP | 4, /** BlockMode. */ 45 DIGEST = TagType:ENUM_REP | 5, /** Digest. */ 46 PADDING = TagType:ENUM_REP | 6, /** PaddingMode. */ 47 CALLER_NONCE = TagType:BOOL | 7, /** Allow caller to specify nonce or IV. */ 48 MIN_MAC_LENGTH = TagType:UINT | 8, /* Minimum length of MAC or AEAD authentication tag in 49 * bits. */ 50 KDF = TagType:ENUM_REP | 9, /** KeyDerivationFunction. */ 51 EC_CURVE = TagType:ENUM | 10, /** EcCurve. */ 52 53 /** Algorithm-specific. */ 54 RSA_PUBLIC_EXPONENT = TagType:ULONG | 200, 55 ECIES_SINGLE_HASH_MODE = TagType:BOOL | 201, /* Whether the ephemeral public key is fed into the 56 * KDF. */ 57 INCLUDE_UNIQUE_ID = TagType:BOOL | 202, /* If true, attestation certificates for this key 58 * will contain an application-scoped and 59 * time-bounded device-unique ID.*/ 60 61 /** Other hardware-enforced. */ 62 BLOB_USAGE_REQUIREMENTS = TagType:ENUM | 301, /** KeyBlobUsageRequirements. */ 63 BOOTLOADER_ONLY = TagType:BOOL | 302, /** Usable only by bootloader. */ 64 65 /** 66 * Tags that should be semantically enforced by hardware if possible and will otherwise be 67 * enforced by software (keystore). 68 */ 69 70 /** Key validity period */ 71 ACTIVE_DATETIME = TagType:DATE | 400, /** Start of validity. */ 72 ORIGINATION_EXPIRE_DATETIME = TagType:DATE | 401, /* Date when new "messages" should no longer 73 * be created. */ 74 USAGE_EXPIRE_DATETIME = TagType:DATE | 402, /* Date when existing "messages" should no 75 * longer be trusted. */ 76 MIN_SECONDS_BETWEEN_OPS = TagType:UINT | 403, /* Minimum elapsed time between 77 * cryptographic operations with the key. */ 78 MAX_USES_PER_BOOT = TagType:UINT | 404, /* Number of times the key can be used per 79 * boot. */ 80 81 /** User authentication */ 82 ALL_USERS = TagType:BOOL | 500, /** Reserved for future use -- ignore. */ 83 USER_ID = TagType:UINT | 501, /** Reserved for future use -- ignore. */ 84 USER_SECURE_ID = TagType:ULONG_REP | 502, /* Secure ID of authorized user or authenticator(s). 85 * Disallowed if ALL_USERS or NO_AUTH_REQUIRED is 86 * present. */ 87 NO_AUTH_REQUIRED = TagType:BOOL | 503, /** If key is usable without authentication. */ 88 USER_AUTH_TYPE = TagType:ENUM | 504, /* Bitmask of authenticator types allowed when 89 * USER_SECURE_ID contains a secure user ID, rather 90 * than a secure authenticator ID. Defined in 91 * HardwareAuthenticatorType. */ 92 AUTH_TIMEOUT = TagType:UINT | 505, /* Required freshness of user authentication for 93 * private/secret key operations, in seconds. Public 94 * key operations require no authentication. If 95 * absent, authentication is required for every use. 96 * Authentication state is lost when the device is 97 * powered off. */ 98 ALLOW_WHILE_ON_BODY = TagType:BOOL | 506, /* Allow key to be used after authentication timeout 99 * if device is still on-body (requires secure on-body 100 * sensor. */ 101 102 /** Application access control */ 103 ALL_APPLICATIONS = TagType:BOOL | 600, /* Specified to indicate key is usable by all 104 * applications. */ 105 APPLICATION_ID = TagType:BYTES | 601, /** Byte string identifying the authorized application. */ 106 EXPORTABLE = TagType:BOOL | 602, /* If true, private/secret key can be exported, but only 107 * if all access control requirements for use are 108 * met. (keymaster2) */ 109 110 /** 111 * Semantically unenforceable tags, either because they have no specific meaning or because 112 * they're informational only. 113 */ 114 APPLICATION_DATA = TagType:BYTES | 700, /** Data provided by authorized application. */ 115 CREATION_DATETIME = TagType:DATE | 701, /** Key creation time */ 116 ORIGIN = TagType:ENUM | 702, /** keymaster_key_origin_t. */ 117 ROLLBACK_RESISTANT = TagType:BOOL | 703, /** Whether key is rollback-resistant. */ 118 ROOT_OF_TRUST = TagType:BYTES | 704, /** Root of trust ID. */ 119 OS_VERSION = TagType:UINT | 705, /** Version of system (keymaster2) */ 120 OS_PATCHLEVEL = TagType:UINT | 706, /** Patch level of system (keymaster2) */ 121 UNIQUE_ID = TagType:BYTES | 707, /** Used to provide unique ID in attestation */ 122 ATTESTATION_CHALLENGE = TagType:BYTES | 708, /** Used to provide challenge in attestation */ 123 ATTESTATION_APPLICATION_ID = TagType:BYTES | 709, /* Used to identify the set of possible 124 * applications of which one has initiated a 125 * key attestation */ 126 ATTESTATION_ID_BRAND = TagType:BYTES | 710, /* Used to provide the device's brand name to be 127 included in attestation */ 128 ATTESTATION_ID_DEVICE = TagType:BYTES | 711, /* Used to provide the device's device name to be 129 included in attestation */ 130 ATTESTATION_ID_PRODUCT = TagType:BYTES | 712, /* Used to provide the device's product name to be 131 included in attestation */ 132 ATTESTATION_ID_SERIAL = TagType:BYTES | 713, /* Used to provide the device's serial number to be 133 included in attestation */ 134 ATTESTATION_ID_IMEI = TagType:BYTES | 714, /* Used to provide the device's IMEI to be included 135 in attestation */ 136 ATTESTATION_ID_MEID = TagType:BYTES | 715, /* Used to provide the device's MEID to be included 137 in attestation */ 138 ATTESTATION_ID_MANUFACTURER = TagType:BYTES | 716, /* Used to provide the device's manufacturer 139 name to be included in attestation */ 140 ATTESTATION_ID_MODEL = TagType:BYTES | 717, /* Used to provide the device's model name to be 141 included in attestation */ 142 143 /** Tags used only to provide data to or receive data from operations */ 144 ASSOCIATED_DATA = TagType:BYTES | 1000, /** Used to provide associated data for AEAD modes. */ 145 NONCE = TagType:BYTES | 1001, /** Nonce or Initialization Vector */ 146 AUTH_TOKEN = TagType:BYTES | 1002, /* Authentication token that proves secure user 147 * authentication has been performed. Structure defined 148 * in hw_auth_token_t in hw_auth_token.h. */ 149 MAC_LENGTH = TagType:UINT | 1003, /** MAC or AEAD authentication tag length in bits. */ 150 151 RESET_SINCE_ID_ROTATION = TagType:BOOL | 1004, /* Whether the device has beeen factory reset 152 * since the last unique ID rotation. Used for 153 * key attestation. */ 154 }; 155 156 enum Algorithm : uint32_t { 157 /** Asymmetric algorithms. */ 158 RSA = 1, 159 // DSA = 2, -- Removed, do not re-use value 2. 160 EC = 3, 161 162 /** Block ciphers algorithms */ 163 AES = 32, 164 165 /** MAC algorithms */ 166 HMAC = 128, 167 }; 168 169 /** 170 * Symmetric block cipher modes provided by keymaster implementations. 171 */ 172 enum BlockMode : uint32_t { 173 /** 174 * Unauthenticated modes, usable only for encryption/decryption and not generally recommended 175 * except for compatibility with existing other protocols. */ 176 ECB = 1, 177 CBC = 2, 178 CTR = 3, 179 180 /** 181 * Authenticated modes, usable for encryption/decryption and signing/verification. Recommended 182 * over unauthenticated modes for all purposes. */ 183 GCM = 32, 184 }; 185 186 /** 187 * Padding modes that may be applied to plaintext for encryption operations. This list includes 188 * padding modes for both symmetric and asymmetric algorithms. Note that implementations should not 189 * provide all possible combinations of algorithm and padding, only the 190 * cryptographically-appropriate pairs. 191 */ 192 enum PaddingMode : uint32_t { 193 NONE = 1, /** deprecated */ 194 RSA_OAEP = 2, 195 RSA_PSS = 3, 196 RSA_PKCS1_1_5_ENCRYPT = 4, 197 RSA_PKCS1_1_5_SIGN = 5, 198 PKCS7 = 64, 199 }; 200 201 /** 202 * Digests provided by keymaster implementations. 203 */ 204 enum Digest : uint32_t { 205 NONE = 0, 206 MD5 = 1, /* Optional, may not be implemented in hardware, will be handled in software if 207 * needed. */ 208 SHA1 = 2, 209 SHA_2_224 = 3, 210 SHA_2_256 = 4, 211 SHA_2_384 = 5, 212 SHA_2_512 = 6, 213 }; 214 215 /** 216 * Supported EC curves, used in ECDSA 217 */ 218 enum EcCurve : uint32_t { 219 P_224 = 0, 220 P_256 = 1, 221 P_384 = 2, 222 P_521 = 3, 223 }; 224 225 /** 226 * The origin of a key (or pair), i.e. where it was generated. Note that ORIGIN can be found in 227 * either the hardware-enforced or software-enforced list for a key, indicating whether the key is 228 * hardware or software-based. Specifically, a key with GENERATED in the hardware-enforced list is 229 * guaranteed never to have existed outide the secure hardware. 230 */ 231 enum KeyOrigin : uint32_t { 232 GENERATED = 0, /** Generated in keymaster. Should not exist outside the TEE. */ 233 DERIVED = 1, /** Derived inside keymaster. Likely exists off-device. */ 234 IMPORTED = 2, /** Imported into keymaster. Existed as cleartext in Android. */ 235 UNKNOWN = 3, /* Keymaster did not record origin. This value can only be seen on keys in a 236 * keymaster0 implementation. The keymaster0 adapter uses this value to document 237 * the fact that it is unkown whether the key was generated inside or imported 238 * into keymaster. */ 239 }; 240 241 /** 242 * Usability requirements of key blobs. This defines what system functionality must be available 243 * for the key to function. For example, key "blobs" which are actually handles referencing 244 * encrypted key material stored in the file system cannot be used until the file system is 245 * available, and should have BLOB_REQUIRES_FILE_SYSTEM. Other requirements entries will be added 246 * as needed for implementations. 247 */ 248 enum KeyBlobUsageRequirements : uint32_t { 249 STANDALONE = 0, 250 REQUIRES_FILE_SYSTEM = 1, 251 }; 252 253 /** 254 * Possible purposes of a key (or pair). 255 */ 256 enum KeyPurpose : uint32_t { 257 ENCRYPT = 0, /** Usable with RSA, EC and AES keys. */ 258 DECRYPT = 1, /** Usable with RSA, EC and AES keys. */ 259 SIGN = 2, /** Usable with RSA, EC and HMAC keys. */ 260 VERIFY = 3, /** Usable with RSA, EC and HMAC keys. */ 261 DERIVE_KEY = 4, /** Usable with EC keys. */ 262 WRAP_KEY = 5, /** Usable with wrapping keys. */ 263 }; 264 265 /** 266 * Keymaster error codes. 267 */ 268 enum ErrorCode : uint32_t { 269 OK = 0, 270 ROOT_OF_TRUST_ALREADY_SET = -1, 271 UNSUPPORTED_PURPOSE = -2, 272 INCOMPATIBLE_PURPOSE = -3, 273 UNSUPPORTED_ALGORITHM = -4, 274 INCOMPATIBLE_ALGORITHM = -5, 275 UNSUPPORTED_KEY_SIZE = -6, 276 UNSUPPORTED_BLOCK_MODE = -7, 277 INCOMPATIBLE_BLOCK_MODE = -8, 278 UNSUPPORTED_MAC_LENGTH = -9, 279 UNSUPPORTED_PADDING_MODE = -10, 280 INCOMPATIBLE_PADDING_MODE = -11, 281 UNSUPPORTED_DIGEST = -12, 282 INCOMPATIBLE_DIGEST = -13, 283 INVALID_EXPIRATION_TIME = -14, 284 INVALID_USER_ID = -15, 285 INVALID_AUTHORIZATION_TIMEOUT = -16, 286 UNSUPPORTED_KEY_FORMAT = -17, 287 INCOMPATIBLE_KEY_FORMAT = -18, 288 UNSUPPORTED_KEY_ENCRYPTION_ALGORITHM = -19, /** For PKCS8 & PKCS12 */ 289 UNSUPPORTED_KEY_VERIFICATION_ALGORITHM = -20, /** For PKCS8 & PKCS12 */ 290 INVALID_INPUT_LENGTH = -21, 291 KEY_EXPORT_OPTIONS_INVALID = -22, 292 DELEGATION_NOT_ALLOWED = -23, 293 KEY_NOT_YET_VALID = -24, 294 KEY_EXPIRED = -25, 295 KEY_USER_NOT_AUTHENTICATED = -26, 296 OUTPUT_PARAMETER_NULL = -27, 297 INVALID_OPERATION_HANDLE = -28, 298 INSUFFICIENT_BUFFER_SPACE = -29, 299 VERIFICATION_FAILED = -30, 300 TOO_MANY_OPERATIONS = -31, 301 UNEXPECTED_NULL_POINTER = -32, 302 INVALID_KEY_BLOB = -33, 303 IMPORTED_KEY_NOT_ENCRYPTED = -34, 304 IMPORTED_KEY_DECRYPTION_FAILED = -35, 305 IMPORTED_KEY_NOT_SIGNED = -36, 306 IMPORTED_KEY_VERIFICATION_FAILED = -37, 307 INVALID_ARGUMENT = -38, 308 UNSUPPORTED_TAG = -39, 309 INVALID_TAG = -40, 310 MEMORY_ALLOCATION_FAILED = -41, 311 IMPORT_PARAMETER_MISMATCH = -44, 312 SECURE_HW_ACCESS_DENIED = -45, 313 OPERATION_CANCELLED = -46, 314 CONCURRENT_ACCESS_CONFLICT = -47, 315 SECURE_HW_BUSY = -48, 316 SECURE_HW_COMMUNICATION_FAILED = -49, 317 UNSUPPORTED_EC_FIELD = -50, 318 MISSING_NONCE = -51, 319 INVALID_NONCE = -52, 320 MISSING_MAC_LENGTH = -53, 321 KEY_RATE_LIMIT_EXCEEDED = -54, 322 CALLER_NONCE_PROHIBITED = -55, 323 KEY_MAX_OPS_EXCEEDED = -56, 324 INVALID_MAC_LENGTH = -57, 325 MISSING_MIN_MAC_LENGTH = -58, 326 UNSUPPORTED_MIN_MAC_LENGTH = -59, 327 UNSUPPORTED_KDF = -60, 328 UNSUPPORTED_EC_CURVE = -61, 329 KEY_REQUIRES_UPGRADE = -62, 330 ATTESTATION_CHALLENGE_MISSING = -63, 331 KEYMASTER_NOT_CONFIGURED = -64, 332 ATTESTATION_APPLICATION_ID_MISSING = -65, 333 CANNOT_ATTEST_IDS = -66, 334 335 UNIMPLEMENTED = -100, 336 VERSION_MISMATCH = -101, 337 338 UNKNOWN_ERROR = -1000, 339 }; 340 341 /** 342 * Key derivation functions, mostly used in ECIES. 343 */ 344 enum KeyDerivationFunction : uint32_t { 345 /** Do not apply a key derivation function; use the raw agreed key */ 346 NONE = 0, 347 /** HKDF defined in RFC 5869 with SHA256 */ 348 RFC5869_SHA256 = 1, 349 /** KDF1 defined in ISO 18033-2 with SHA1 */ 350 ISO18033_2_KDF1_SHA1 = 2, 351 /** KDF1 defined in ISO 18033-2 with SHA256 */ 352 ISO18033_2_KDF1_SHA256 = 3, 353 /** KDF2 defined in ISO 18033-2 with SHA1 */ 354 ISO18033_2_KDF2_SHA1 = 4, 355 /** KDF2 defined in ISO 18033-2 with SHA256 */ 356 ISO18033_2_KDF2_SHA256 = 5, 357 }; 358 359 /** 360 * Hardware authentication type, used by HardwareAuthTokens to specify the mechanism used to 361 * authentiate the user, and in KeyCharacteristics to specify the allowable mechanisms for 362 * authenticating to activate a key. 363 */ 364 enum HardwareAuthenticatorType : uint32_t { 365 NONE = 0, 366 PASSWORD = 1 << 0, 367 FINGERPRINT = 1 << 1, 368 // Additional entries must be powers of 2. 369 ANY = 0xFFFFFFFF, 370 }; 371 372 struct KeyParameter { 373 /** 374 * Discriminates the uinon/blob field used. The blob cannot be coincided with the union, but 375 * only one of "f" and "blob" is ever used at a time. */ 376 Tag tag; 377 union IntegerParams { 378 /** Enum types */ 379 Algorithm algorithm; 380 BlockMode blockMode; 381 PaddingMode paddingMode; 382 Digest digest; 383 EcCurve ecCurve; 384 KeyOrigin origin; 385 KeyBlobUsageRequirements keyBlobUsageRequirements; 386 KeyPurpose purpose; 387 KeyDerivationFunction keyDerivationFunction; 388 HardwareAuthenticatorType hardwareAuthenticatorType; 389 390 /** Other types */ 391 bool boolValue; // Always true, if a boolean tag is present. 392 uint32_t integer; 393 uint64_t longInteger; 394 uint64_t dateTime; 395 }; 396 IntegerParams f; // Hidl does not support anonymous unions, so we have to name it. 397 vec<uint8_t> blob; 398 }; 399 400 struct KeyCharacteristics { 401 vec<KeyParameter> softwareEnforced; 402 vec<KeyParameter> teeEnforced; 403 }; 404 405 /** 406 * Data used to prove successful authentication. 407 */ 408 struct HardwareAuthToken { 409 uint64_t challenge; 410 uint64_t userId; // Secure User ID, not Android user ID. 411 uint64_t authenticatorId; // Secure authenticator ID. 412 uint32_t authenticatorType; // HardwareAuthenticatorType, in network order. 413 uint64_t timestamp; // In network order. 414 uint8_t[32] hmac; // HMAC is computed over 0 || challenge || user_id || 415 // authenticator_id || authenticator_type || timestamp, with a 416 // prefixed 0 byte (which was a version field in Keymaster1 and 417 // Keymaster2) and the fields packed (no padding; so you probably 418 // can't just compute over the bytes of the struct). 419 }; 420 421 enum SecurityLevel : uint32_t { 422 SOFTWARE = 0, 423 TRUSTED_ENVIRONMENT = 1, 424 }; 425 426 /** 427 * Formats for key import and export. 428 */ 429 enum KeyFormat : uint32_t { 430 X509 = 0, /** for public key export */ 431 PKCS8 = 1, /** for asymmetric key pair import */ 432 RAW = 3, /* for symmetric key import and export*/ 433 }; 434 435 typedef uint64_t OperationHandle; 436
