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 17 package android.hardware.keymaster@4.0; 18 19 import android.hardware.keymaster@3.0::ErrorCode; 20 import android.hardware.keymaster@3.0::KeyFormat; 21 22 /** 23 * Keymaster device definition. 24 * 25 * == Features == 26 * 27 * An IKeymasterDevice provides cryptographic services, including the following categories of 28 * operations: 29 * 30 * o Key generation 31 * o Import and export (public only) of asymmetric keys 32 * o Import of raw symmetric keys 33 * o Asymmetric encryption and decryption with appropriate padding modes 34 * o Asymmetric signing and verification with digesting and appropriate padding modes 35 * o Symmetric encryption and decryption in appropriate modes, including an AEAD mode 36 * o Generation and verification of symmetric message authentication codes 37 * o Attestation to the presence and configuration of asymmetric keys. 38 * 39 * Protocol elements, such as purpose, mode and padding, as well as access control constraints, must 40 * be specified by the caller when keys are generated or imported and must be permanently bound to 41 * the key, ensuring that the key cannot be used in any other way. 42 * 43 * In addition to the list above, IKeymasterDevice implementations must provide one more service 44 * which is not exposed as an API but used internally: Random number generation. The random number 45 * generator must be high-quality and must be used for generation of keys, initialization vectors, 46 * random padding and other elements of secure protocols that require randomness. 47 * 48 * == Types of IKeymasterDevices == 49 * 50 * All of the operations and storage of key material must occur in a secure environment. Secure 51 * environments may be either: 52 * 53 * 1. Isolated execution environments, such as a separate virtual machine, hypervisor or 54 * purpose-built trusted execution environment like ARM TrustZone. The isolated environment 55 * must provide complete separation from the Android kernel and user space (collectively called 56 * the "non-secure world", or NSW) so that nothing running in the NSW can observe or manipulate 57 * the results of any computation in the isolated environment. Isolated execution environments 58 * are identified by the SecurityLevel TRUSTED_ENVIRONMENT. 59 * 60 * 2. Completely separate, purpose-built and certified secure CPUs, called "StrongBox" devices. 61 * Examples of StrongBox devices are embedded Secure Elements (eSE) or on-SoC secure processing 62 * units (SPU). StrongBox environments are identified by the SecurityLevel STRONGBOX. To 63 * qualify as a StrongBox, a device must meet the requirements specified in CDD 9.11.2. 64 * 65 * == Necessary Primitives == 66 * 67 * All IKeymasterDevice implementations must provide support for the following: 68 * 69 * o RSA 70 * 71 * - TRUSTED_ENVIRONMENT IKeymasterDevices must support 2048, 3072 and 4096-bit keys. 72 * STRONGBOX IKeymasterDevices must support 2048-bit keys. 73 * - Public exponent F4 (2^16+1) 74 * - Unpadded, RSASSA-PSS and RSASSA-PKCS1-v1_5 padding modes for RSA signing 75 * - TRUSTED_ENVIRONMENT IKeymasterDevices must support MD5, SHA1, SHA-2 224, SHA-2 256, SHA-2 76 * 384 and SHA-2 512 digest modes for RSA signing. STRONGBOX IKeymasterDevices must support 77 * SHA-2 256. 78 * - Unpadded, RSAES-OAEP and RSAES-PKCS1-v1_5 padding modes for RSA encryption. 79 * 80 * o ECDSA 81 * 82 * - TRUSTED_ENVIRONMENT IKeymasterDevices must support NIST curves P-224, P-256, P-384 and 83 * P-521. STRONGBOX IKeymasterDevices must support NIST curve P-256. 84 * - TRUSTED_ENVIRONMENT IKeymasterDevices must support SHA1, SHA-2 224, SHA-2 256, SHA-2 85 * 384 and SHA-2 512 digest modes. STRONGBOX IKeymasterDevices must support SHA-2 256. 86 * 87 * o AES 88 * 89 * - 128 and 256-bit keys 90 * - CBC, CTR, ECB and GCM modes. The GCM mode must not allow the use of tags smaller than 96 91 * bits or nonce lengths other than 96 bits. 92 * - CBC and ECB modes must support unpadded and PKCS7 padding modes. With no padding CBC and 93 * ECB-mode operations must fail with ErrorCode::INVALID_INPUT_LENGTH if the input isn't a 94 * multiple of the AES block size. With PKCS7 padding, GCM and CTR operations must fail with 95 * ErrorCode::INCOMPATIBLE_PADDING_MODE. 96 * 97 * o 3DES 98 * 99 * - 168-bit keys. 100 * - CBC and ECB mode. 101 102 * - CBC and ECB modes must support unpadded and PKCS7 padding modes. With no padding CBC and 103 * ECB-mode operations must fail with ErrorCode::INVALID_INPUT_LENGTH if the input isn't a 104 * multiple of the DES block size. 105 * 106 * o HMAC 107 * 108 * - Any key size that is between 64 and 512 bits (inclusive) and a multiple of 8 must be 109 * supported. STRONGBOX IKeymasterDevices must not support keys larger than 512 bits. 110 * - TRUSTED_ENVIRONMENT IKeymasterDevices must support MD-5, SHA1, SHA-2-224, SHA-2-256, 111 * SHA-2-384 and SHA-2-512. STRONGBOX IKeymasterDevices must support SHA-2-256. 112 * 113 * == Key Access Control == 114 * 115 * Hardware-based keys that can never be extracted from the device don't provide much security if an 116 * attacker can use them at will (though they're more secure than keys which can be 117 * exfiltrated). Therefore, IKeymasterDevice must enforce access controls. 118 * 119 * Access controls are defined as an "authorization list" of tag/value pairs. Authorization tags 120 * are 32-bit integers from the Tag enum, and the values are a variety of types, defined in the 121 * TagType enum. Some tags may be repeated to specify multiple values. Whether a tag may be 122 * repeated is specified in the documentation for the tag and in the TagType. When a key is created 123 * or imported, the caller specifies an authorization list. The IKeymasterDevice must divide the 124 * caller-provided authorizations into two lists, those it enforces in hardware and those it does 125 * not. These two lists are returned as the "hardwareEnforced" and "softwareEnforced" elements of 126 * the KeyCharacteristics struct. The IKeymasterDevice must also add the following authorizations 127 * to the appropriate list: 128 * 129 * o Tag::OS_VERSION, must be hardware-enforced. 130 * o Tag::OS_PATCHLEVEL, must be hardware-enforced. 131 * o Tag::VENDOR_PATCHLEVEL, must be hardware-enforced. 132 * o Tag::BOOT_PATCHLEVEL, must be hardware-enforced. 133 * o Tag::CREATION_DATETIME, must be software-enforced, unless the IKeymasterDevice has access to 134 * a secure time service. 135 * o Tag::ORIGIN, must be hardware-enforced. 136 * 137 * The IKeymasterDevice must accept arbitrary, unknown tags and return them in the softwareEnforced 138 * list. 139 * 140 * All authorization tags and their values, both hardwareEnforced and softwareEnforced, including 141 * unknown tags, must be cryptographically bound to the private/secret key material such that any 142 * modification of the portion of the key blob that contains the authorization list makes it 143 * impossible for the secure environment to obtain the private/secret key material. The recommended 144 * approach to meet this requirement is to use the full set of authorization tags associated with a 145 * key as input to a secure key derivation function used to derive a key that is used to encrypt the 146 * private/secret key material. 147 * 148 * IKeymasterDevice implementations must place any tags they cannot fully and completely enforce in 149 * the softwareEnforced list. For example, Tag::ORIGINATION_EXPIRE_DATETIME provides the date and 150 * time after which a key may not be used to encrypt or sign new messages. Unless the 151 * IKeymasterDevice has access to a secure source of current date/time information, it is not 152 * possible for the IKeymasterDevice to enforce this tag. An IKeymasterDevice implementation may 153 * not rely on the non-secure world's notion of time, because it could be controlled by an attacker. 154 * Similarly, it cannot rely on GPSr time, even if it has exclusive control of the GPSr, because 155 * that might be spoofed by attacker RF signals. 156 * 157 * It is recommended that IKeymasterDevices not enforce any tags they place in the softwareEnforced 158 * list. The IKeymasterDevice caller must enforce them, and it is unnecessary to enforce them 159 * twice. 160 * 161 * Some tags must be enforced by the IKeymasterDevice. See the detailed documentation on each Tag 162 * in types.hal. 163 * 164 * == Root of Trust Binding == 165 * 166 * IKeymasterDevice keys must be bound to a root of trust, which is a bitstring that must be 167 * provided to the secure environment (by an unspecified, implementation-defined mechanism) during 168 * startup, preferably by the bootloader. This bitstring must be cryptographically bound to every 169 * key managed by the IKeymasterDevice. As above, the recommended mechanism for this cryptographic 170 * binding is to include the Root of Trust data in the input to the key derivation function used to 171 * derive a key that is used to encrypt the private/secret key material. 172 * 173 * The root of trust consists of a bitstring that must be derived from the public key used by 174 * Verified Boot to verify the signature on the boot image and from the the lock state of the 175 * device. If the public key is changed to allow a different system image to be used or if the lock 176 * state is changed, then all of the IKeymasterDevice-protected keys created by the previous system 177 * state must be unusable, unless the previous state is restored. The goal is to increase the value 178 * of the software-enforced key access controls by making it impossible for an attacker-installed 179 * operating system to use IKeymasterDevice keys. 180 * 181 * == Version Binding == 182 * 183 * All keys must also be bound to the operating system and patch level of the system image and the 184 * patch levels of the vendor image and boot image. This ensures that an attacker who discovers a 185 * weakness in an old version of the software cannot roll a device back to the vulnerable version 186 * and use keys created with the newer version. In addition, when a key with a given version and 187 * patch level is used on a device that has been upgraded to a newer version or patch level, the key 188 * must be upgraded (See IKeymasterDevice::upgradeKey()) before it can be used, and the previous 189 * version of the key must be invalidated. In this way, as the device is upgraded, the keys will 190 * "ratchet" forward along with the device, but any reversion of the device to a previous release 191 * will cause the keys to be unusable. 192 * 193 * This version information must be associated with every key as a set of tag/value pairs in the 194 * hardwareEnforced authorization list. Tag::OS_VERSION, Tag::OS_PATCHLEVEL, 195 * Tag::VENDOR_PATCHLEVEL, and Tag::BOOT_PATCHLEVEL must be cryptographically bound to every 196 * IKeymasterDevice key, as described in the Key Access Control section above. 197 */ 198 199 interface IKeymasterDevice { 200 201 /** 202 * Returns information about the underlying IKeymasterDevice hardware. 203 * 204 * @return security level of the IKeymasterDevice implementation accessed through this HAL. 205 * 206 * @return keymasterName is the name of the IKeymasterDevice implementation. 207 * 208 * @return keymasterAuthorName is the name of the author of the IKeymasterDevice implementation 209 * (organization name, not individual). 210 */ 211 getHardwareInfo() 212 generates (SecurityLevel securityLevel, string keymasterName, string keymasterAuthorName); 213 214 /** 215 * Start the creation of an HMAC key, shared with another IKeymasterDevice implementation. Any 216 * device with a StrongBox IKeymasterDevice has two IKeymasterDevice instances, because there 217 * must be a TEE Keymaster as well. The HMAC key used to MAC and verify authentication tokens 218 * (HardwareAuthToken, VerificationToken and ConfirmationToken all use this HMAC key) must be 219 * shared between TEE and StrongBox so they can each validate tokens produced by the other. 220 * This method is the first step in the process for agreeing on a shared key. It is called by 221 * Android during startup. The system calls it on each of the HAL instances and collects the 222 * results in preparation for the second step. 223 * 224 * @return error ErrorCode::OK on success, ErrorCode::UNIMPLEMENTED if HMAC agreement is not 225 * implemented (note that all 4.0::IKeymasterDevice HALS must implement HMAC agreement, 226 * regardless of whether or not the HAL will be used on a device with StrongBox), or 227 * ErrorCode::UNKNOWN_ERROR if the parameters cannot be returned. 228 * 229 * @return params The HmacSharingParameters to use. As specified in the HmacSharingParameters 230 * documentation in types.hal, the seed must contain the same value in every invocation 231 * of the method on a given device, and the nonce must return the same value for every 232 * invocation during a boot session. 233 */ 234 getHmacSharingParameters() generates (ErrorCode error, HmacSharingParameters params); 235 236 /** 237 * Complete the creation of an HMAC key, shared with another IKeymasterDevice implementation. 238 * Any device with a StrongBox IKeymasterDevice has two IKeymasterDevice instances, because 239 * there must be a TEE IKeymasterDevice as well. The HMAC key used to MAC and verify 240 * authentication tokens must be shared between TEE and StrongBox so they can each validate 241 * tokens produced by the other. This method is the second and final step in the process for 242 * agreeing on a shared key. It is called by Android during startup. The system calls it on 243 * each of the HAL instances, and sends to it all of the HmacSharingParameters returned by all 244 * HALs. 245 * 246 * To ensure consistent ordering of the HmacSharingParameters, the caller must sort the 247 * parameters lexicographically. See the support/keymaster_utils.cpp for an operator< that 248 * defines the appropriate ordering. 249 * 250 * This method computes the shared 32-byte HMAC ``H'' as follows (all IKeymasterDevice instances 251 * perform the same computation to arrive at the same result): 252 * 253 * H = CKDF(key = K, 254 * context = P1 || P2 || ... || Pn, 255 * label = "KeymasterSharedMac") 256 * 257 * where: 258 * 259 * ``CKDF'' is the standard AES-CMAC KDF from NIST SP 800-108 in counter mode (see Section 260 * 5.1 of the referenced publication). ``key'', ``context'', and ``label'' are 261 * defined in the standard. The counter is prefixed and length L appended, as shown 262 * in the construction on page 12 of the standard. The label string is UTF-8 encoded. 263 * 264 * ``K'' is a pre-established shared secret, set up during factory reset. The mechanism for 265 * establishing this shared secret is implementation-defined, but see below for a 266 * recommended approach, which assumes that the TEE IKeymasterDevice does not have 267 * storage available to it, but the StrongBox IKeymasterDevice does. 268 * 269 * CRITICAL SECURITY REQUIREMENT: All keys created by a IKeymasterDevice instance must 270 * be cryptographically bound to the value of K, such that establishing a new K 271 * permanently destroys them. 272 * 273 * ``||'' represents concatenation. 274 * 275 * ``Pi'' is the i'th HmacSharingParameters value in the params vector. Note that at 276 * present only two IKeymasterDevice implementations are supported, but this mechanism 277 * extends without modification to any number of implementations. Encoding of an 278 * HmacSharingParameters is the concatenation of its two fields, i.e. seed || nonce. 279 * 280 * Note that the label "KeymasterSharedMac" is the 18-byte UTF-8 encoding of the string. 281 * 282 * Process for establishing K: 283 * 284 * Any method of securely establishing K that ensures that an attacker cannot obtain or 285 * derive its value is acceptable. What follows is a recommended approach, to be executed 286 * during each factory reset. It relies on use of the factory-installed attestation keys to 287 * mitigate man-in-the-middle attacks. This protocol requires that one of the instances 288 * have secure persistent storage. This model was chosen because StrongBox has secure 289 * persistent storage (by definition), but the TEE may not. The instance without storage is 290 * assumed to be able to derive a unique hardware-bound key (HBK) which is used only for 291 * this purpose, and is not derivable outside the secure environment. 292 * 293 * In what follows, T is the IKeymasterDevice instance without storage, S is the 294 * IKeymasterDevice instance with storage: 295 * 296 * 1. T generates an ephemeral EC P-256 key pair K1. 297 * 2. T sends K1_pub to S, signed with T's attestation key. 298 * 3. S validates the signature on K1_pub. 299 * 4. S generates an ephemeral EC P-256 key pair K2. 300 * 5. S sends {K1_pub, K2_pub}, to T, signed with S's attestation key. 301 * 6. T validates the signature on {K1_pub, K2_pub}. 302 * 7. T uses {K1_priv, K2_pub} with ECDH to compute session secret Q. 303 * 8. T generates a random seed S. 304 * 9. T computes K = KDF(HBK, S), where KDF is some secure key derivation function. 305 * 10. T sends M = AES-GCM-ENCRYPT(Q, {S || K}) to S. 306 * 10. S uses {K2_priv, K1_pub} with ECDH to compute session secret Q. 307 * 11. S computes S || K = AES-GCM-DECRYPT(Q, M) and stores S and K. 308 * 309 * When S receives the getHmacSharingParameters call, it returns the stored S as the seed 310 * and a nonce. When T receives the same call, it returns an empty seed and a nonce. When 311 * T receives the computeSharedHmac call, it uses the seed provided by S to compute K. S, 312 * of course, has K stored. 313 * 314 * @param params The HmacSharingParameters data returned by all IKeymasterDevice instances when 315 * getHmacSharingParameters was called. 316 * 317 * @return error ErrorCode::OK in the event that there is no error. ErrorCode::INVALID_ARGUMENT 318 * if one of the provided parameters is not the value returned by the prior call to 319 * getHmacParameters(). 320 * 321 * @return sharingCheck A 32-byte value used to verify that all IKeymasterDevice instances have 322 * computed the same shared HMAC key. The sharingCheck value is computed as follows: 323 * 324 * sharingCheck = HMAC(H, "Keymaster HMAC Verification") 325 * 326 * The string is UTF-8 encoded, 27 bytes in length. If the returned values of all 327 * IKeymasterDevice instances don't match, clients must assume that HMAC agreement 328 * failed. 329 */ 330 computeSharedHmac(vec<HmacSharingParameters> params) 331 generates (ErrorCode error, vec<uint8_t> sharingCheck); 332 333 /** 334 * Verify authorizations for another IKeymasterDevice instance. 335 * 336 * On systems with both a StrongBox and a TEE IKeymasterDevice instance it is sometimes useful 337 * to ask the TEE IKeymasterDevice to verify authorizations for a key hosted in StrongBox. 338 * 339 * For every StrongBox operation, Keystore is required to call this method on the TEE Keymaster, 340 * passing in the StrongBox key's hardwareEnforced authorization list and the operation handle 341 * returned by StrongBox begin(). The TEE IKeymasterDevice must validate all of the 342 * authorizations it can and return those it validated in the VerificationToken. If it cannot 343 * verify any, the parametersVerified field of the VerificationToken must be empty. Keystore 344 * must then pass the VerificationToken to the subsequent invocations of StrongBox update() and 345 * finish(). 346 * 347 * StrongBox implementations must return ErrorCode::UNIMPLEMENTED. 348 * 349 * @param operationHandle the operation handle returned by StrongBox Keymaster's begin(). 350 * 351 * @param parametersToVerify Set of authorizations to verify. The caller may provide an empty 352 * vector if the only required information is the TEE timestamp. 353 * 354 * @param authToken A HardwareAuthToken if needed to authorize key usage. 355 * 356 * @return error ErrorCode::OK on success or ErrorCode::UNIMPLEMENTED if the IKeymasterDevice is 357 * a StrongBox. If the IKeymasterDevice cannot verify one or more elements of 358 * parametersToVerify it must not return an error code, but just omit the unverified 359 * parameter from the VerificationToken. 360 * 361 * @return token the verification token. See VerificationToken in types.hal for details. 362 */ 363 verifyAuthorization(uint64_t operationHandle, vec<KeyParameter> parametersToVerify, 364 HardwareAuthToken authToken) 365 generates (ErrorCode error, VerificationToken token); 366 367 368 /** 369 * Adds entropy to the RNG used by Keymaster. Entropy added through this method must not be the 370 * only source of entropy used, and a secure mixing function must be used to mix the entropy 371 * provided by this method with internally-generated entropy. The mixing function must be 372 * secure in the sense that if any one of the mixing function inputs is provided with any data 373 * the attacker cannot predict (or control), then the output of the seeded CRNG is 374 * indistinguishable from random. Thus, if the entropy from any source is good, the output must 375 * be good. 376 * 377 * @param data Bytes to be mixed into the CRNG seed. The caller must not provide more than 2 378 * KiB of data per invocation. 379 * 380 * @return error ErrorCode::OK on success; ErrorCode::INVALID_INPUT_LENGTH if the caller 381 * provides more than 2 KiB of data. 382 */ 383 addRngEntropy(vec<uint8_t> data) generates (ErrorCode error); 384 385 /** 386 * Generates a new cryptographic key, specifying associated parameters, which must be 387 * cryptographically bound to the key. IKeymasterDevice implementations must disallow any use 388 * of a key in any way inconsistent with the authorizations specified at generation time. With 389 * respect to parameters that the secure environment cannot enforce, the secure environment's 390 * obligation is limited to ensuring that the unenforceable parameters associated with the key 391 * cannot be modified, so that every call to getKeyCharacteristics returns the original 392 * values. In addition, the characteristics returned by generateKey places parameters correctly 393 * in the hardware-enforced and software-enforced lists. See getKeyCharacteristics for more 394 * details. 395 * 396 * In addition to the parameters provided, generateKey must add the following to the returned 397 * characteristics. 398 * 399 * o Tag::ORIGIN with the value KeyOrigin::GENERATED. 400 * 401 * o Tag::BLOB_USAGE_REQUIREMENTS with the appropriate value (see KeyBlobUsageRequirements in 402 * types.hal). 403 * 404 * o Tag::CREATION_DATETIME with the appropriate value. Note that it is expected that this will 405 * generally be added by the HAL, not by the secure environment, and that it will be in the 406 * software-enforced list. It must be cryptographically bound to the key, like all tags. 407 * 408 * o Tag::OS_VERSION, Tag::OS_PATCHLEVEL, Tag::VENDOR_PATCHLEVEL and Tag::BOOT_PATCHLEVEL with 409 * appropriate values. 410 * 411 * The parameters provided to generateKey depend on the type of key being generated. This 412 * section summarizes the necessary and optional tags for each type of key. Tag::ALGORITHM is 413 * always necessary, to specify the type. 414 * 415 * == RSA Keys == 416 * 417 * The following parameters are required to generate an RSA key: 418 * 419 * o Tag::Key_SIZE specifies the size of the public modulus, in bits. If omitted, generateKey 420 * must return ErrorCode::UNSUPPORTED_KEY_SIZE. Required values for TEE IKeymasterDevice 421 * implementations are 1024, 2048, 3072 and 4096. StrongBox IKeymasterDevice implementations 422 * must support 2048. 423 * 424 * o Tag::RSA_PUBLIC_EXPONENT specifies the RSA public exponent value. If omitted, generateKey 425 * must return ErrorCode::INVALID_ARGUMENT. The values 3 and 65537 must be supported. It is 426 * recommended to support all prime values up to 2^64. If provided with a non-prime value, 427 * generateKey must return ErrorCode::INVALID_ARGUMENT. 428 * 429 * The following parameters are not necessary to generate a usable RSA key, but generateKey must 430 * not return an error if they are omitted: 431 * 432 * o Tag::PURPOSE specifies allowed purposes. All KeyPurpose values (see types.hal) must be 433 * supported for RSA keys. 434 * 435 * o Tag::DIGEST specifies digest algorithms that may be used with the new key. TEE 436 * IKeymasterDevice implementations must support all Digest values (see types.hal) for RSA 437 * keys. StrongBox IKeymasterDevice implementations must support SHA_2_256. 438 * 439 * o Tag::PADDING specifies the padding modes that may be used with the new 440 * key. IKeymasterDevice implementations must support PaddingMode::NONE, 441 * PaddingMode::RSA_OAEP, PaddingMode::RSA_PSS, PaddingMode::RSA_PKCS1_1_5_ENCRYPT and 442 * PaddingMode::RSA_PKCS1_1_5_SIGN for RSA keys. 443 * 444 * == ECDSA Keys == 445 * 446 * Either Tag::KEY_SIZE or Tag::EC_CURVE must be provided to generate an ECDSA key. If neither 447 * is provided, generateKey must return ErrorCode::UNSUPPORTED_KEY_SIZE. If Tag::KEY_SIZE is 448 * provided, the possible values are 224, 256, 384 and 521, and must be mapped to Tag::EC_CURVE 449 * values P_224, P_256, P_384 and P_521, respectively. TEE IKeymasterDevice implementations 450 * must support all curves. StrongBox implementations must support P_256. 451 * 452 * == AES Keys == 453 * 454 * Only Tag::KEY_SIZE is required to generate an AES key. If omitted, generateKey must return 455 * ErrorCode::UNSUPPORTED_KEY_SIZE. 128 and 256-bit key sizes must be supported. 456 * 457 * If Tag::BLOCK_MODE is specified with value BlockMode::GCM, then the caller must also provide 458 * Tag::MIN_MAC_LENGTH. If omitted, generateKey must return ErrorCode::MISSING_MIN_MAC_LENGTH. 459 * 460 * 461 * @param keyParams Key generation parameters are defined as IKeymasterDevice tag/value pairs, 462 * provided in params. See above for detailed specifications of which tags are required 463 * for which types of keys. 464 * 465 * @return keyBlob Opaque descriptor of the generated key. The recommended implementation 466 * strategy is to include an encrypted copy of the key material, wrapped in a key 467 * unavailable outside secure hardware. 468 * 469 * @return keyCharacteristics Description of the generated key. See the getKeyCharacteristics 470 * method below. 471 */ 472 generateKey(vec<KeyParameter> keyParams) 473 generates (ErrorCode error, vec<uint8_t> keyBlob, KeyCharacteristics keyCharacteristics); 474 475 /** 476 * Imports key material into an IKeymasterDevice. Key definition parameters and return values 477 * are the same as for generateKey, with the following exceptions: 478 * 479 * o Tag::KEY_SIZE is not necessary in the input parameters. If not provided, the 480 * IKeymasterDevice must deduce the value from the provided key material and add the tag and 481 * value to the key characteristics. If Tag::KEY_SIZE is provided, the IKeymasterDevice must 482 * validate it against the key material. In the event of a mismatch, importKey must return 483 * ErrorCode::IMPORT_PARAMETER_MISMATCH. 484 * 485 * o Tag::RSA_PUBLIC_EXPONENT (for RSA keys only) is not necessary in the input parameters. If 486 * not provided, the IKeymasterDevice must deduce the value from the provided key material and 487 * add the tag and value to the key characteristics. If Tag::RSA_PUBLIC_EXPONENT is provided, 488 * the IKeymasterDevice must validate it against the key material. In the event of a 489 * mismatch, importKey must return ErrorCode::IMPORT_PARAMETER_MISMATCH. 490 * 491 * o Tag::ORIGIN (returned in keyCharacteristics) must have the value KeyOrigin::IMPORTED. 492 * 493 * @param keyParams Key generation parameters are defined as IKeymasterDevice tag/value pairs, 494 * provided in params. 495 * 496 * @param keyFormat The format of the key material to import. See KeyFormat in types.hal. 497 * 498 * @pram keyData The key material to import, in the format specified in keyFormat. 499 * 500 * @return keyBlob Opaque descriptor of the imported key. The recommended implementation 501 * strategy is to include an encrypted copy of the key material, wrapped in a key 502 * unavailable outside secure hardware. 503 * 504 * @return keyCharacteristics Description of the generated key. See the getKeyCharacteristics 505 * method below. 506 */ 507 importKey(vec<KeyParameter> keyParams, KeyFormat keyFormat, vec<uint8_t> keyData) 508 generates (ErrorCode error, vec<uint8_t> keyBlob, KeyCharacteristics keyCharacteristics); 509 510 /** 511 * Securely imports a key, or key pair, returning a key blob and a description of the imported 512 * key. 513 * 514 * @param wrappedKeyData The wrapped key material to import. The wrapped key is in DER-encoded 515 * ASN.1 format, specified by the following schema: 516 * 517 * KeyDescription ::= SEQUENCE( 518 * keyFormat INTEGER, # Values from KeyFormat enum. 519 * keyParams AuthorizationList, 520 * ) 521 * 522 * SecureKeyWrapper ::= SEQUENCE( 523 * version INTEGER, # Contains value 0 524 * encryptedTransportKey OCTET_STRING, 525 * initializationVector OCTET_STRING, 526 * keyDescription KeyDescription, 527 * encryptedKey OCTET_STRING, 528 * tag OCTET_STRING 529 * ) 530 * 531 * Where: 532 * 533 * o keyFormat is an integer from the KeyFormat enum, defining the format of the plaintext 534 * key material. 535 * o keyParams is the characteristics of the key to be imported (as with generateKey or 536 * importKey). If the secure import is successful, these characteristics must be 537 * associated with the key exactly as if the key material had been insecurely imported 538 * with the @3.0::IKeymasterDevice::importKey. See attestKey() for documentation of the 539 * AuthorizationList schema. 540 * o encryptedTransportKey is a 256-bit AES key, XORed with a masking key and then encrypted 541 * with the wrapping key specified by wrappingKeyBlob. 542 * o keyDescription is a KeyDescription, above. 543 * o encryptedKey is the key material of the key to be imported, in format keyFormat, and 544 * encrypted with encryptedEphemeralKey in AES-GCM mode, with the DER-encoded 545 * representation of keyDescription provided as additional authenticated data. 546 * o tag is the tag produced by the AES-GCM encryption of encryptedKey. 547 * 548 * So, importWrappedKey does the following: 549 * 550 * 1. Get the private key material for wrappingKeyBlob, verifying that the wrapping key has 551 * purpose KEY_WRAP, padding mode RSA_OAEP, and digest SHA_2_256, returning the 552 * appropriate error if any of those requirements fail. 553 * 2. Extract the encryptedTransportKey field from the SecureKeyWrapper, and decrypt 554 * it with the wrapping key. 555 * 3. XOR the result of step 2 with maskingKey. 556 * 4. Use the result of step 3 as an AES-GCM key to decrypt encryptedKey, using the encoded 557 * value of keyDescription as the additional authenticated data. Call the result 558 * "keyData" for the next step. 559 * 5. Perform the equivalent of calling importKey(keyParams, keyFormat, keyData), except 560 * that the origin tag should be set to SECURELY_IMPORTED. 561 * 562 * @param wrappingKeyBlob The opaque key descriptor returned by generateKey() or importKey(). 563 * This key must have been created with Purpose::WRAP_KEY. 564 * 565 * @param maskingKey The 32-byte value XOR'd with the transport key in the SecureWrappedKey 566 * structure. 567 * 568 * @param unwrappingParams must contain any parameters needed to perform the unwrapping 569 * operation. For example, if the wrapping key is an AES key the block and padding modes 570 * must be specified in this argument. 571 * 572 * @param passwordSid specifies the password secure ID (SID) of the user that owns the key being 573 * installed. If the authorization list in wrappedKeyData contains a Tag::USER_SECURE_ID 574 * with a value that has the HardwareAuthenticatorType::PASSWORD bit set, the constructed 575 * key must be bound to the SID value provided by this argument. If the wrappedKeyData 576 * does not contain such a tag and value, this argument must be ignored. 577 * 578 * @param biometricSid specifies the biometric secure ID (SID) of the user that owns the key 579 * being installed. If the authorization list in wrappedKeyData contains a 580 * Tag::USER_SECURE_ID with a value that has the HardwareAuthenticatorType::FINGERPRINT 581 * bit set, the constructed key must be bound to the SID value provided by this argument. 582 * If the wrappedKeyData does not contain such a tag and value, this argument must be 583 * ignored. 584 * 585 * @return keyBlob Opaque descriptor of the imported key. It is recommended that the keyBlob 586 * contain a copy of the key material, wrapped in a key unavailable outside secure 587 * hardware. 588 */ 589 importWrappedKey(vec<uint8_t> wrappedKeyData, vec<uint8_t> wrappingKeyBlob, 590 vec<uint8_t> maskingKey, vec<KeyParameter> unwrappingParams, 591 uint64_t passwordSid, uint64_t biometricSid) 592 generates(ErrorCode error, vec<uint8_t> keyBlob, KeyCharacteristics keyCharacteristics); 593 594 /** 595 * Returns parameters associated with the provided key, divided into two sets: hardware-enforced 596 * and software-enforced. The description here applies equally to the key characteristics lists 597 * returned by generateKey, importKey and importWrappedKey. The characteristics returned by 598 * this method completely describe the type and usage of the specified key. 599 * 600 * The rule that IKeymasterDevice implementations must use for deciding whether a given tag 601 * belongs in the hardware-enforced or software-enforced list is that if the meaning of the tag 602 * is fully assured by secure hardware, it is hardware enforced. Otherwise, it's software 603 * enforced. 604 * 605 * 606 * @param keyBlob The opaque descriptor returned by generateKey, importKey or importWrappedKey. 607 * 608 * @param clientId An opaque byte string identifying the client. This value must match the 609 * Tag::APPLICATION_ID data provided during key generation/import. Without the correct 610 * value, it must be computationally infeasible for the secure hardware to obtain the key 611 * material. 612 * 613 * @param appData An opaque byte string provided by the application. This value must match the 614 * Tag::APPLICATION_DATA data provided during key generation/import. Without the correct 615 * value, it must be computationally infeasible for the secure hardware to obtain the key 616 * material. 617 * 618 * @return keyCharacteristics Description of the generated key. See KeyCharacteristics in 619 * types.hal. 620 */ 621 getKeyCharacteristics(vec<uint8_t> keyBlob, vec<uint8_t> clientId, vec<uint8_t> appData) 622 generates (ErrorCode error, KeyCharacteristics keyCharacteristics); 623 624 /** 625 * Exports a public key, returning the key in the specified format. 626 * 627 * @parm keyFormat The format used for export. See KeyFormat in types.hal. 628 * 629 * @param keyBlob The opaque descriptor returned by generateKey() or importKey(). The 630 * referenced key must be asymmetric. 631 * 632 * @param clientId An opaque byte string identifying the client. This value must match the 633 * Tag::APPLICATION_ID data provided during key generation/import. Without the correct 634 * value, it must be computationally infeasible for the secure hardware to obtain the key 635 * material. 636 * 637 * @param appData An opaque byte string provided by the application. This value must match the 638 * Tag::APPLICATION_DATA data provided during key generation/import. Without the correct 639 * value, it must be computationally infeasible for the secure hardware to obtain the key 640 * material. 641 * 642 * @return keyMaterial The public key material in PKCS#8 format. 643 */ 644 exportKey(KeyFormat keyFormat, vec<uint8_t> keyBlob, vec<uint8_t> clientId, 645 vec<uint8_t> appData) generates (ErrorCode error, vec<uint8_t> keyMaterial); 646 647 /** 648 * Generates a signed X.509 certificate chain attesting to the presence of keyToAttest in 649 * Keymaster. 650 * 651 * The certificates in the chain must be ordered such that each certificate is signed by the 652 * subsequent one, up to the root which must be self-signed. The first certificate in the chain 653 * signs the public key info of the attested key and must contain the following entries (see RFC 654 * 5280 for details on each): 655 * 656 * o version -- with value 2 657 * 658 * o serialNumber -- with value 1 (same value for all keys) 659 * 660 * o signature -- contains an the AlgorithmIdentifier of the algorithm used to sign, must be 661 * ECDSA for EC keys, RSA for RSA keys. 662 * 663 * o issuer -- must contain the same value as the Subject field of the next certificate. 664 * 665 * o validity -- SEQUENCE of two dates, containing the values of Tag::ACTIVE_DATETIME and 666 * Tag::USAGE_EXPIRE_DATETIME. The tag values are in milliseconds since Jan 1, 1970; see RFD 667 * 5280 for the correct representation in certificates. If Tag::ACTIVE_DATETIME is not 668 * present in the key, the IKeymasterDevice must use the value of Tag::CREATION_DATETIME. If 669 * Tag::USAGE_EXPIRE_DATETIME is not present, the IKeymasterDevice must use the expiration 670 * date of the batch attestation certificate (see below). 671 * 672 * o subject -- CN="Android Keystore Key" (same value for all keys) 673 * 674 * o subjectPublicKeyInfo -- X.509 SubjectPublicKeyInfo containing the attested public key. 675 * 676 * o Key Usage extension -- digitalSignature bit must be set iff the attested key has 677 * KeyPurpose::SIGN. dataEncipherment bit must be set iff the attested key has 678 * KeyPurpose::DECRYPT. keyEncipherment bit must be set iff the attested key has 679 * KeyPurpose::KEY_WRAP. All other bits must be clear. 680 * 681 * In addition to the above, the attestation certificate must contain an extension with OID 682 * 1.3.6.1.4.1.11129.2.1.17 and value according to the KeyDescription schema defined as: 683 * 684 * KeyDescription ::= SEQUENCE { 685 * attestationVersion INTEGER, # Value 3 686 * attestationSecurityLevel SecurityLevel, # See below 687 * keymasterVersion INTEGER, # Value 4 688 * keymasterSecurityLevel SecurityLevel, # See below 689 * attestationChallenge OCTET_STRING, # Tag::ATTESTATION_CHALLENGE from attestParams 690 * uniqueId OCTET_STRING, # Empty unless key has Tag::INCLUDE_UNIQUE_ID 691 * softwareEnforced AuthorizationList, # See below 692 * hardwareEnforced AuthorizationList, # See below 693 * } 694 * 695 * SecurityLevel ::= ENUMERATED { 696 * Software (0), 697 * TrustedEnvironment (1), 698 * StrongBox (2), 699 * } 700 * 701 * RootOfTrust ::= SEQUENCE { 702 * verifiedBootKey OCTET_STRING, 703 * deviceLocked BOOLEAN, 704 * verifiedBootState VerifiedBootState, 705 * # verifiedBootHash must contain 32-byte value that represents the state of all binaries 706 * # or other components validated by verified boot. Updating any verified binary or 707 * # component must cause this value to change. 708 * verifiedBootHash OCTET_STRING, 709 * } 710 * 711 * VerifiedBootState ::= ENUMERATED { 712 * Verified (0), 713 * SelfSigned (1), 714 * Unverified (2), 715 * Failed (3), 716 * } 717 * 718 * AuthorizationList ::= SEQUENCE { 719 * purpose [1] EXPLICIT SET OF INTEGER OPTIONAL, 720 * algorithm [2] EXPLICIT INTEGER OPTIONAL, 721 * keySize [3] EXPLICIT INTEGER OPTIONAL, 722 * blockMode [4] EXPLICIT SET OF INTEGER OPTIONAL, 723 * digest [5] EXPLICIT SET OF INTEGER OPTIONAL, 724 * padding [6] EXPLICIT SET OF INTEGER OPTIONAL, 725 * callerNonce [7] EXPLICIT NULL OPTIONAL, 726 * minMacLength [8] EXPLICIT INTEGER OPTIONAL, 727 * ecCurve [10] EXPLICIT INTEGER OPTIONAL, 728 * rsaPublicExponent [200] EXPLICIT INTEGER OPTIONAL, 729 * rollbackResistance [303] EXPLICIT NULL OPTIONAL, 730 * activeDateTime [400] EXPLICIT INTEGER OPTIONAL, 731 * originationExpireDateTime [401] EXPLICIT INTEGER OPTIONAL, 732 * usageExpireDateTime [402] EXPLICIT INTEGER OPTIONAL, 733 * userSecureId [502] EXPLICIT INTEGER OPTIONAL, 734 * noAuthRequired [503] EXPLICIT NULL OPTIONAL, 735 * userAuthType [504] EXPLICIT INTEGER OPTIONAL, 736 * authTimeout [505] EXPLICIT INTEGER OPTIONAL, 737 * allowWhileOnBody [506] EXPLICIT NULL OPTIONAL, 738 * trustedUserPresenceReq [507] EXPLICIT NULL OPTIONAL, 739 * trustedConfirmationReq [508] EXPLICIT NULL OPTIONAL, 740 * unlockedDeviceReq [509] EXPLICIT NULL OPTIONAL, 741 * creationDateTime [701] EXPLICIT INTEGER OPTIONAL, 742 * origin [702] EXPLICIT INTEGER OPTIONAL, 743 * rootOfTrust [704] EXPLICIT RootOfTrust OPTIONAL, 744 * osVersion [705] EXPLICIT INTEGER OPTIONAL, 745 * osPatchLevel [706] EXPLICIT INTEGER OPTIONAL, 746 * attestationApplicationId [709] EXPLICIT OCTET_STRING OPTIONAL, 747 * attestationIdBrand [710] EXPLICIT OCTET_STRING OPTIONAL, 748 * attestationIdDevice [711] EXPLICIT OCTET_STRING OPTIONAL, 749 * attestationIdProduct [712] EXPLICIT OCTET_STRING OPTIONAL, 750 * attestationIdSerial [713] EXPLICIT OCTET_STRING OPTIONAL, 751 * attestationIdImei [714] EXPLICIT OCTET_STRING OPTIONAL, 752 * attestationIdMeid [715] EXPLICIT OCTET_STRING OPTIONAL, 753 * attestationIdManufacturer [716] EXPLICIT OCTET_STRING OPTIONAL, 754 * attestationIdModel [717] EXPLICIT OCTET_STRING OPTIONAL, 755 * vendorPatchLevel [718] EXPLICIT INTEGER OPTIONAL, 756 * bootPatchLevel [719] EXPLICIT INTEGER OPTIONAL, 757 * } 758 * 759 * The above schema is mostly a straightforward translation of the IKeymasterDevice tag/value 760 * parameter lists to ASN.1: 761 * 762 * o TagType::ENUM, TagType::UINT, TagType::ULONG and TagType::DATE tags are represented as 763 * ASN.1 INTEGER. 764 * 765 * o TagType::ENUM_REP, TagType::UINT_REP and TagType::ULONG_REP tags are represented as ASN.1 766 * SET of INTEGER. 767 * 768 * o TagType::BOOL tags are represented as ASN.1 NULL. All entries in AuthorizationList are 769 * OPTIONAL, so the presence of the tag means "true", absence means "false". 770 * 771 * o TagType::BYTES tags are represented as ASN.1 OCTET_STRING. 772 * 773 * The numeric ASN.1 tag numbers are the same values as the IKeymasterDevice Tag enum values, 774 * except with the TagType modifier stripped. 775 * 776 * The attestation certificate must be signed by a "batch" key, which must be securely 777 * pre-installed into the device, generally in the factory, and securely stored to prevent 778 * access or extraction. The batch key must be used only for signing attestation certificates. 779 * The batch attestation certificate must be signed by a chain or zero or more intermediates 780 * leading to a self-signed roots. The intermediate and root certificate signing keys must not 781 * exist anywhere on the device. 782 * 783 * == ID Attestation == 784 * 785 * ID attestation is a special case of key attestation in which unique device ID values are 786 * included in the signed attestation certificate. 787 * 788 * @param keyToAttest The opaque descriptor returned by generateKey() or importKey(). The 789 * referenced key must be asymmetric. 790 * 791 * @param attestParams Parameters for the attestation. Must contain Tag::ATTESTATION_CHALLENGE, 792 * the value of which must be put in the attestationChallenge field of the KeyDescription 793 * ASN.1 structure defined above. 794 * 795 * @return certChain The attestation certificate, and additional certificates back to the root 796 * attestation certificate, which clients will need to check against a known-good value. 797 * The certificates must be DER-encoded. 798 */ 799 attestKey(vec<uint8_t> keyToAttest, vec<KeyParameter> attestParams) 800 generates (ErrorCode error, vec<vec<uint8_t>> certChain); 801 802 /** 803 * Upgrades an old key blob. Keys can become "old" in two ways: IKeymasterDevice can be 804 * upgraded to a new version with an incompatible key blob format, or the system can be updated 805 * to invalidate the OS version (OS_VERSION tag), system patch level (OS_PATCHLEVEL tag), vendor 806 * patch level (VENDOR_PATCH_LEVEL tag), boot patch level (BOOT_PATCH_LEVEL tag) or other, 807 * implementation-defined patch level (keymaster implementers are encouraged to extend this HAL 808 * with a minor version extension to define validatable patch levels for other images; tags must 809 * be defined in the implementer's namespace, starting at 10000). In either case, attempts to 810 * use an old key blob with getKeyCharacteristics(), exportKey(), attestKey() or begin() must 811 * result in IKeymasterDevice returning ErrorCode::KEY_REQUIRES_UPGRADE. The caller must use 812 * this method to upgrade the key blob. 813 * 814 * The upgradeKey method must examine each version or patch level associated with the key. If 815 * any one of them is higher than the corresponding current device value upgradeKey() must 816 * return ErrorCode::INVALID_ARGUMENT. There is one exception: it is always permissible to 817 * "downgrade" from any OS_VERSION number to OS_VERSION 0. For example, if the key has 818 * OS_VERSION 080001, it is permissible to upgrade the key if the current system version is 819 * 080100, because the new version is larger, or if the current system version is 0, because 820 * upgrades to 0 are always allowed. If the system version were 080000, however, keymaster must 821 * return ErrorCode::INVALID_ARGUMENT because that value is smaller than 080001. Values other 822 * than OS_VERSION must never be downgraded. 823 * 824 * Note that Keymaster versions 2 and 3 required that the system and boot images have the same 825 * patch level and OS version. This requirement is relaxed for 4.0::IKeymasterDevice, and the 826 * OS version in the boot image footer is no longer used. 827 * 828 * @param keyBlobToUpgrade The opaque descriptor returned by generateKey() or importKey(); 829 * 830 * @param upgradeParams A parameter list containing any parameters needed to complete the 831 * upgrade, including Tag::APPLICATION_ID and Tag::APPLICATION_DATA. 832 * 833 * @return upgradedKeyBlob A new key blob that references the same key as keyBlobToUpgrade, but 834 * is in the new format, or has the new version data. 835 */ 836 upgradeKey(vec<uint8_t> keyBlobToUpgrade, vec<KeyParameter> upgradeParams) 837 generates (ErrorCode error, vec<uint8_t> upgradedKeyBlob); 838 839 /** 840 * Deletes the key, or key pair, associated with the key blob. Calling this function on a key 841 * with Tag::ROLLBACK_RESISTANCE in its hardware-enforced authorization list must render the key 842 * permanently unusable. Keys without Tag::ROLLBACK_RESISTANCE may or may not be rendered 843 * unusable. 844 * 845 * @param keyBlob The opaque descriptor returned by generateKey() or importKey(); 846 */ 847 deleteKey(vec<uint8_t> keyBlob) generates (ErrorCode error); 848 849 /** 850 * Deletes all keys in the hardware keystore. Used when keystore is reset completely. After 851 * this function is called all keys with Tag::ROLLBACK_RESISTANCE in their hardware-enforced 852 * authorization lists must be rendered permanently unusable. Keys without 853 * Tag::ROLLBACK_RESISTANCE may or may not be rendered unusable. 854 * 855 * @return error See the ErrorCode enum. 856 */ 857 deleteAllKeys() generates (ErrorCode error); 858 859 /** 860 * Destroys knowledge of the device's ids. This prevents all device id attestation in the 861 * future. The destruction must be permanent so that not even a factory reset will restore the 862 * device ids. 863 * 864 * Device id attestation may be provided only if this method is fully implemented, allowing the 865 * user to permanently disable device id attestation. If this cannot be guaranteed, the device 866 * must never attest any device ids. 867 * 868 * This is a NOP if device id attestation is not supported. 869 */ 870 destroyAttestationIds() generates (ErrorCode error); 871 872 /** 873 * Begins a cryptographic operation using the specified key. If all is well, begin() must 874 * return ErrorCode::OK and create an operation handle which must be passed to subsequent calls 875 * to update(), finish() or abort(). 876 * 877 * It is critical that each call to begin() be paired with a subsequent call to finish() or 878 * abort(), to allow the IKeymasterDevice implementation to clean up any internal operation 879 * state. The caller's failure to do this may leak internal state space or other internal 880 * resources and may eventually cause begin() to return ErrorCode::TOO_MANY_OPERATIONS when it 881 * runs out of space for operations. Any result other than ErrorCode::OK from begin(), update() 882 * or finish() implicitly aborts the operation, in which case abort() need not be called (and 883 * must return ErrorCode::INVALID_OPERATION_HANDLE if called). IKeymasterDevice implementations 884 * must support 16 concurrent operations. 885 * 886 * If Tag::APPLICATION_ID or Tag::APPLICATION_DATA were specified during key generation or 887 * import, calls to begin must include those tags with the originally-specified values in the 888 * inParams argument to this method. If not, begin() must return ErrorCode::INVALID_KEY_BLOB. 889 * 890 * == Authorization Enforcement == 891 * 892 * The following key authorization parameters must be enforced by the IKeymasterDevice secure 893 * environment if the tags were returned in the "hardwareEnforced" list in the 894 * KeyCharacteristics. Public key operations, meaning KeyPurpose::ENCRYPT and 895 * KeyPurpose::VERIFY must be allowed to succeed even if authorization requirements are not met. 896 * 897 * -- All Key Types -- 898 * 899 * The tags in this section apply to all key types. See below for additional key type-specific 900 * tags. 901 * 902 * o Tag::PURPOSE: The purpose specified in the begin() call must match one of the purposes in 903 * the key authorizations. If the specified purpose does not match, begin() must return 904 * ErrorCode::UNSUPPORTED_PURPOSE. 905 * 906 * o Tag::ACTIVE_DATETIME can only be enforced if a trusted UTC time source is available. If 907 * the current date and time is prior to the tag value, begin() must return 908 * ErrorCode::KEY_NOT_YET_VALID. 909 * 910 * o Tag::ORIGINATION_EXPIRE_DATETIME can only be enforced if a trusted UTC time source is 911 * available. If the current date and time is later than the tag value and the purpose is 912 * KeyPurpose::ENCRYPT or KeyPurpose::SIGN, begin() must return ErrorCode::KEY_EXPIRED. 913 * 914 * o Tag::USAGE_EXPIRE_DATETIME can only be enforced if a trusted UTC time source is 915 * available. If the current date and time is later than the tag value and the purpose is 916 * KeyPurpose::DECRYPT or KeyPurpose::VERIFY, begin() must return ErrorCode::KEY_EXPIRED. 917 918 * o Tag::MIN_SECONDS_BETWEEN_OPS must be compared with a trusted relative timer indicating the 919 * last use of the key. If the last use time plus the tag value is less than the current 920 * time, begin() must return ErrorCode::KEY_RATE_LIMIT_EXCEEDED. See the tag description for 921 * important implementation details. 922 923 * o Tag::MAX_USES_PER_BOOT must be compared against a secure counter that tracks the uses of 924 * the key since boot time. If the count of previous uses exceeds the tag value, begin() must 925 * return ErrorCode::KEY_MAX_OPS_EXCEEDED. 926 * 927 * o Tag::USER_SECURE_ID must be enforced by this method if and only if the key also has 928 * Tag::AUTH_TIMEOUT (if it does not have Tag::AUTH_TIMEOUT, the Tag::USER_SECURE_ID 929 * requirement must be enforced by update() and finish()). If the key has both, then this 930 * method must receive a non-empty HardwareAuthToken in the authToken argument. For the auth 931 * token to be valid, all of the following have to be true: 932 * 933 * o The HMAC field must validate correctly. 934 * 935 * o At least one of the Tag::USER_SECURE_ID values from the key must match at least one of 936 * the secure ID values in the token. 937 * 938 * o The key must have a Tag::USER_AUTH_TYPE that matches the auth type in the token. 939 * 940 * o The timestamp in the auth token plus the value of the Tag::AUTH_TIMEOUT must be less than 941 * the current secure timestamp (which is a monotonic timer counting milliseconds since 942 * boot.) 943 * 944 * If any of these conditions are not met, begin() must return 945 * ErrorCode::KEY_USER_NOT_AUTHENTICATED. 946 * 947 * o Tag::CALLER_NONCE allows the caller to specify a nonce or initialization vector (IV). If 948 * the key doesn't have this tag, but the caller provided Tag::NONCE to this method, 949 * ErrorCode::CALLER_NONCE_PROHIBITED must be returned. 950 * 951 * o Tag::BOOTLOADER_ONLY specifies that only the bootloader may use the key. If this method is 952 * called with a bootloader-only key after the bootloader has finished executing, it must 953 * return ErrorCode::INVALID_KEY_BLOB. The mechanism for notifying the IKeymasterDevice that 954 * the bootloader has finished executing is implementation-defined. 955 * 956 * -- RSA Keys -- 957 * 958 * All RSA key operations must specify exactly one padding mode in inParams. If unspecified or 959 * specified more than once, the begin() must return ErrorCode::UNSUPPORTED_PADDING_MODE. 960 * 961 * RSA signing and verification operations need a digest, as do RSA encryption and decryption 962 * operations with OAEP padding mode. For those cases, the caller must specify exactly one 963 * digest in inParams. If unspecified or specified more than once, begin() must return 964 * ErrorCode::UNSUPPORTED_DIGEST. 965 * 966 * Private key operations (KeyPurpose::DECRYPT and KeyPurpose::SIGN) need authorization of 967 * digest and padding, which means that the key authorizations need to contain the specified 968 * values. If not, begin() must return ErrorCode::INCOMPATIBLE_DIGEST or 969 * ErrorCode::INCOMPATIBLE_PADDING, as appropriate. Public key operations (KeyPurpose::ENCRYPT 970 * and KeyPurpose::VERIFY) are permitted with unauthorized digest or padding modes. 971 * 972 * With the exception of PaddingMode::NONE, all RSA padding modes are applicable only to certain 973 * purposes. Specifically, PaddingMode::RSA_PKCS1_1_5_SIGN and PaddingMode::RSA_PSS only 974 * support signing and verification, while PaddingMode::RSA_PKCS1_1_5_ENCRYPT and 975 * PaddingMode::RSA_OAEP only support encryption and decryption. begin() must return 976 * ErrorCode::UNSUPPORTED_PADDING_MODE if the specified mode does not support the specified 977 * purpose. 978 * 979 * There are some important interactions between padding modes and digests: 980 * 981 * o PaddingMode::NONE indicates that a "raw" RSA operation is performed. If signing or 982 * verifying, Digest::NONE is specified for the digest. No digest is necessary for unpadded 983 * encryption or decryption. 984 * 985 * o PaddingMode::RSA_PKCS1_1_5_SIGN padding requires a digest. The digest may be Digest::NONE, 986 * in which case the Keymaster implementation cannot build a proper PKCS#1 v1.5 signature 987 * structure, because it cannot add the DigestInfo structure. Instead, the IKeymasterDevice 988 * must construct 0x00 || 0x01 || PS || 0x00 || M, where M is the provided message and PS is a 989 * random padding string at least eight bytes in length. The size of the RSA key has to be at 990 * least 11 bytes larger than the message, otherwise begin() must return 991 * ErrorCode::INVALID_INPUT_LENGTH. 992 * 993 * o PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT padding does not require a digest. 994 * 995 * o PaddingMode::RSA_PSS padding requires a digest, which may not be Digest::NONE. If 996 * Digest::NONE is specified, the begin() must return ErrorCode::INCOMPATIBLE_DIGEST. In 997 * addition, the size of the RSA key must be at least 2 + D bytes larger than the output size 998 * of the digest, where D is the size of the digest, in bytes. Otherwise begin() must 999 * return ErrorCode::INCOMPATIBLE_DIGEST. The salt size must be D. 1000 * 1001 * o PaddingMode::RSA_OAEP padding requires a digest, which may not be Digest::NONE. If 1002 * Digest::NONE is specified, begin() must return ErrorCode::INCOMPATIBLE_DIGEST. The OAEP 1003 * mask generation function must be MGF1 and the MGF1 digest must be SHA1, regardless of the 1004 * OAEP digest specified. 1005 * 1006 * -- EC Keys -- 1007 * 1008 * EC key operations must specify exactly one padding mode in inParams. If unspecified or 1009 * specified more than once, begin() must return ErrorCode::UNSUPPORTED_PADDING_MODE. 1010 * 1011 * Private key operations (KeyPurpose::SIGN) need authorization of digest and padding, which 1012 * means that the key authorizations must contain the specified values. If not, begin() must 1013 * return ErrorCode::INCOMPATIBLE_DIGEST. Public key operations (KeyPurpose::VERIFY) are 1014 * permitted with unauthorized digest or padding. 1015 * 1016 * -- AES Keys -- 1017 * 1018 * AES key operations must specify exactly one block mode (Tag::BLOCK_MODE) and one padding mode 1019 * (Tag::PADDING) in inParams. If either value is unspecified or specified more than once, 1020 * begin() must return ErrorCode::UNSUPPORTED_BLOCK_MODE or 1021 * ErrorCode::UNSUPPORTED_PADDING_MODE. The specified modes must be authorized by the key, 1022 * otherwise begin() must return ErrorCode::INCOMPATIBLE_BLOCK_MODE or 1023 * ErrorCode::INCOMPATIBLE_PADDING_MODE. 1024 * 1025 * If the block mode is BlockMode::GCM, inParams must specify Tag::MAC_LENGTH, and the specified 1026 * value must be a multiple of 8 that is not greater than 128 or less than the value of 1027 * Tag::MIN_MAC_LENGTH in the key authorizations. For MAC lengths greater than 128 or 1028 * non-multiples of 8, begin() must return ErrorCode::UNSUPPORTED_MAC_LENGTH. For values less 1029 * than the key's minimum length, begin() must return ErrorCode::INVALID_MAC_LENGTH. 1030 * 1031 * If the block mode is BlockMode::GCM or BlockMode::CTR, the specified padding mode must be 1032 * PaddingMode::NONE. For BlockMode::ECB or BlockMode::CBC, the mode may be PaddingMode::NONE 1033 * or PaddingMode::PKCS7. If the padding mode doesn't meet these conditions, begin() must 1034 * return ErrorCode::INCOMPATIBLE_PADDING_MODE. 1035 * 1036 * If the block mode is BlockMode::CBC, BlockMode::CTR, or BlockMode::GCM, an initialization 1037 * vector or nonce is required. In most cases, callers shouldn't provide an IV or nonce and the 1038 * IKeymasterDevice implementation must generate a random IV or nonce and return it via 1039 * Tag::NONCE in outParams. CBC and CTR IVs are 16 bytes. GCM nonces are 12 bytes. If the key 1040 * authorizations contain Tag::CALLER_NONCE, then the caller may provide an IV/nonce with 1041 * Tag::NONCE in inParams. If a nonce is provided when Tag::CALLER_NONCE is not authorized, 1042 * begin() must return ErrorCode::CALLER_NONCE_PROHIBITED. If a nonce is not provided when 1043 * Tag::CALLER_NONCE is authorized, IKeymasterDevice must generate a random IV/nonce. 1044 * 1045 * -- HMAC keys -- 1046 * 1047 * HMAC key operations must specify Tag::MAC_LENGTH in inParams. The specified value must be a 1048 * multiple of 8 that is not greater than the digest length or less than the value of 1049 * Tag::MIN_MAC_LENGTH in the key authorizations. For MAC lengths greater than the digest 1050 * length or non-multiples of 8, begin() must return ErrorCode::UNSUPPORTED_MAC_LENGTH. For 1051 * values less than the key's minimum length, begin() must return ErrorCode::INVALID_MAC_LENGTH. 1052 * 1053 * @param purpose The purpose of the operation, one of KeyPurpose::ENCRYPT, KeyPurpose::DECRYPT, 1054 * KeyPurpose::SIGN or KeyPurpose::VERIFY. Note that for AEAD modes, encryption and 1055 * decryption imply signing and verification, respectively, but must be specified as 1056 * KeyPurpose::ENCRYPT and KeyPurpose::DECRYPT. 1057 * 1058 * @param keyBlob The opaque key descriptor returned by generateKey() or importKey(). The key 1059 * must have a purpose compatible with purpose and all of its usage requirements must be 1060 * satisfied, or begin() must return an appropriate error code (see above). 1061 * 1062 * @param inParams Additional parameters for the operation. If Tag::APPLICATION_ID or 1063 * Tag::APPLICATION_DATA were provided during generation, they must be provided here, or 1064 * the operation must fail with ErrorCode::INVALID_KEY_BLOB. For operations that require 1065 * a nonce or IV, on keys that were generated with Tag::CALLER_NONCE, inParams may 1066 * contain a tag Tag::NONCE. If Tag::NONCE is provided for a key without 1067 * Tag:CALLER_NONCE, ErrorCode::CALLER_NONCE_PROHIBITED must be returned. 1068 * 1069 * @param authToken Authentication token. Callers that provide no token must set all numeric 1070 * fields to zero and the MAC must be an empty vector. 1071 * 1072 * @return outParams Output parameters. Used to return additional data from the operation 1073 * initialization, notably to return the IV or nonce from operations that generate an IV 1074 * or nonce. 1075 * 1076 * @return operationHandle The newly-created operation handle which must be passed to update(), 1077 * finish() or abort(). 1078 */ 1079 begin(KeyPurpose purpose, vec<uint8_t> keyBlob, vec<KeyParameter> inParams, 1080 HardwareAuthToken authToken) 1081 generates (ErrorCode error, vec<KeyParameter> outParams, OperationHandle operationHandle); 1082 1083 /** 1084 * Provides data to, and possibly receives output from, an ongoing cryptographic operation begun 1085 * with begin(). The operation is specified by the operationHandle parameter. 1086 * 1087 * If operationHandle is invalid, update() must return ErrorCode::INVALID_OPERATION_HANDLE. 1088 * 1089 * To provide more flexibility for buffer handling, implementations of this method have the 1090 * option of consuming less data than was provided. The caller is responsible for looping to 1091 * feed the rest of the data in subsequent calls. The amount of input consumed must be returned 1092 * in the inputConsumed parameter. Implementations must always consume at least one byte, unless 1093 * the operation cannot accept any more; if more than zero bytes are provided and zero bytes are 1094 * consumed, callers must consider this an error and abort the operation. 1095 * 1096 * Implementations may also choose how much data to return, as a result of the update. This is 1097 * only relevant for encryption and decryption operations, because signing and verification 1098 * return no data until finish. It is recommended to return data as early as possible, rather 1099 * than buffer it. 1100 * 1101 * If this method returns an error code other than ErrorCode::OK, the operation is aborted and 1102 * the operation handle must be invalidated. Any future use of the handle, with this method, 1103 * finish, or abort, must return ErrorCode::INVALID_OPERATION_HANDLE. 1104 * 1105 * == Authorization Enforcement == 1106 * 1107 * Key authorization enforcement is performed primarily in begin(). The one exception is the 1108 * case where the key has: 1109 1110 * o One or more Tag::USER_SECURE_IDs, and 1111 * 1112 * o Does not have a Tag::AUTH_TIMEOUT 1113 * 1114 * In this case, the key requires an authorization per operation, and the update method must 1115 * receive a non-empty and valid HardwareAuthToken. For the auth token to be valid, all of the 1116 * following has to be true: 1117 * 1118 * o The HMAC field must validate correctly. 1119 * 1120 * o At least one of the Tag::USER_SECURE_ID values from the key must match at least one of 1121 * the secure ID values in the token. 1122 * 1123 * o The key must have a Tag::USER_AUTH_TYPE that matches the auth type in the token. 1124 * 1125 * o The challenge field in the auth token must contain the operationHandle 1126 * 1127 * If any of these conditions are not met, update() must return 1128 * ErrorCode::KEY_USER_NOT_AUTHENTICATED. 1129 * 1130 * The caller must provide the auth token on every call to update() and finish(). 1131 * 1132 * -- RSA keys -- 1133 * 1134 * For signing and verification operations with Digest::NONE, this method must accept the entire 1135 * block to be signed or verified in a single update. It may not consume only a portion of the 1136 * block in these cases. However, the caller may choose to provide the data in multiple updates, 1137 * and update() must accept the data this way as well. If the caller provides more data to sign 1138 * than can be used (length of data exceeds RSA key size), update() must return 1139 * ErrorCode::INVALID_INPUT_LENGTH. 1140 * 1141 * -- ECDSA keys -- 1142 * 1143 * For signing and verification operations with Digest::NONE, this method must accept the entire 1144 * block to be signed or verified in a single update. This method may not consume only a 1145 * portion of the block. However, the caller may choose to provide the data in multiple updates 1146 * and update() must accept the data this way as well. If the caller provides more data to sign 1147 * than can be used, the data is silently truncated. (This differs from the handling of excess 1148 * data provided in similar RSA operations. The reason for this is compatibility with legacy 1149 * clients.) 1150 * 1151 * -- AES keys -- 1152 * 1153 * AES GCM mode supports "associated authentication data," provided via the Tag::ASSOCIATED_DATA 1154 * tag in the inParams argument. The associated data may be provided in repeated calls 1155 * (important if the data is too large to send in a single block) but must always precede data 1156 * to be encrypted or decrypted. An update call may receive both associated data and data to 1157 * encrypt/decrypt, but subsequent updates must not include associated data. If the caller 1158 * provides associated data to an update call after a call that includes data to 1159 * encrypt/decrypt, update() must return ErrorCode::INVALID_TAG. 1160 * 1161 * For GCM encryption, the AEAD tag must be appended to the ciphertext by finish(). During 1162 * decryption, the last Tag::MAC_LENGTH bytes of the data provided to the last update call must 1163 * be the AEAD tag. Since a given invocation of update cannot know if it's the last invocation, 1164 * it must process all but the tag length and buffer the possible tag data for processing during 1165 * finish(). 1166 * 1167 * @param operationHandle The operation handle returned by begin(). 1168 * 1169 * @param inParams Additional parameters for the operation. For AEAD modes, this is used to 1170 * specify Tag::ADDITIONAL_DATA. Note that additional data may be provided in multiple 1171 * calls to update(), but only until input data has been provided. 1172 * 1173 * @param input Data to be processed. Note that update() may or may not consume all of the data 1174 * provided. See inputConsumed. 1175 * 1176 * @param authToken Authentication token. Callers that provide no token must set all numeric 1177 * fields to zero and the MAC must be an empty vector. 1178 * 1179 * @param verificationToken Verification token, used to prove that another IKeymasterDevice HAL 1180 * has verified some parameters, and to deliver the other HAL's current timestamp, if 1181 * needed. If not provided, all fields must be initialized to zero and vectors must be 1182 * empty. 1183 * 1184 * @return error See the ErrorCode enum in types.hal. 1185 * 1186 * @return inputConsumed Amount of data that was consumed by update(). If this is less than the 1187 * amount provided, the caller may provide the remainder in a subsequent call to 1188 * update() or finish(). Every call to update must consume at least one byte, unless 1189 * the input is empty, and implementations should consume as much data as reasonably 1190 * possible for each call. 1191 * 1192 * @return outParams Output parameters, used to return additional data from the operation. 1193 * 1194 * @return output The output data, if any. 1195 */ 1196 update(OperationHandle operationHandle, vec<KeyParameter> inParams, vec<uint8_t> input, 1197 HardwareAuthToken authToken, VerificationToken verificationToken) 1198 generates (ErrorCode error, uint32_t inputConsumed, vec<KeyParameter> outParams, 1199 vec<uint8_t> output); 1200 1201 /** 1202 * Finalizes a cryptographic operation begun with begin() and invalidates operationHandle. 1203 * 1204 * This method is the last one called in an operation, so all processed data must be returned. 1205 * 1206 * Whether it completes successfully or returns an error, this method finalizes the operation 1207 * and therefore must invalidate the provided operation handle. Any future use of the handle, 1208 * with finish(), update(), or abort(), must return ErrorCode::INVALID_OPERATION_HANDLE. 1209 * 1210 * Signing operations return the signature as the output. Verification operations accept the 1211 * signature in the signature parameter, and return no output. 1212 * 1213 * == Authorization enforcement == 1214 * 1215 * Key authorization enforcement is performed primarily in begin(). The exceptions are 1216 * authorization per operation keys and confirmation-required keys. 1217 * 1218 * Authorization per operation keys are the case where the key has one or more 1219 * Tag::USER_SECURE_IDs, and does not have a Tag::AUTH_TIMEOUT. In this case, the key requires 1220 * an authorization per operation, and the finish method must receive a non-empty and valid 1221 * authToken. For the auth token to be valid, all of the following has to be true: 1222 * 1223 * o The HMAC field must validate correctly. 1224 * 1225 * o At least one of the Tag::USER_SECURE_ID values from the key must match at least one of 1226 * the secure ID values in the token. 1227 * 1228 * o The key must have a Tag::USER_AUTH_TYPE that matches the auth type in the token. 1229 * 1230 * o The challenge field in the auth token must contain the operationHandle 1231 * 1232 * If any of these conditions are not met, update() must return 1233 * ErrorCode::KEY_USER_NOT_AUTHENTICATED. 1234 * 1235 * The caller must provide the auth token on every call to update() and finish(). 1236 * 1237 * Confirmation-required keys are keys that were generated with 1238 * Tag::TRUSTED_CONFIRMATION_REQUIRED. For these keys, when doing a signing operation the 1239 * caller must pass a KeyParameter Tag::CONFIRMATION_TOKEN to finish(). Implementations must 1240 * check the confirmation token by computing the 32-byte HMAC-SHA256 over all of the 1241 * to-be-signed data, prefixed with the 18-byte UTF-8 encoded string "confirmation token". If 1242 * the computed value does not match the Tag::CONFIRMATION_TOKEN parameter, finish() must not 1243 * produce a signature and must return ErrorCode::NO_USER_CONFIRMATION. 1244 * 1245 * -- RSA keys -- 1246 * 1247 * Some additional requirements, depending on the padding mode: 1248 * 1249 * o PaddingMode::NONE. For unpadded signing and encryption operations, if the provided data is 1250 * shorter than the key, the data must be zero-padded on the left before 1251 * signing/encryption. If the data is the same length as the key, but numerically larger, 1252 * finish() must return ErrorCode::INVALID_ARGUMENT. For verification and decryption 1253 * operations, the data must be exactly as long as the key. Otherwise, return 1254 * ErrorCode::INVALID_INPUT_LENGTH. 1255 * 1256 * o PaddingMode::RSA_PSS. For PSS-padded signature operations, the PSS salt length must match 1257 * the size of the PSS digest selected. The digest specified with Tag::DIGEST in inputParams 1258 * on begin() must be used as the PSS digest algorithm, MGF1 must be used as the mask 1259 * generation function and SHA1 must be used as the MGF1 digest algorithm. 1260 * 1261 * o PaddingMode::RSA_OAEP. The digest specified with Tag::DIGEST in inputParams on begin is 1262 * used as the OAEP digest algorithm, MGF1 must be used as the mask generation function and 1263 * and SHA1 must be used as the MGF1 digest algorithm. 1264 * 1265 * -- ECDSA keys -- 1266 * 1267 * If the data provided for unpadded signing or verification is too long, truncate it. 1268 * 1269 * -- AES keys -- 1270 * 1271 * Some additional conditions, depending on block mode: 1272 * 1273 * o BlockMode::ECB or BlockMode::CBC. If padding is PaddingMode::NONE and the data length is 1274 * not a multiple of the AES block size, finish() must return 1275 * ErrorCode::INVALID_INPUT_LENGTH. If padding is PaddingMode::PKCS7, pad the data per the 1276 * PKCS#7 specification, including adding an additional padding block if the data is a multiple 1277 * of the block length. 1278 * 1279 * o BlockMode::GCM. During encryption, after processing all plaintext, compute the tag 1280 * (Tag::MAC_LENGTH bytes) and append it to the returned ciphertext. During decryption, 1281 * process the last Tag::MAC_LENGTH bytes as the tag. If tag verification fails, finish() 1282 * must return ErrorCode::VERIFICATION_FAILED. 1283 * 1284 * @param operationHandle The operation handle returned by begin(). This handle must be invalid 1285 * when finish() returns. 1286 * 1287 * @param inParams Additional parameters for the operation. For AEAD modes, this is used to 1288 * specify Tag::ADDITIONAL_DATA, but only if no input data was provided to update(). 1289 * 1290 * @param input Data to be processed, per the parameters established in the call to begin(). 1291 * finish() must consume all provided data or return ErrorCode::INVALID_INPUT_LENGTH. 1292 * 1293 * @param signature The signature to be verified if the purpose specified in the begin() call 1294 * was KeyPurpose::VERIFY. 1295 * 1296 * @param authToken Authentication token. Callers that provide no token must set all numeric 1297 * fields to zero and the MAC must be an empty vector. 1298 * 1299 * @param verificationToken Verification token, used to prove that another IKeymasterDevice HAL 1300 * has verified some parameters, and to deliver the other HAL's current timestamp, if 1301 * needed. If not provided, all fields must be initialized to zero and vectors empty. 1302 * 1303 * @return outParams Any output parameters generated by finish(). 1304 * 1305 * @return output The output data, if any. 1306 */ 1307 finish(OperationHandle operationHandle, vec<KeyParameter> inParams, vec<uint8_t> input, 1308 vec<uint8_t> signature, HardwareAuthToken authToken, VerificationToken verificationToken) 1309 generates (ErrorCode error, vec<KeyParameter> outParams, vec<uint8_t> output); 1310 1311 /** 1312 * Aborts a cryptographic operation begun with begin(), freeing all internal resources and 1313 * invalidating operationHandle. 1314 * 1315 * @param operationHandle The operation handle returned by begin(). This handle must be 1316 * invalid when abort() returns. 1317 * 1318 * @return error See the ErrorCode enum in types.hal. 1319 */ 1320 abort(OperationHandle operationHandle) generates (ErrorCode error); 1321 }; 1322
