1/* 2 * Copyright (C) 2017 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 [email protected]; 18 19/** 20 * Time in milliseconds since some arbitrary point in time. Time must be monotonically increasing, 21 * and a secure environment's notion of "current time" must not repeat until the Android device 22 * reboots, or until at least 50 million years have elapsed (note that this requirement is satisfied 23 * by setting the clock to zero during each boot, and then counting time accurately). 24 */ 25typedef uint64_t Timestamp; 26 27/** 28 * A place to define any needed constants. 29 */ 30enum Constants : uint32_t { 31 AUTH_TOKEN_MAC_LENGTH = 32, 32}; 33 34enum TagType : uint32_t { 35 /** Invalid type, used to designate a tag as uninitialized. */ 36 INVALID = 0 << 28, 37 /** Enumeration value. */ 38 ENUM = 1 << 28, 39 /** Repeatable enumeration value. */ 40 ENUM_REP = 2 << 28, 41 /** 32-bit unsigned integer. */ 42 UINT = 3 << 28, 43 /** Repeatable 32-bit unsigned integer. */ 44 UINT_REP = 4 << 28, 45 /** 64-bit unsigned integer. */ 46 ULONG = 5 << 28, 47 /** 64-bit unsigned integer representing a date and time, in milliseconds since 1 Jan 1970. */ 48 DATE = 6 << 28, 49 /** Boolean. If a tag with this type is present, the value is "true". If absent, "false". */ 50 BOOL = 7 << 28, 51 /** Byte string containing an arbitrary-length integer, big-endian ordering. */ 52 BIGNUM = 8 << 28, 53 /** Byte string */ 54 BYTES = 9 << 28, 55 /** Repeatable 64-bit unsigned integer */ 56 ULONG_REP = 10 << 28, 57}; 58 59enum Tag : uint32_t { 60 INVALID = TagType:INVALID | 0, 61 62 /** 63 * Tag::PURPOSE specifies the set of purposes for which the key may be used. Possible values 64 * are defined in the KeyPurpose enumeration. 65 * 66 * This tag is repeatable; keys may be generated with multiple values, although an operation has 67 * a single purpose. When begin() is called to start an operation, the purpose of the operation 68 * is specified. If the purpose specified for the operation is not authorized by the key (the 69 * key didn't have a corresponding Tag::PURPOSE provided during generation/import), the 70 * operation must fail with ErrorCode::INCOMPATIBLE_PURPOSE. 71 * 72 * Must be hardware-enforced. 73 */ 74 PURPOSE = TagType:ENUM_REP | 1, 75 76 /** 77 * Tag::ALGORITHM specifies the cryptographic algorithm with which the key is used. This tag 78 * must be provided to generateKey and importKey, and must be specified in the wrapped key 79 * provided to importWrappedKey. 80 * 81 * Must be hardware-enforced. 82 */ 83 ALGORITHM = TagType:ENUM | 2, 84 85 /** 86 * Tag::KEY_SIZE pecifies the size, in bits, of the key, measuring in the normal way for the 87 * key's algorithm. For example, for RSA keys, Tag::KEY_SIZE specifies the size of the public 88 * modulus. For AES keys it specifies the length of the secret key material. For 3DES keys it 89 * specifies the length of the key material, not counting parity bits (though parity bits must 90 * be provided for import, etc.). Since only three-key 3DES keys are supported, 3DES 91 * Tag::KEY_SIZE must be 168. 92 * 93 * Must be hardware-enforced. 94 */ 95 KEY_SIZE = TagType:UINT | 3, 96 97 /** 98 * Tag::BLOCK_MODE specifies the block cipher mode(s) with which the key may be used. This tag 99 * is only relevant to AES and 3DES keys. Possible values are defined by the BlockMode enum. 100 * 101 * This tag is repeatable for key generation/import. For AES and 3DES operations the caller 102 * must specify a Tag::BLOCK_MODE in the additionalParams argument of begin(). If the mode is 103 * missing or the specified mode is not in the modes specified for the key during 104 * generation/import, the operation must fail with ErrorCode::INCOMPATIBLE_BLOCK_MODE. 105 * 106 * Must be hardware-enforced. 107 */ 108 BLOCK_MODE = TagType:ENUM_REP | 4, /* BlockMode. */ 109 110 /** 111 * Tag::DIGEST specifies the digest algorithms that may be used with the key to perform signing 112 * and verification operations. This tag is relevant to RSA, ECDSA and HMAC keys. Possible 113 * values are defined by the Digest enum. 114 * 115 * This tag is repeatable for key generation/import. For signing and verification operations, 116 * the caller must specify a digest in the additionalParams argument of begin(). If the digest 117 * is missing or the specified digest is not in the digests associated with the key, the 118 * operation must fail with ErrorCode::INCOMPATIBLE_DIGEST. 119 * 120 * Must be hardware-enforced. 121 */ 122 DIGEST = TagType:ENUM_REP | 5, 123 124 /** 125 * Tag::PADDING specifies the padding modes that may be used with the key. This tag is relevant 126 * to RSA, AES and 3DES keys. Possible values are defined by the PaddingMode enum. 127 * 128 * PaddingMode::RSA_OAEP and PaddingMode::RSA_PKCS1_1_5_ENCRYPT are used only for RSA 129 * encryption/decryption keys and specify RSA OAEP padding and RSA PKCS#1 v1.5 randomized 130 * padding, respectively. PaddingMode::RSA_PSS and PaddingMode::RSA_PKCS1_1_5_SIGN are used 131 * only for RSA signing/verification keys and specify RSA PSS padding and RSA PKCS#1 v1.5 132 * deterministic padding, respectively. 133 * 134 * PaddingMode::NONE may be used with either RSA, AES or 3DES keys. For AES or 3DES keys, if 135 * PaddingMode::NONE is used with block mode ECB or CBC and the data to be encrypted or 136 * decrypted is not a multiple of the AES block size in length, the call to finish() must fail 137 * with ErrorCode::INVALID_INPUT_LENGTH. 138 * 139 * PaddingMode::PKCS7 may only be used with AES and 3DES keys, and only with ECB and CBC modes. 140 * 141 * In any case, if the caller specifies a padding mode that is not usable with the key's 142 * algorithm, the generation or import method must return ErrorCode::INCOMPATIBLE_PADDING_MODE. 143 * 144 * This tag is repeatable. A padding mode must be specified in the call to begin(). If the 145 * specified mode is not authorized for the key, the operation must fail with 146 * ErrorCode::INCOMPATIBLE_BLOCK_MODE. 147 * 148 * Must be hardware-enforced. 149 */ 150 PADDING = TagType:ENUM_REP | 6, 151 152 /** 153 * Tag::CALLER_NONCE specifies that the caller can provide a nonce for nonce-requiring 154 * operations. This tag is boolean, so the possible values are true (if the tag is present) and 155 * false (if the tag is not present). 156 * 157 * This tag is used only for AES and 3DES keys, and is only relevant for CBC, CTR and GCM block 158 * modes. If the tag is not present in a key's authorization list, implementations must reject 159 * any operation that provides Tag::NONCE to begin() with ErrorCode::CALLER_NONCE_PROHIBITED. 160 * 161 * Must be hardware-enforced. 162 */ 163 CALLER_NONCE = TagType:BOOL | 7, 164 165 /** 166 * Tag::MIN_MAC_LENGTH specifies the minimum length of MAC that can be requested or verified 167 * with this key for HMAC keys and AES keys that support GCM mode. 168 * 169 * This value is the minimum MAC length, in bits. It must be a multiple of 8 bits. For HMAC 170 * keys, the value must be least 64 and no more than 512. For GCM keys, the value must be at 171 * least 96 and no more than 128. If the provided value violates these requirements, 172 * generateKey() or importKey() must return ErrorCode::UNSUPPORTED_KEY_SIZE. 173 * 174 * Must be hardware-enforced. 175 */ 176 MIN_MAC_LENGTH = TagType:UINT | 8, 177 178 // Tag 9 reserved 179 180 /** 181 * Tag::EC_CURVE specifies the elliptic curve. EC key generation requests may have 182 * Tag:EC_CURVE, Tag::KEY_SIZE, or both. If both are provided and the size and curve do not 183 * match, IKeymasterDevice must return ErrorCode::INVALID_ARGUMENT. 184 * 185 * Must be hardware-enforced. 186 */ 187 EC_CURVE = TagType:ENUM | 10, 188 189 /** 190 * Tag::RSA_PUBLIC_EXPONENT specifies the value of the public exponent for an RSA key pair. 191 * This tag is relevant only to RSA keys, and is required for all RSA keys. 192 * 193 * The value is a 64-bit unsigned integer that satisfies the requirements of an RSA public 194 * exponent. This value must be a prime number. IKeymasterDevice implementations must support 195 * the value 2^16+1 and may support other reasonable values. If no exponent is specified or if 196 * the specified exponent is not supported, key generation must fail with 197 * ErrorCode::INVALID_ARGUMENT. 198 * 199 * Must be hardware-enforced. 200 */ 201 RSA_PUBLIC_EXPONENT = TagType:ULONG | 200, 202 203 // Tag 201 reserved 204 205 /** 206 * Tag::INCLUDE_UNIQUE_ID is specified during key generation to indicate that an attestation 207 * certificate for the generated key should contain an application-scoped and time-bounded 208 * device-unique ID. See Tag::UNIQUE_ID. 209 * 210 * Must be hardware-enforced. 211 */ 212 INCLUDE_UNIQUE_ID = TagType:BOOL | 202, 213 214 /** 215 * Tag::BLOB_USAGE_REQUIREMENTS specifies the necessary system environment conditions for the 216 * generated key to be used. Possible values are defined by the KeyBlobUsageRequirements enum. 217 * 218 * This tag is specified by the caller during key generation or import to require that the key 219 * is usable in the specified condition. If the caller specifies Tag::BLOB_USAGE_REQUIREMENTS 220 * with value KeyBlobUsageRequirements::STANDALONE the IKeymasterDevice must return a key blob 221 * that can be used without file system support. This is critical for devices with encrypted 222 * disks, where the file system may not be available until after a Keymaster key is used to 223 * decrypt the disk. 224 * 225 * Must be hardware-enforced. 226 */ 227 BLOB_USAGE_REQUIREMENTS = TagType:ENUM | 301, 228 229 /** 230 * Tag::BOOTLOADER_ONLY specifies only the bootloader can use the key. 231 * 232 * Any attempt to use a key with Tag::BOOTLOADER_ONLY from the Android system must fail with 233 * ErrorCode::INVALID_KEY_BLOB. 234 * 235 * Must be hardware-enforced. 236 */ 237 BOOTLOADER_ONLY = TagType:BOOL | 302, 238 239 /** 240 * Tag::ROLLBACK_RESISTANCE specifies that the key has rollback resistance, meaning that when 241 * deleted with deleteKey() or deleteAllKeys(), the key is guaranteed to be permanently deleted 242 * and unusable. It's possible that keys without this tag could be deleted and then restored 243 * from backup. 244 * 245 * This tag is specified by the caller during key generation or import to require. If the 246 * IKeymasterDevice cannot guarantee rollback resistance for the specified key, it must return 247 * ErrorCode::ROLLBACK_RESISTANCE_UNAVAILABLE. IKeymasterDevice implementations are not 248 * required to support rollback resistance. 249 * 250 * Must be hardwared-enforced. 251 */ 252 ROLLBACK_RESISTANCE = TagType:BOOL | 303, 253 254 // Reserved for future use. 255 HARDWARE_TYPE = TagType:ENUM | 304, 256 257 /** 258 * Tag::ACTIVE_DATETIME specifies the date and time at which the key becomes active, in 259 * milliseconds since Jan 1, 1970. If a key with this tag is used prior to the specified date 260 * and time, IKeymasterDevice::begin() must return ErrorCode::KEY_NOT_YET_VALID; 261 * 262 * Need not be hardware-enforced. 263 */ 264 ACTIVE_DATETIME = TagType:DATE | 400, /* Start of validity. */ 265 266 /** 267 * Tag::ORIGINATION_EXPIRE_DATETIME specifies the date and time at which the key expires for 268 * signing and encryption purposes. After this time, any attempt to use a key with 269 * KeyPurpose::SIGN or KeyPurpose::ENCRYPT provided to begin() must fail with 270 * ErrorCode::KEY_EXPIRED. 271 * 272 * The value is a 64-bit integer representing milliseconds since January 1, 1970. 273 * 274 * Need not be hardware-enforced. 275 */ 276 ORIGINATION_EXPIRE_DATETIME = TagType:DATE | 401, 277 278 /** 279 * Tag::USAGE_EXPIRE_DATETIME specifies the date and time at which the key expires for 280 * verification and decryption purposes. After this time, any attempt to use a key with 281 * KeyPurpose::VERIFY or KeyPurpose::DECRYPT provided to begin() must fail with 282 * ErrorCode::KEY_EXPIRED. 283 * 284 * The value is a 64-bit integer representing milliseconds since January 1, 1970. 285 * 286 * Need not be hardware-enforced. 287 */ 288 USAGE_EXPIRE_DATETIME = TagType:DATE | 402, 289 290 /** 291 * Tag::MIN_SECONDS_BETWEEN_OPS specifies the minimum amount of time that elapses between 292 * allowed operations using a key. This can be used to rate-limit uses of keys in contexts 293 * where unlimited use may enable brute force attacks. 294 * 295 * The value is a 32-bit integer representing seconds between allowed operations. 296 * 297 * When a key with this tag is used in an operation, the IKeymasterDevice must start a timer 298 * during the finish() or abort() call. Any call to begin() that is received before the timer 299 * indicates that the interval specified by Tag::MIN_SECONDS_BETWEEN_OPS has elapsed must fail 300 * with ErrorCode::KEY_RATE_LIMIT_EXCEEDED. This implies that the IKeymasterDevice must keep a 301 * table of use counters for keys with this tag. Because memory is often limited, this table 302 * may have a fixed maximum size and Keymaster may fail operations that attempt to use keys with 303 * this tag when the table is full. The table must acommodate at least 8 in-use keys and 304 * aggressively reuse table slots when key minimum-usage intervals expire. If an operation 305 * fails because the table is full, Keymaster returns ErrorCode::TOO_MANY_OPERATIONS. 306 * 307 * Must be hardware-enforced. 308 */ 309 MIN_SECONDS_BETWEEN_OPS = TagType:UINT | 403, 310 311 /** 312 * Tag::MAX_USES_PER_BOOT specifies the maximum number of times that a key may be used between 313 * system reboots. This is another mechanism to rate-limit key use. 314 * 315 * The value is a 32-bit integer representing uses per boot. 316 * 317 * When a key with this tag is used in an operation, a key-associated counter must be 318 * incremented during the begin() call. After the key counter has exceeded this value, all 319 * subsequent attempts to use the key must fail with ErrorCode::MAX_OPS_EXCEEDED, until the 320 * device is restarted. This implies that the IKeymasterDevice must keep a table of use 321 * counters for keys with this tag. Because Keymaster memory is often limited, this table can 322 * have a fixed maximum size and Keymaster can fail operations that attempt to use keys with 323 * this tag when the table is full. The table needs to acommodate at least 8 keys. If an 324 * operation fails because the table is full, IKeymasterDevice must 325 * ErrorCode::TOO_MANY_OPERATIONS. 326 * 327 * Must be hardware-enforced. 328 */ 329 MAX_USES_PER_BOOT = TagType:UINT | 404, 330 331 /** 332 * Tag::USER_ID specifies the ID of the Android user that is permitted to use the key. 333 * 334 * Must not be hardware-enforced. 335 */ 336 USER_ID = TagType:UINT | 501, 337 338 /** 339 * Tag::USER_SECURE_ID specifies that a key may only be used under a particular secure user 340 * authentication state. This tag is mutually exclusive with Tag::NO_AUTH_REQUIRED. 341 * 342 * The value is a 64-bit integer specifying the authentication policy state value which must be 343 * present in the userId or authenticatorId field of a HardwareAuthToken provided to begin(), 344 * update(), or finish(). If a key with Tag::USER_SECURE_ID is used without a HardwareAuthToken 345 * with the matching userId or authenticatorId, the IKeymasterDevice must return 346 * ErrorCode::KEY_USER_NOT_AUTHENTICATED. 347 * 348 * Tag::USER_SECURE_ID interacts with Tag::AUTH_TIMEOUT in a very important way. If 349 * Tag::AUTH_TIMEOUT is present in the key's characteristics then the key is a "timeout-based" 350 * key, and may only be used if the difference between the current time when begin() is called 351 * and the timestamp in the HardwareAuthToken is less than the value in Tag::AUTH_TIMEOUT * 1000 352 * (the multiplier is because Tag::AUTH_TIMEOUT is in seconds, but the HardwareAuthToken 353 * timestamp is in milliseconds). Otherwise the IKeymasterDevice must returrn 354 * ErrorCode::KEY_USER_NOT_AUTHENTICATED. 355 * 356 * If Tag::AUTH_TIMEOUT is not present, then the key is an "auth-per-operation" key. In this 357 * case, begin() must not require a HardwareAuthToken with appropriate contents. Instead, 358 * update() and finish() must receive a HardwareAuthToken with Tag::USER_SECURE_ID value in 359 * userId or authenticatorId fields, and the current operation's operation handle in the 360 * challenge field. Otherwise the IKeymasterDevice must returrn 361 * ErrorCode::KEY_USER_NOT_AUTHENTICATED. 362 * 363 * This tag is repeatable. If repeated, and any one of the values matches the HardwareAuthToken 364 * as described above, the key is authorized for use. Otherwise the operation must fail with 365 * ErrorCode::KEY_USER_NOT_AUTHENTICATED. 366 * 367 * Must be hardware-enforced. 368 */ 369 USER_SECURE_ID = TagType:ULONG_REP | 502, /* Secure ID of authorized user or authenticator(s). 370 * Disallowed if NO_AUTH_REQUIRED is present. */ 371 372 /** 373 * Tag::NO_AUTH_REQUIRED specifies that no authentication is required to use this key. This tag 374 * is mutually exclusive with Tag::USER_SECURE_ID. 375 * 376 * Must be hardware-enforced. 377 */ 378 NO_AUTH_REQUIRED = TagType:BOOL | 503, /* If key is usable without authentication. */ 379 380 /** 381 * Tag::USER_AUTH_TYPE specifies the types of user authenticators that may be used to authorize 382 * this key. 383 * 384 * The value is one or more values from HardwareAuthenticatorType, ORed together. 385 * 386 * When IKeymasterDevice is requested to perform an operation with a key with this tag, it must 387 * receive a HardwareAuthToken and one or more bits must be set in both the HardwareAuthToken's 388 * authenticatorType field and the Tag::USER_AUTH_TYPE value. That is, it must be true that 389 * 390 * (token.authenticatorType & tag_user_auth_type) != 0 391 * 392 * where token.authenticatorType is the authenticatorType field of the HardwareAuthToken and 393 * tag_user_auth_type is the value of Tag:USER_AUTH_TYPE. 394 * 395 * Must be hardware-enforced. 396 */ 397 USER_AUTH_TYPE = TagType:ENUM | 504, 398 399 /** 400 * Tag::AUTH_TIMEOUT specifies the time in seconds for which the key is authorized for use, 401 * after user authentication. If 402 * Tag::USER_SECURE_ID is present and this tag is not, then the key requies authentication for 403 * every usage (see begin() for the details of the authentication-per-operation flow). 404 * 405 * The value is a 32-bit integer specifying the time in seconds after a successful 406 * authentication of the user specified by Tag::USER_SECURE_ID with the authentication method 407 * specified by Tag::USER_AUTH_TYPE that the key can be used. 408 * 409 * Must be hardware-enforced. 410 */ 411 AUTH_TIMEOUT = TagType:UINT | 505, 412 413 /** 414 * Tag::ALLOW_WHILE_ON_BODY specifies that the key may be used after authentication timeout if 415 * device is still on-body (requires on-body sensor). 416 * 417 * Cannot be hardware-enforced. 418 */ 419 ALLOW_WHILE_ON_BODY = TagType:BOOL | 506, 420 421 /** 422 * TRUSTED_USER_PRESENCE_REQUIRED is an optional feature that specifies that this key must be 423 * unusable except when the user has provided proof of physical presence. Proof of physical 424 * presence must be a signal that cannot be triggered by an attacker who doesn't have one of: 425 * 426 * a) Physical control of the device or 427 * 428 * b) Control of the secure environment that holds the key. 429 * 430 * For instance, proof of user identity may be considered proof of presence if it meets the 431 * requirements. However, proof of identity established in one security domain (e.g. TEE) does 432 * not constitute proof of presence in another security domain (e.g. StrongBox), and no 433 * mechanism analogous to the authentication token is defined for communicating proof of 434 * presence across security domains. 435 * 436 * Some examples: 437 * 438 * A hardware button hardwired to a pin on a StrongBox device in such a way that nothing 439 * other than a button press can trigger the signal constitutes proof of physical presence 440 * for StrongBox keys. 441 * 442 * Fingerprint authentication provides proof of presence (and identity) for TEE keys if the 443 * TEE has exclusive control of the fingerprint scanner and performs fingerprint matching. 444 * 445 * Password authentication does not provide proof of presence to either TEE or StrongBox, 446 * even if TEE or StrongBox does the password matching, because password input is handled by 447 * the non-secure world, which means an attacker who has compromised Android can spoof 448 * password authentication. 449 * 450 * Note that no mechanism is defined for delivering proof of presence to an IKeymasterDevice, 451 * except perhaps as implied by an auth token. This means that Keymaster must be able to check 452 * proof of presence some other way. Further, the proof of presence must be performed between 453 * begin() and the first call to update() or finish(). If the first update() or the finish() 454 * call is made without proof of presence, the keymaster method must return 455 * ErrorCode::PROOF_OF_PRESENCE_REQUIRED and abort the operation. The caller must delay the 456 * update() or finish() call until proof of presence has been provided, which means the caller 457 * must also have some mechanism for verifying that the proof has been provided. 458 * 459 * Only one operation requiring TUP may be in flight at a time. If begin() has already been 460 * called on one key with TRUSTED_USER_PRESENCE_REQUIRED, and another begin() comes in for that 461 * key or another with TRUSTED_USER_PRESENCE_REQUIRED, Keymaster must return 462 * ErrorCode::CONCURRENT_PROOF_OF_PRESENCE_REQUESTED. 463 * 464 * Must be hardware-enforced. 465 */ 466 TRUSTED_USER_PRESENCE_REQUIRED = TagType:BOOL | 507, 467 468 /** Tag::TRUSTED_CONFIRMATION_REQUIRED is only applicable to keys with KeyPurpose SIGN, and 469 * specifies that this key must not be usable unless the user provides confirmation of the data 470 * to be signed. Confirmation is proven to keymaster via an approval token. See 471 * CONFIRMATION_TOKEN, as well as the ConfirmatinUI HAL. 472 * 473 * If an attempt to use a key with this tag does not have a cryptographically valid 474 * CONFIRMATION_TOKEN provided to finish() or if the data provided to update()/finish() does not 475 * match the data described in the token, keymaster must return NO_USER_CONFIRMATION. 476 * 477 * Must be hardware-enforced. 478 */ 479 TRUSTED_CONFIRMATION_REQUIRED = TagType:BOOL | 508, 480 481 /** 482 * Tag::UNLOCKED_DEVICE_REQUIRED specifies that the key may only be used when the device is 483 * unlocked. 484 * 485 * Must be software-enforced. 486 */ 487 UNLOCKED_DEVICE_REQUIRED = TagType:BOOL | 509, 488 489 /** 490 * Tag::APPLICATION_ID. When provided to generateKey or importKey, this tag specifies data 491 * that is necessary during all uses of the key. In particular, calls to exportKey() and 492 * getKeyCharacteristics() must provide the same value to the clientId parameter, and calls to 493 * begin must provide this tag and the same associated data as part of the inParams set. If 494 * the correct data is not provided, the method must return ErrorCode::INVALID_KEY_BLOB. 495 * 496 * The content of this tag must be bound to the key cryptographically, meaning it must not be 497 * possible for an adversary who has access to all of the secure world secrets but does not have 498 * access to the tag content to decrypt the key without brute-forcing the tag content, which 499 * applications can prevent by specifying sufficiently high-entropy content. 500 * 501 * Must never appear in KeyCharacteristics. 502 */ 503 APPLICATION_ID = TagType:BYTES | 601, 504 505 /* 506 * Semantically unenforceable tags, either because they have no specific meaning or because 507 * they're informational only. 508 */ 509 510 /** 511 * Tag::APPLICATION_DATA. When provided to generateKey or importKey, this tag specifies data 512 * that is necessary during all uses of the key. In particular, calls to exportKey() and 513 * getKeyCharacteristics() must provide the same value to the appData parameter, and calls to 514 * begin must provide this tag and the same associated data as part of the inParams set. If 515 * the correct data is not provided, the method must return ErrorCode::INVALID_KEY_BLOB. 516 * 517 * The content of this tag msut be bound to the key cryptographically, meaning it must not be 518 * possible for an adversary who has access to all of the secure world secrets but does not have 519 * access to the tag content to decrypt the key without brute-forcing the tag content, which 520 * applications can prevent by specifying sufficiently high-entropy content. 521 * 522 * Must never appear in KeyCharacteristics. 523 */ 524 APPLICATION_DATA = TagType:BYTES | 700, 525 526 /** 527 * Tag::CREATION_DATETIME specifies the date and time the key was created, in milliseconds since 528 * January 1, 1970. This tag is optional and informational only. 529 * 530 * Tag::CREATED is informational only, and not enforced by anything. Must be in the 531 * software-enforced list, if provided. 532 */ 533 CREATION_DATETIME = TagType:DATE | 701, 534 535 /** 536 * Tag::ORIGIN specifies where the key was created, if known. This tag must not be specified 537 * during key generation or import, and must be added to the key characteristics by the 538 * IKeymasterDevice. The possible values are defined in the KeyOrigin enum. 539 * 540 * Must be hardware-enforced. 541 */ 542 ORIGIN = TagType:ENUM | 702, 543 544 // 703 is unused. 545 546 /** 547 * Tag::ROOT_OF_TRUST specifies the root of trust, the key used by verified boot to validate the 548 * operating system booted (if any). This tag is never provided to or returned from Keymaster 549 * in the key characteristics. It exists only to define the tag for use in the attestation 550 * record. 551 * 552 * Must never appear in KeyCharacteristics. 553 */ 554 ROOT_OF_TRUST = TagType:BYTES | 704, 555 556 /** 557 * Tag::OS_VERSION specifies the system OS version with which the key may be used. This tag is 558 * never sent to the IKeymasterDevice, but is added to the hardware-enforced authorization list 559 * by the TA. Any attempt to use a key with a Tag::OS_VERSION value different from the 560 * currently-running OS version must cause begin(), getKeyCharacteristics() or exportKey() to 561 * return ErrorCode::KEY_REQUIRES_UPGRADE. See upgradeKey() for details. 562 * 563 * The value of the tag is an integer of the form MMmmss, where MM is the major version number, 564 * mm is the minor version number, and ss is the sub-minor version number. For example, for a 565 * key generated on Android version 4.0.3, the value would be 040003. 566 * 567 * The IKeymasterDevice HAL must read the current OS version from the system property 568 * ro.build.version.release and deliver it to the secure environment when the HAL is first 569 * loaded (mechanism is implementation-defined). The secure environment must not accept another 570 * version until after the next boot. If the content of ro.build.version.release has additional 571 * version information after the sub-minor version number, it must not be included in 572 * Tag::OS_VERSION. If the content is non-numeric, the secure environment must use 0 as the 573 * system version. 574 * 575 * Must be hardware-enforced. 576 */ 577 OS_VERSION = TagType:UINT | 705, 578 579 /** 580 * Tag::OS_PATCHLEVEL specifies the system security patch level with which the key may be used. 581 * This tag is never sent to the keymaster TA, but is added to the hardware-enforced 582 * authorization list by the TA. Any attempt to use a key with a Tag::OS_PATCHLEVEL value 583 * different from the currently-running system patchlevel must cause begin(), 584 * getKeyCharacteristics() or exportKey() to return ErrorCode::KEY_REQUIRES_UPGRADE. See 585 * upgradeKey() for details. 586 * 587 * The value of the tag is an integer of the form YYYYMM, where YYYY is the four-digit year of 588 * the last update and MM is the two-digit month of the last update. For example, for a key 589 * generated on an Android device last updated in December 2015, the value would be 201512. 590 * 591 * The IKeymasterDevice HAL must read the current system patchlevel from the system property 592 * ro.build.version.security_patch and deliver it to the secure environment when the HAL is 593 * first loaded (mechanism is implementation-defined). The secure environment must not accept 594 * another patchlevel until after the next boot. 595 * 596 * Must be hardware-enforced. 597 */ 598 OS_PATCHLEVEL = TagType:UINT | 706, 599 600 /** 601 * Tag::UNIQUE_ID specifies a unique, time-based identifier. This tag is never provided to or 602 * returned from Keymaster in the key characteristics. It exists only to define the tag for use 603 * in the attestation record. 604 * 605 * When a key with Tag::INCLUDE_UNIQUE_ID is attested, the unique ID is added to the attestation 606 * record. The value is a 128-bit hash that is unique per device and per calling application, 607 * and changes monthly and on most password resets. It is computed with: 608 * 609 * HMAC_SHA256(T || C || R, HBK) 610 * 611 * Where: 612 * 613 * T is the "temporal counter value", computed by dividing the value of 614 * Tag::CREATION_DATETIME by 2592000000, dropping any remainder. T changes every 30 days 615 * (2592000000 = 30 * 24 * 60 * 60 * 1000). 616 * 617 * C is the value of Tag::ATTESTATION_APPLICATION_ID that is provided to attestKey(). 618 * 619 * R is 1 if Tag::RESET_SINCE_ID_ROTATION was provided to attestKey or 0 if the tag was not 620 * provided. 621 * 622 * HBK is a unique hardware-bound secret known to the secure environment and never revealed 623 * by it. The secret must contain at least 128 bits of entropy and be unique to the 624 * individual device (probabilistic uniqueness is acceptable). 625 * 626 * HMAC_SHA256 is the HMAC function, with SHA-2-256 as the hash. 627 * 628 * The output of the HMAC function must be truncated to 128 bits. 629 * 630 * Must be hardware-enforced. 631 */ 632 UNIQUE_ID = TagType:BYTES | 707, 633 634 /** 635 * Tag::ATTESTATION_CHALLENGE is used to deliver a "challenge" value to the attestKey() method, 636 * which must place the value in the KeyDescription SEQUENCE of the attestation extension. See 637 * attestKey(). 638 * 639 * Must never appear in KeyCharacteristics. 640 */ 641 ATTESTATION_CHALLENGE = TagType:BYTES | 708, /* Used to provide challenge in attestation */ 642 643 /** 644 * Tag::ATTESTATION_APPLICATION_ID identifies the set of applications which may use a key, used 645 * only with attestKey(). 646 * 647 * The content of Tag::ATTESTATION_APPLICATION_ID is a DER-encoded ASN.1 structure, with the 648 * following schema: 649 * 650 * AttestationApplicationId ::= SEQUENCE { 651 * packageInfoRecords SET OF PackageInfoRecord, 652 * signatureDigests SET OF OCTET_STRING, 653 * } 654 * 655 * PackageInfoRecord ::= SEQUENCE { 656 * packageName OCTET_STRING, 657 * version INTEGER, 658 * } 659 * 660 * See system/security/keystore/keystore_attestation_id.cpp for details of construction. 661 * IKeymasterDevice implementers do not need to create or parse the ASN.1 structure, but only 662 * copy the tag value into the attestation record. The DER-encoded string must not exceed 1 KiB 663 * in length. 664 * 665 * Cannot be hardware-enforced. 666 */ 667 ATTESTATION_APPLICATION_ID = TagType:BYTES | 709, 668 669 /** 670 * Tag::ATTESTATION_ID_BRAND provides the device's brand name, as returned by Build.BRAND in 671 * Android, to attestKey(). This field must be set only when requesting attestation of the 672 * device's identifiers. 673 * 674 * If the device does not support ID attestation (or destroyAttestationIds() was previously 675 * called and the device can no longer attest its IDs), any key attestation request that 676 * includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS. 677 * 678 * Must never appear in KeyCharacteristics. 679 */ 680 ATTESTATION_ID_BRAND = TagType:BYTES | 710, 681 682 /** 683 * Tag::ATTESTATION_ID_DEVICE provides the device's device name, as returned by Build.DEVICE in 684 * Android, to attestKey(). This field must be set only when requesting attestation of the 685 * device's identifiers. 686 * 687 * If the device does not support ID attestation (or destroyAttestationIds() was previously 688 * called and the device can no longer attest its IDs), any key attestation request that 689 * includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS. 690 * 691 * Must never appear in KeyCharacteristics. 692 */ 693 ATTESTATION_ID_DEVICE = TagType:BYTES | 711, 694 695 /** 696 * Tag::ATTESTATION_ID_PRODUCT provides the device's product name, as returned by Build.PRODUCT 697 * in Android, to attestKey(). This field must be set only when requesting attestation of the 698 * device's identifiers. 699 * 700 * If the device does not support ID attestation (or destroyAttestationIds() was previously 701 * called and the device can no longer attest its IDs), any key attestation request that 702 * includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS. 703 * 704 * Must never appear in KeyCharacteristics. 705 */ 706 ATTESTATION_ID_PRODUCT = TagType:BYTES | 712, 707 708 /** 709 * Tag::ATTESTATION_ID_SERIAL the device's serial number. This field must be set only when 710 * requesting attestation of the device's identifiers. 711 * 712 * If the device does not support ID attestation (or destroyAttestationIds() was previously 713 * called and the device can no longer attest its IDs), any key attestation request that 714 * includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS. 715 * 716 * Must never appear in KeyCharacteristics. 717 */ 718 ATTESTATION_ID_SERIAL = TagType:BYTES | 713, 719 720 /** 721 * Tag::ATTESTATION_ID_IMEI provides the IMEIs for all radios on the device to attestKey(). 722 * This field must be set only when requesting attestation of the device's identifiers. 723 * 724 * If the device does not support ID attestation (or destroyAttestationIds() was previously 725 * called and the device can no longer attest its IDs), any key attestation request that 726 * includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS. 727 * 728 * Must never appear in KeyCharacteristics. 729 */ 730 ATTESTATION_ID_IMEI = TagType:BYTES | 714, /* Used to provide the device's IMEI to be included 731 * in attestation */ 732 733 /** 734 * Tag::ATTESTATION_ID_MEID provides the MEIDs for all radios on the device to attestKey(). 735 * This field must be set only when requesting attestation of the device's identifiers. 736 * 737 * If the device does not support ID attestation (or destroyAttestationIds() was previously 738 * called and the device can no longer attest its IDs), any key attestation request that 739 * includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS. 740 * 741 * Must never appear in KeyCharacteristics. 742 */ 743 ATTESTATION_ID_MEID = TagType:BYTES | 715, /* Used to provide the device's MEID to be included 744 * in attestation */ 745 746 /** 747 * Tag::ATTESTATION_ID_MANUFACTURER provides the device's manufacturer name, as returned by 748 * Build.MANUFACTURER in Android, to attstKey(). This field must be set only when requesting 749 * attestation of the device's identifiers. 750 * 751 * If the device does not support ID attestation (or destroyAttestationIds() was previously 752 * called and the device can no longer attest its IDs), any key attestation request that 753 * includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS. 754 * 755 * Must never appear in KeyCharacteristics. 756 */ 757 ATTESTATION_ID_MANUFACTURER = TagType:BYTES | 716, 758 759 /** 760 * Tag::ATTESTATION_ID_MODEL provides the device's model name, as returned by Build.MODEL in 761 * Android, to attestKey(). This field must be set only when requesting attestation of the 762 * device's identifiers. 763 * 764 * If the device does not support ID attestation (or destroyAttestationIds() was previously 765 * called and the device can no longer attest its IDs), any key attestation request that 766 * includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS. 767 * 768 * Must never appear in KeyCharacteristics. 769 */ 770 ATTESTATION_ID_MODEL = TagType:BYTES | 717, 771 772 /** 773 * Tag::VENDOR_PATCHLEVEL specifies the vendor image security patch level with which the key may 774 * be used. This tag is never sent to the keymaster TA, but is added to the hardware-enforced 775 * authorization list by the TA. Any attempt to use a key with a Tag::VENDOR_PATCHLEVEL value 776 * different from the currently-running system patchlevel must cause begin(), 777 * getKeyCharacteristics() or exportKey() to return ErrorCode::KEY_REQUIRES_UPGRADE. See 778 * upgradeKey() for details. 779 * 780 * The value of the tag is an integer of the form YYYYMMDD, where YYYY is the four-digit year of 781 * the last update, MM is the two-digit month and DD is the two-digit day of the last 782 * update. For example, for a key generated on an Android device last updated on June 5, 2018, 783 * the value would be 20180605. 784 * 785 * The IKeymasterDevice HAL must read the current vendor patchlevel from the system property 786 * ro.vendor.build.security_patch and deliver it to the secure environment when the HAL is first 787 * loaded (mechanism is implementation-defined). The secure environment must not accept another 788 * patchlevel until after the next boot. 789 * 790 * Must be hardware-enforced. 791 */ 792 VENDOR_PATCHLEVEL = TagType:UINT | 718, 793 794 /** 795 * Tag::BOOT_PATCHLEVEL specifies the boot image (kernel) security patch level with which the 796 * key may be used. This tag is never sent to the keymaster TA, but is added to the 797 * hardware-enforced authorization list by the TA. Any attempt to use a key with a 798 * Tag::BOOT_PATCHLEVEL value different from the currently-running system patchlevel must 799 * cause begin(), getKeyCharacteristics() or exportKey() to return 800 * ErrorCode::KEY_REQUIRES_UPGRADE. See upgradeKey() for details. 801 * 802 * The value of the tag is an integer of the form YYYYMMDD, where YYYY is the four-digit year of 803 * the last update, MM is the two-digit month and DD is the two-digit day of the last 804 * update. For example, for a key generated on an Android device last updated on June 5, 2018, 805 * the value would be 20180605. If the day is not known, 00 may be substituted. 806 * 807 * During each boot, the bootloader must provide the patch level of the boot image to the secure 808 * envirionment (mechanism is implementation-defined). 809 * 810 * Must be hardware-enforced. 811 */ 812 BOOT_PATCHLEVEL = TagType:UINT | 719, 813 814 /** 815 * Tag::ASSOCIATED_DATA Provides "associated data" for AES-GCM encryption or decryption. This 816 * tag is provided to update and specifies data that is not encrypted/decrypted, but is used in 817 * computing the GCM tag. 818 * 819 * Must never appear KeyCharacteristics. 820 */ 821 ASSOCIATED_DATA = TagType:BYTES | 1000, 822 823 /** 824 * Tag::NONCE is used to provide or return a nonce or Initialization Vector (IV) for AES-GCM, 825 * AES-CBC, AES-CTR, or 3DES-CBC encryption or decryption. This tag is provided to begin during 826 * encryption and decryption operations. It is only provided to begin if the key has 827 * Tag::CALLER_NONCE. If not provided, an appropriate nonce or IV must be randomly generated by 828 * Keymaster and returned from begin. 829 * 830 * The value is a blob, an arbitrary-length array of bytes. Allowed lengths depend on the mode: 831 * GCM nonces are 12 bytes in length; AES-CBC and AES-CTR IVs are 16 bytes in length, 3DES-CBC 832 * IVs are 8 bytes in length. 833 * 834 * Must never appear in KeyCharacteristics. 835 */ 836 NONCE = TagType:BYTES | 1001, 837 838 /** 839 * Tag::MAC_LENGTH provides the requested length of a MAC or GCM authentication tag, in bits. 840 * 841 * The value is the MAC length in bits. It must be a multiple of 8 and at least as large as the 842 * value of Tag::MIN_MAC_LENGTH associated with the key. Otherwise, begin() must return 843 * ErrorCode::INVALID_MAC_LENGTH. 844 * 845 * Must never appear in KeyCharacteristics. 846 */ 847 MAC_LENGTH = TagType:UINT | 1003, 848 849 /** 850 * Tag::RESET_SINCE_ID_ROTATION specifies whether the device has been factory reset since the 851 * last unique ID rotation. Used for key attestation. 852 * 853 * Must never appear in KeyCharacteristics. 854 */ 855 RESET_SINCE_ID_ROTATION = TagType:BOOL | 1004, 856 857 /** 858 * Tag::CONFIRMATION_TOKEN is used to deliver a cryptographic token proving that the user 859 * confirmed a signing request. The content is a full-length HMAC-SHA256 value. See the 860 * ConfirmationUI HAL for details of token computation. 861 * 862 * Must never appear in KeyCharacteristics. 863 */ 864 CONFIRMATION_TOKEN = TagType:BYTES | 1005, 865}; 866 867/** 868 * Algorithms provided by IKeymasterDevice implementations. 869 */ 870enum Algorithm : uint32_t { 871 /** Asymmetric algorithms. */ 872 RSA = 1, 873 // 2 removed, do not reuse. 874 EC = 3, 875 876 /** Block cipher algorithms */ 877 AES = 32, 878 TRIPLE_DES = 33, 879 880 /** MAC algorithms */ 881 HMAC = 128, 882}; 883 884/** 885 * Symmetric block cipher modes provided by keymaster implementations. 886 */ 887enum BlockMode : uint32_t { 888 /* 889 * Unauthenticated modes, usable only for encryption/decryption and not generally recommended 890 * except for compatibility with existing other protocols. 891 */ 892 ECB = 1, 893 CBC = 2, 894 CTR = 3, 895 896 /* 897 * Authenticated modes, usable for encryption/decryption and signing/verification. Recommended 898 * over unauthenticated modes for all purposes. 899 */ 900 GCM = 32, 901}; 902 903/** 904 * Padding modes that may be applied to plaintext for encryption operations. This list includes 905 * padding modes for both symmetric and asymmetric algorithms. Note that implementations should not 906 * provide all possible combinations of algorithm and padding, only the 907 * cryptographically-appropriate pairs. 908 */ 909enum PaddingMode : uint32_t { 910 NONE = 1, /* deprecated */ 911 RSA_OAEP = 2, 912 RSA_PSS = 3, 913 RSA_PKCS1_1_5_ENCRYPT = 4, 914 RSA_PKCS1_1_5_SIGN = 5, 915 PKCS7 = 64, 916}; 917 918/** 919 * Digests provided by keymaster implementations. 920 */ 921enum Digest : uint32_t { 922 NONE = 0, 923 MD5 = 1, 924 SHA1 = 2, 925 SHA_2_224 = 3, 926 SHA_2_256 = 4, 927 SHA_2_384 = 5, 928 SHA_2_512 = 6, 929}; 930 931/** 932 * Supported EC curves, used in ECDSA 933 */ 934enum EcCurve : uint32_t { 935 P_224 = 0, 936 P_256 = 1, 937 P_384 = 2, 938 P_521 = 3, 939}; 940 941/** 942 * The origin of a key (or pair), i.e. where it was generated. Note that ORIGIN can be found in 943 * either the hardware-enforced or software-enforced list for a key, indicating whether the key is 944 * hardware or software-based. Specifically, a key with GENERATED in the hardware-enforced list 945 * must be guaranteed never to have existed outide the secure hardware. 946 */ 947enum KeyOrigin : uint32_t { 948 /** Generated in keymaster. Should not exist outside the TEE. */ 949 GENERATED = 0, 950 951 /** Derived inside keymaster. Likely exists off-device. */ 952 DERIVED = 1, 953 954 /** Imported into keymaster. Existed as cleartext in Android. */ 955 IMPORTED = 2, 956 957 /** 958 * Keymaster did not record origin. This value can only be seen on keys in a keymaster0 959 * implementation. The keymaster0 adapter uses this value to document the fact that it is 960 * unkown whether the key was generated inside or imported into keymaster. 961 */ 962 UNKNOWN = 3, 963 964 /** 965 * Securely imported into Keymaster. Was created elsewhere, and passed securely through Android 966 * to secure hardware. 967 */ 968 SECURELY_IMPORTED = 4, 969}; 970 971/** 972 * Usability requirements of key blobs. This defines what system functionality must be available 973 * for the key to function. For example, key "blobs" which are actually handles referencing 974 * encrypted key material stored in the file system cannot be used until the file system is 975 * available, and should have BLOB_REQUIRES_FILE_SYSTEM. 976 */ 977enum KeyBlobUsageRequirements : uint32_t { 978 STANDALONE = 0, 979 REQUIRES_FILE_SYSTEM = 1, 980}; 981 982/** 983 * Possible purposes of a key (or pair). 984 */ 985enum KeyPurpose : uint32_t { 986 ENCRYPT = 0, /* Usable with RSA, EC and AES keys. */ 987 DECRYPT = 1, /* Usable with RSA, EC and AES keys. */ 988 SIGN = 2, /* Usable with RSA, EC and HMAC keys. */ 989 VERIFY = 3, /* Usable with RSA, EC and HMAC keys. */ 990 /* 4 is reserved */ 991 WRAP_KEY = 5, /* Usable with wrapping keys. */ 992}; 993 994/** 995 * Keymaster error codes. 996 */ 997enum ErrorCode : int32_t { 998 OK = 0, 999 ROOT_OF_TRUST_ALREADY_SET = -1, 1000 UNSUPPORTED_PURPOSE = -2, 1001 INCOMPATIBLE_PURPOSE = -3, 1002 UNSUPPORTED_ALGORITHM = -4, 1003 INCOMPATIBLE_ALGORITHM = -5, 1004 UNSUPPORTED_KEY_SIZE = -6, 1005 UNSUPPORTED_BLOCK_MODE = -7, 1006 INCOMPATIBLE_BLOCK_MODE = -8, 1007 UNSUPPORTED_MAC_LENGTH = -9, 1008 UNSUPPORTED_PADDING_MODE = -10, 1009 INCOMPATIBLE_PADDING_MODE = -11, 1010 UNSUPPORTED_DIGEST = -12, 1011 INCOMPATIBLE_DIGEST = -13, 1012 INVALID_EXPIRATION_TIME = -14, 1013 INVALID_USER_ID = -15, 1014 INVALID_AUTHORIZATION_TIMEOUT = -16, 1015 UNSUPPORTED_KEY_FORMAT = -17, 1016 INCOMPATIBLE_KEY_FORMAT = -18, 1017 UNSUPPORTED_KEY_ENCRYPTION_ALGORITHM = -19, /** For PKCS8 & PKCS12 */ 1018 UNSUPPORTED_KEY_VERIFICATION_ALGORITHM = -20, /** For PKCS8 & PKCS12 */ 1019 INVALID_INPUT_LENGTH = -21, 1020 KEY_EXPORT_OPTIONS_INVALID = -22, 1021 DELEGATION_NOT_ALLOWED = -23, 1022 KEY_NOT_YET_VALID = -24, 1023 KEY_EXPIRED = -25, 1024 KEY_USER_NOT_AUTHENTICATED = -26, 1025 OUTPUT_PARAMETER_NULL = -27, 1026 INVALID_OPERATION_HANDLE = -28, 1027 INSUFFICIENT_BUFFER_SPACE = -29, 1028 VERIFICATION_FAILED = -30, 1029 TOO_MANY_OPERATIONS = -31, 1030 UNEXPECTED_NULL_POINTER = -32, 1031 INVALID_KEY_BLOB = -33, 1032 IMPORTED_KEY_NOT_ENCRYPTED = -34, 1033 IMPORTED_KEY_DECRYPTION_FAILED = -35, 1034 IMPORTED_KEY_NOT_SIGNED = -36, 1035 IMPORTED_KEY_VERIFICATION_FAILED = -37, 1036 INVALID_ARGUMENT = -38, 1037 UNSUPPORTED_TAG = -39, 1038 INVALID_TAG = -40, 1039 MEMORY_ALLOCATION_FAILED = -41, 1040 IMPORT_PARAMETER_MISMATCH = -44, 1041 SECURE_HW_ACCESS_DENIED = -45, 1042 OPERATION_CANCELLED = -46, 1043 CONCURRENT_ACCESS_CONFLICT = -47, 1044 SECURE_HW_BUSY = -48, 1045 SECURE_HW_COMMUNICATION_FAILED = -49, 1046 UNSUPPORTED_EC_FIELD = -50, 1047 MISSING_NONCE = -51, 1048 INVALID_NONCE = -52, 1049 MISSING_MAC_LENGTH = -53, 1050 KEY_RATE_LIMIT_EXCEEDED = -54, 1051 CALLER_NONCE_PROHIBITED = -55, 1052 KEY_MAX_OPS_EXCEEDED = -56, 1053 INVALID_MAC_LENGTH = -57, 1054 MISSING_MIN_MAC_LENGTH = -58, 1055 UNSUPPORTED_MIN_MAC_LENGTH = -59, 1056 UNSUPPORTED_KDF = -60, 1057 UNSUPPORTED_EC_CURVE = -61, 1058 KEY_REQUIRES_UPGRADE = -62, 1059 ATTESTATION_CHALLENGE_MISSING = -63, 1060 KEYMASTER_NOT_CONFIGURED = -64, 1061 ATTESTATION_APPLICATION_ID_MISSING = -65, 1062 CANNOT_ATTEST_IDS = -66, 1063 ROLLBACK_RESISTANCE_UNAVAILABLE = -67, 1064 HARDWARE_TYPE_UNAVAILABLE = -68, 1065 PROOF_OF_PRESENCE_REQUIRED = -69, 1066 CONCURRENT_PROOF_OF_PRESENCE_REQUESTED = -70, 1067 NO_USER_CONFIRMATION = -71, 1068 DEVICE_LOCKED = -72, 1069 1070 UNIMPLEMENTED = -100, 1071 VERSION_MISMATCH = -101, 1072 1073 UNKNOWN_ERROR = -1000, 1074 1075 // Implementer's namespace for error codes starts at -10000. 1076}; 1077 1078/** 1079 * Key derivation functions, mostly used in ECIES. 1080 */ 1081enum KeyDerivationFunction : uint32_t { 1082 /** Do not apply a key derivation function; use the raw agreed key */ 1083 NONE = 0, 1084 /** HKDF defined in RFC 5869 with SHA256 */ 1085 RFC5869_SHA256 = 1, 1086 /** KDF1 defined in ISO 18033-2 with SHA1 */ 1087 ISO18033_2_KDF1_SHA1 = 2, 1088 /** KDF1 defined in ISO 18033-2 with SHA256 */ 1089 ISO18033_2_KDF1_SHA256 = 3, 1090 /** KDF2 defined in ISO 18033-2 with SHA1 */ 1091 ISO18033_2_KDF2_SHA1 = 4, 1092 /** KDF2 defined in ISO 18033-2 with SHA256 */ 1093 ISO18033_2_KDF2_SHA256 = 5, 1094}; 1095 1096/** 1097 * Hardware authentication type, used by HardwareAuthTokens to specify the mechanism used to 1098 * authentiate the user, and in KeyCharacteristics to specify the allowable mechanisms for 1099 * authenticating to activate a key. 1100 */ 1101enum HardwareAuthenticatorType : uint32_t { 1102 NONE = 0, 1103 PASSWORD = 1 << 0, 1104 FINGERPRINT = 1 << 1, 1105 // Additional entries must be powers of 2. 1106 ANY = 0xFFFFFFFF, 1107}; 1108 1109/** 1110 * Device security levels. 1111 */ 1112enum SecurityLevel : uint32_t { 1113 SOFTWARE = 0, 1114 TRUSTED_ENVIRONMENT = 1, 1115 /** 1116 * STRONGBOX specifies that the secure hardware satisfies the requirements specified in CDD 1117 * 9.11.2. 1118 */ 1119 STRONGBOX = 2, 1120}; 1121 1122/** 1123 * Formats for key import and export. 1124 */ 1125enum KeyFormat : uint32_t { 1126 /** X.509 certificate format, for public key export. */ 1127 X509 = 0, 1128 /** PCKS#8 format, asymmetric key pair import. */ 1129 PKCS8 = 1, 1130 /** Raw bytes, for symmetric key import. */ 1131 RAW = 3, 1132}; 1133 1134struct KeyParameter { 1135 /** 1136 * Discriminates the union/blob field used. The blob cannot be placed in the union, but only 1137 * one of "f" and "blob" may ever be used at a time. 1138 */ 1139 Tag tag; 1140 1141 union IntegerParams { 1142 /* Enum types */ 1143 Algorithm algorithm; 1144 BlockMode blockMode; 1145 PaddingMode paddingMode; 1146 Digest digest; 1147 EcCurve ecCurve; 1148 KeyOrigin origin; 1149 KeyBlobUsageRequirements keyBlobUsageRequirements; 1150 KeyPurpose purpose; 1151 KeyDerivationFunction keyDerivationFunction; 1152 HardwareAuthenticatorType hardwareAuthenticatorType; 1153 SecurityLevel hardwareType; 1154 1155 /* Other types */ 1156 bool boolValue; // Always true, if a boolean tag is present. 1157 uint32_t integer; 1158 uint64_t longInteger; 1159 uint64_t dateTime; 1160 }; 1161 IntegerParams f; // Hidl does not support anonymous unions, so we have to name it. 1162 vec<uint8_t> blob; 1163}; 1164 1165/** 1166 * KeyCharacteristics defines the attributes of a key, including cryptographic parameters, and usage 1167 * restrictions. It consits of two vectors of KeyParameters, one for "softwareEnforced" attributes 1168 * and one for "hardwareEnforced" attributes. 1169 * 1170 * KeyCharacteristics objects are returned by generateKey, importKey, importWrappedKey and 1171 * getKeyCharacteristics. The IKeymasterDevice secure environment is responsible for allocating the 1172 * parameters, all of which are Tags with associated values, to the correct vector. The 1173 * hardwareEnforced vector must contain only those attributes which are enforced by secure hardware. 1174 * All others should be in the softwareEnforced vector. See the definitions of individual Tag enums 1175 * for specification of which must be hardware-enforced, which may be software-enforced and which 1176 * must never appear in KeyCharacteristics. 1177 */ 1178struct KeyCharacteristics { 1179 vec<KeyParameter> softwareEnforced; 1180 vec<KeyParameter> hardwareEnforced; 1181}; 1182 1183/** 1184 * HardwareAuthToken is used to prove successful user authentication, to unlock the use of a key. 1185 * 1186 * HardwareAuthTokens are produced by other secure environment applications, notably GateKeeper and 1187 * Fingerprint, in response to successful user authentication events. These tokens are passed to 1188 * begin(), update(), and finish() to prove that authentication occurred. See those methods for 1189 * more details. It is up to the caller to determine which of the generated auth tokens is 1190 * appropriate for a given key operation. 1191 */ 1192struct HardwareAuthToken { 1193 /** 1194 * challenge is a value that's used to enable authentication tokens to authorize specific 1195 * events. The primary use case for challenge is to authorize an IKeymasterDevice cryptographic 1196 * operation, for keys that require authentication per operation. See begin() for details. 1197 */ 1198 uint64_t challenge; 1199 1200 /** 1201 * userId is the a "secure" user ID. It is not related to any Android user ID or UID, but is 1202 * created in the Gatekeeper application in the secure environment. 1203 */ 1204 uint64_t userId; 1205 1206 /** 1207 * authenticatorId is the a "secure" user ID. It is not related to any Android user ID or UID, 1208 * but is created in an authentication application in the secure environment, such as the 1209 * Fingerprint application. 1210 */ 1211 uint64_t authenticatorId; // Secure authenticator ID. 1212 1213 /** 1214 * authenticatorType describes the type of authentication that took place, e.g. password or 1215 * fingerprint. 1216 */ 1217 HardwareAuthenticatorType authenticatorType; 1218 1219 /** 1220 * timestamp indicates when the user authentication took place, in milliseconds since some 1221 * starting point (generally the most recent device boot) which all of the applications within 1222 * one secure environment must agree upon. This timestamp is used to determine whether or not 1223 * the authentication occurred recently enough to unlock a key (see Tag::AUTH_TIMEOUT). 1224 */ 1225 Timestamp timestamp; 1226 1227 /** 1228 * MACs are computed with a backward-compatible method, used by Keymaster 3.0, Gatekeeper 1.0 1229 * and Fingerprint 1.0, as well as pre-treble HALs. 1230 * 1231 * The MAC is Constants::AUTH_TOKEN_MAC_LENGTH bytes in length and is computed as follows: 1232 * 1233 * HMAC_SHA256( 1234 * H, 0 || challenge || user_id || authenticator_id || authenticator_type || timestamp) 1235 * 1236 * where ``||'' represents concatenation, the leading zero is a single byte, and all integers 1237 * are represented as unsigned values, the full width of the type. The challenge, userId and 1238 * authenticatorId values are in machine order, but authenticatorType and timestamp are in 1239 * network order (big-endian). This odd construction is compatible with the hw_auth_token_t 1240 * structure, 1241 * 1242 * Note that mac is a vec rather than an array, not because it's actually variable-length but 1243 * because it could be empty. As documented in the IKeymasterDevice::begin, 1244 * IKeymasterDevice::update and IKeymasterDevice::finish doc comments, an empty mac indicates 1245 * that this auth token is empty. 1246 */ 1247 vec<uint8_t> mac; 1248}; 1249 1250typedef uint64_t OperationHandle; 1251 1252/** 1253 * HmacSharingParameters holds the data used in the process of establishing a shared HMAC key 1254 * between multiple Keymaster instances. Sharing parameters are returned in this struct by 1255 * getHmacSharingParameters() and send to computeSharedHmac(). See the named methods in IKeymaster 1256 * for details of usage. 1257 */ 1258struct HmacSharingParameters { 1259 /** 1260 * Either empty or contains a persistent value that is associated with the pre-shared HMAC 1261 * agreement key (see documentation of computeSharedHmac in @4.0::IKeymaster). It is either 1262 * empty or 32 bytes in length. 1263 */ 1264 vec<uint8_t> seed; 1265 1266 /** 1267 * A 32-byte value which is guaranteed to be different each time 1268 * getHmacSharingParameters() is called. Probabilistic uniqueness (i.e. random) is acceptable, 1269 * though a stronger uniqueness guarantee (e.g. counter) is recommended where possible. 1270 */ 1271 uint8_t[32] nonce; 1272}; 1273 1274/** 1275 * VerificationToken enables one Keymaster instance to validate authorizations for another. See 1276 * verifyAuthorizations() in IKeymaster for details. 1277 */ 1278struct VerificationToken { 1279 /** 1280 * The operation handle, used to ensure freshness. 1281 */ 1282 uint64_t challenge; 1283 1284 /** 1285 * The current time of the secure environment that generates the VerificationToken. This can be 1286 * checked against auth tokens generated by the same secure environment, which avoids needing to 1287 * synchronize clocks. 1288 */ 1289 Timestamp timestamp; 1290 1291 /** 1292 * A list of the parameters verified. Empty if the only parameters verified are time-related. 1293 * In that case the timestamp is the payload. 1294 */ 1295 vec<KeyParameter> parametersVerified; 1296 1297 /** 1298 * SecurityLevel of the secure environment that generated the token. 1299 */ 1300 SecurityLevel securityLevel; 1301 1302 /** 1303 * 32-byte HMAC-SHA256 of the above values, computed as: 1304 * 1305 * HMAC(H, 1306 * "Auth Verification" || challenge || timestamp || securityLevel || parametersVerified) 1307 * 1308 * where: 1309 * 1310 * ``HMAC'' is the shared HMAC key (see computeSharedHmac() in IKeymaster). 1311 * 1312 * ``||'' represents concatenation 1313 * 1314 * The representation of challenge and timestamp is as 64-bit unsigned integers in big-endian 1315 * order. securityLevel is represented as a 32-bit unsigned integer in big-endian order. 1316 * 1317 * If parametersVerified is non-empty, the representation of parametersVerified is an ASN.1 DER 1318 * encoded representation of the values. The ASN.1 schema used is the AuthorizationList schema 1319 * from the Keystore attestation documentation. If parametersVerified is empty, it is simply 1320 * omitted from the HMAC computation. 1321 */ 1322 vec<uint8_t> mac; 1323}; 1324