1 /* 2 * Copyright (C) 2016 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.hardware.keymaster@3.0; 18 19 /** 20 * Keymaster device definition. For thorough documentation see the implementer's reference, at 21 * https://source.android.com/security/keystore/implementer-ref.html 22 */ 23 interface IKeymasterDevice { 24 25 /** 26 * Returns information about the underlying keymaster hardware. 27 * 28 * @return isSecure is true if keys are stored and never leave secure hardware (Trusted 29 * Execution Environment or similar). CDD requires that all devices initially 30 * launched with Marshmallow or later must have secure hardware. 31 * 32 * @return supportsEllipticCurve is true if the hardware supports Elliptic Curve cryptography 33 * with the NIST curves (P-224, P-256, P-384, and P-521). CDD requires that all 34 * devices initially launched with Nougat or later must support Elliptic Curve 35 * cryptography. 36 * 37 * @return supportsSymmetricCryptography is true if the hardware supports symmetric 38 * cryptography, including AES and HMAC. CDD requires that all devices initially 39 * launched with Nougat or later must support hardware enforcement of Keymaster 40 * authorizations. 41 * 42 * @return supportsAttestation is true if the hardware supports generation of Keymaster public 43 * key attestation certificates, signed with a key injected in a secure 44 * environment. CDD requires that all devices initially launched with Android O or 45 * later must support hardware attestation. 46 * 47 * @return supportsAllDigests is true if the hardware supports all keymaster digest functions, 48 * namely ND-5, SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512. CDD requires that all 49 * devices launched initially with Android O or later must support all digests. 50 * 51 * @return keymasterName is the name of the keymaster implementation. 52 * 53 * @return keymasterAuthorName is the name of the author of the keymaster implementation 54 * (generally this should be the name of an organization, not an individual.) 55 */ 56 getHardwareFeatures() 57 generates(bool isSecure, bool supportsEllipticCurve, bool supportsSymmetricCryptography, 58 bool supportsAttestation, bool supportsAllDigests, string keymasterName, 59 string keymasterAuthorName); 60 61 /** 62 * Adds entropy to the RNG used by keymaster. Entropy added through this method is guaranteed 63 * not to be the only source of entropy used, and the mixing function is required to be secure, 64 * in the sense that if the RNG is seeded (from any source) with any data the attacker cannot 65 * predict (or control), then the RNG output is indistinguishable from random. Thus, if the 66 * entropy from any source is good, the output must be good. 67 * 68 * @param data Bytes to be mixed into the RNG. 69 * 70 * @return error See the ErrorCode enum in types.hal. 71 */ 72 addRngEntropy(vec<uint8_t> data) generates(ErrorCode error); 73 74 /** 75 * Generates a key, or key pair, returning a key blob and/or a description of the key. 76 * 77 * @param keyParams Key generation parameters are defined as keymaster tag/value pairs, provided 78 * in params. See Tag in types.hal for the full list. 79 * 80 * @return error See the ErrorCode enum in types.hal. 81 * 82 * @return keyBlob Opaque, encrypted descriptor of the generated key, which generally contains a 83 * copy of the key material, wrapped in a key unavailable outside secure hardware. 84 * 85 * @return keyCharacteristics Description of the generated key. See KeyCharacteristis in 86 * types.hal. 87 */ 88 generateKey(vec<KeyParameter> keyParams) 89 generates(ErrorCode error, vec<uint8_t> keyBlob, KeyCharacteristics keyCharacteristics); 90 91 /** 92 * Imports a key, or key pair, returning a key blob and/or a description of the key. 93 * 94 * @param keyParams Key generation parameters are defined as keymaster tag/value pairs, provided 95 * in params. See Tag for the full list. 96 * 97 * @param keyFormat The format of the key material to import. See KeyFormat in types.hal. 98 * 99 * @pram keyData The key material to import, in the format specifed in keyFormat. 100 * 101 * @return error See the ErrorCode enum. 102 * 103 * @return keyBlob Opaque, encrypted descriptor of the generated key, which will generally 104 * contain a copy of the key material, wrapped in a key unavailable outside secure 105 * hardware. 106 * 107 * @return keyCharacteristics Decription of the generated key. See KeyCharacteristis. 108 * 109 * @return error See the ErrorCode enum. 110 */ 111 importKey(vec<KeyParameter> params, KeyFormat keyFormat, vec<uint8_t> keyData) 112 generates(ErrorCode error, vec<uint8_t> keyBlob, KeyCharacteristics keyCharacteristics); 113 114 /** 115 * Returns the characteristics of the specified key, if the keyBlob is valid (implementations 116 * must fully validate the integrity of the key). 117 * 118 * @param keyBlob The opaque descriptor returned by generateKey() or importKey(); 119 * 120 * @param clientId An opaque byte string identifying the client. This value must match the 121 * Tag::APPLICATION_ID data provided during key generation/import. Without the 122 * correct value it must be cryptographically impossible for the secure hardware to 123 * obtain the key material. 124 * 125 * @param appData An opaque byte string provided by the application. This value must match the 126 * Tag::APPLICATION_DATA data provided during key generation/import. Without the 127 * correct value it must be cryptographically impossible for the secure hardware to 128 * obtain the key material. 129 * 130 * @return error See the ErrorCode enum in types.hal. 131 * 132 * @return keyCharacteristics Decription of the generated key. See KeyCharacteristis in 133 * types.hal. 134 */ 135 getKeyCharacteristics(vec<uint8_t> keyBlob, vec<uint8_t> clientId, vec<uint8_t> appData) 136 generates(ErrorCode error, KeyCharacteristics keyCharacteristics); 137 138 /** 139 * Exports a public key, returning the key in the specified format. 140 * 141 * @parm keyFormat The format used for export. See KeyFormat in types.hal. 142 * 143 * @param keyBlob The opaque descriptor returned by generateKey() or importKey(). The 144 * referenced key must be asymmetric. 145 * 146 * @param clientId An opaque byte string identifying the client. This value must match the 147 * Tag::APPLICATION_ID data provided during key generation/import. Without the 148 * correct value it must be cryptographically impossible for the secure hardware to 149 * obtain the key material. 150 * 151 * @param appData An opaque byte string provided by the application. This value must match the 152 * Tag::APPLICATION_DATA data provided during key generation/import. Without the 153 * correct value it must be cryptographically impossible for the secure hardware to 154 * obtain the key material. 155 * 156 * @return error See the ErrorCode enum in types.hal. 157 * 158 * @return keyMaterial The public key material in PKCS#8 format. 159 */ 160 exportKey(KeyFormat keyFormat, vec<uint8_t> keyBlob, vec<uint8_t> clientId, 161 vec<uint8_t> appData) generates(ErrorCode error, vec<uint8_t> keyMaterial); 162 163 /** 164 * Generates a signed X.509 certificate chain attesting to the presence of keyToAttest in 165 * keymaster. The certificate will contain an extension with OID 1.3.6.1.4.1.11129.2.1.17 and 166 * value defined in: 167 * 168 * https://developer.android.com/training/articles/security-key-attestation.html. 169 * 170 * @param keyToAttest The opaque descriptor returned by generateKey() or importKey(). The 171 * referenced key must be asymmetric. 172 * 173 * @param attestParams Parameters for the attestation, notably Tag::ATTESTATION_CHALLENGE. 174 * 175 * @return error See the ErrorCode enum in types.hal. 176 */ 177 attestKey(vec<uint8_t> keyToAttest, vec<KeyParameter> attestParams) 178 generates(ErrorCode error, vec<vec<uint8_t>> certChain); 179 180 /** 181 * Upgrades an old key. Keys can become "old" in two ways: Keymaster can be upgraded to a new 182 * version, or the system can be updated to invalidate the OS version and/or patch level. In 183 * either case, attempts to use an old key with getKeyCharacteristics(), exportKey(), 184 * attestKey() or begin() will result in keymaster returning 185 * ErrorCode::KEY_REQUIRES_UPGRADE. This method must then be called to upgrade the key. 186 * 187 * @param keyBlobToUpgrade The opaque descriptor returned by generateKey() or importKey(); 188 * 189 * @param upgradeParams A parameter list containing any parameters needed to complete the 190 * upgrade, including Tag::APPLICATION_ID and Tag::APPLICATION_DATA. 191 * 192 * @return error See the ErrorCode enum. 193 */ 194 upgradeKey(vec<uint8_t> keyBlobToUpgrade, vec<KeyParameter> upgradeParams) 195 generates(ErrorCode error, vec<uint8_t> upgradedKeyBlob); 196 197 /** 198 * Deletes the key, or key pair, associated with the key blob. After calling this function it 199 * will be impossible to use the key for any other operations. May be applied to keys from 200 * foreign roots of trust (keys not usable under the current root of trust). 201 * 202 * This is a NOP for keys that don't have rollback protection. 203 * 204 * @param keyBlobToUpgrade The opaque descriptor returned by generateKey() or importKey(); 205 * 206 * @return error See the ErrorCode enum. 207 */ 208 deleteKey(vec<uint8_t> keyBlob) generates(ErrorCode error); 209 210 /** 211 * Deletes all keys in the hardware keystore. Used when keystore is reset completely. After 212 * calling this function it will be impossible to use any previously generated or imported key 213 * blobs for any operations. 214 * 215 * This is a NOP if keys don't have rollback protection. 216 * 217 * @return error See the ErrorCode enum. 218 */ 219 deleteAllKeys() generates(ErrorCode error); 220 221 /** 222 * Destroys knowledge of the device's ids. This prevents all device id attestation in the 223 * future. The destruction must be permanent so that not even a factory reset will restore the 224 * device ids. 225 * 226 * Device id attestation may be provided only if this method is fully implemented, allowing the 227 * user to permanently disable device id attestation. If this cannot be guaranteed, the device 228 * must never attest any device ids. 229 * 230 * This is a NOP if device id attestation is not supported. 231 * 232 * @return error See the ErrorCode enum. 233 */ 234 destroyAttestationIds() generates(ErrorCode error); 235 236 /** 237 * Begins a cryptographic operation using the specified key. If all is well, begin() will return 238 * ErrorCode::OK and create an operation handle which must be passed to subsequent calls to 239 * update(), finish() or abort(). 240 * 241 * It is critical that each call to begin() be paired with a subsequent call to finish() or 242 * abort(), to allow the keymaster implementation to clean up any internal operation state. 243 * Failure to do this may leak internal state space or other internal resources and may 244 * eventually cause begin() to return ErrorCode::TOO_MANY_OPERATIONS when it runs out of space 245 * for operations. Any result other than ErrorCode::OK from begin(), update() or finish() 246 * implicitly aborts the operation, in which case abort() need not be called (and will return 247 * ErrorCode::INVALID_OPERATION_HANDLE if called). 248 * 249 * @param purpose The purpose of the operation, one of KeyPurpose::ENCRYPT, KeyPurpose::DECRYPT, 250 * KeyPurpose::SIGN or KeyPurpose::VERIFY. Note that for AEAD modes, encryption and 251 * decryption imply signing and verification, respectively, but must be specified as 252 * KeyPurpose::ENCRYPT and KeyPurpose::DECRYPT. 253 * 254 * @param keyBlob The opaque key descriptor returned by generateKey() or importKey(). The key 255 * must have a purpose compatible with purpose and all of its usage requirements 256 * must be satisfied, or begin() will return an appropriate error code. 257 * 258 * @param inParams Additional parameters for the operation. This is typically used to provide 259 * authentication data, with Tag::AUTH_TOKEN. If Tag::APPLICATION_ID or 260 * Tag::APPLICATION_DATA were provided during generation, they must be provided 261 * here, or the operation will fail with ErrorCode::INVALID_KEY_BLOB. For operations 262 * that require a nonce or IV, on keys that were generated with Tag::CALLER_NONCE, 263 * inParams may contain a tag Tag::NONCE. 264 * 265 * @return error See the ErrorCode enum in types.hal. 266 * 267 * @return outParams Output parameters. Used to return additional data from the operation 268 * initialization, notably to return the IV or nonce from operations that generate 269 * an IV or nonce. 270 * 271 * @return operationHandle The newly-created operation handle which must be passed to update(), 272 * finish() or abort(). 273 */ 274 begin(KeyPurpose purpose, vec<uint8_t> key, vec<KeyParameter> inParams) 275 generates(ErrorCode error, vec<KeyParameter> outParams, OperationHandle operationHandle); 276 277 /** 278 * Provides data to, and possibly receives output from, an ongoing cryptographic operation begun 279 * with begin(). 280 * 281 * If operationHandle is invalid, update() will return ErrorCode::INVALID_OPERATION_HANDLE. 282 * 283 * update() may not consume all of the data provided in the data buffer. update() will return 284 * the amount consumed in inputConsumed. The caller may provide the unconsumed data in a 285 * subsequent call. 286 * 287 * @param operationHandle The operation handle returned by begin(). 288 * 289 * @param inParams Additional parameters for the operation. For AEAD modes, this is used to 290 * specify Tag::ADDITIONAL_DATA. Note that additional data may be provided in 291 * multiple calls to update(), but only until input data has been provided. 292 * 293 * @param input Data to be processed, per the parameters established in the call to begin(). 294 * Note that update() may or may not consume all of the data provided. See 295 * inputConsumed. 296 * 297 * @return error See the ErrorCode enum in types.hal. 298 * 299 * @return inputConsumed Amount of data that was consumed by update(). If this is less than the 300 * amount provided, the caller may provide the remainder in a subsequent call to 301 * update() or finish(). 302 * 303 * @return outParams Output parameters, used to return additional data from the operation The 304 * caller takes ownership of the output parameters array and must free it with 305 * keymaster_free_param_set(). 306 * 307 * @return output The output data, if any. 308 */ 309 update(OperationHandle operationHandle, vec<KeyParameter> inParams, vec<uint8_t> input) 310 generates(ErrorCode error, uint32_t inputConsumed, vec<KeyParameter> outParams, 311 vec<uint8_t> output); 312 313 /** 314 * Finalizes a cryptographic operation begun with begin() and invalidates operationHandle. 315 * 316 * @param operationHandle The operation handle returned by begin(). This handle will be 317 * invalid when finish() returns. 318 * 319 * @param inParams Additional parameters for the operation. For AEAD modes, this is used to 320 * specify Tag::ADDITIONAL_DATA, but only if no input data was provided to update(). 321 * 322 * @param input Data to be processed, per the parameters established in the call to 323 * begin(). finish() must consume all provided data or return 324 * ErrorCode::INVALID_INPUT_LENGTH. 325 * 326 * @param signature The signature to be verified if the purpose specified in the begin() call 327 * was KeyPurpose::VERIFY. 328 * 329 * @return error See the ErrorCode enum in types.hal. 330 * 331 * @return outParams Any output parameters generated by finish(). 332 * 333 * @return output The output data, if any. 334 */ 335 finish(OperationHandle operationHandle, vec<KeyParameter> inParams, vec<uint8_t> input, 336 vec<uint8_t> signature) 337 generates(ErrorCode error, vec<KeyParameter> outParams, vec<uint8_t> output); 338 339 /** 340 * Aborts a cryptographic operation begun with begin(), freeing all internal resources and 341 * invalidating operationHandle. 342 * 343 * @param operationHandle The operation handle returned by begin(). This handle will be 344 * invalid when abort() returns. 345 * 346 * @return error See the ErrorCode enum in types.hal. 347 */ 348 abort(OperationHandle operationHandle) generates(ErrorCode error); 349 }; 350
