Shawn Willden | 1e50c67 | 2017-11-10 11:49:02 -0700 | [diff] [blame] | 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. For thorough documentation see the implementer's reference, at |
| 24 | * https://source.android.com/security/keystore/implementer-ref.html |
| 25 | */ |
| 26 | interface IKeymaster { |
| 27 | |
| 28 | /** |
| 29 | * Returns information about the underlying keymaster hardware. |
| 30 | * |
| 31 | * @return isSecure Indicates whether this keymaster implementation is in some sort of secure |
| 32 | * hardware. |
| 33 | * |
| 34 | * @return keymasterName is the name of the keymaster implementation. |
| 35 | * |
| 36 | * @return keymasterAuthorName is the name of the author of the keymaster implementation |
| 37 | * (organization name, not individual). |
| 38 | */ |
| 39 | getHardwareInfo() generates (bool isSecure, string keymasterName, string keymasterAuthorName); |
| 40 | |
| 41 | /** |
| 42 | * Adds entropy to the RNG used by keymaster. Entropy added through this method must not be the |
| 43 | * only source of entropy used. The keymaster implementation must securely mix entropy provided |
| 44 | * through this method with internally-generated entropy. |
| 45 | * |
| 46 | * @param data Bytes to be mixed into the RNG. |
| 47 | * |
| 48 | * @return error See the ErrorCode enum in types.hal. |
| 49 | */ |
| 50 | addRngEntropy(vec<uint8_t> data) generates (ErrorCode error); |
| 51 | |
| 52 | /** |
| 53 | * Generates a key, or key pair, returning a key blob and a description of the key. |
| 54 | * |
| 55 | * @param keyParams Key generation parameters are defined as keymaster tag/value pairs, provided |
| 56 | * in params. See Tag in types.hal for the full list. |
| 57 | * |
| 58 | * @return error See the ErrorCode enum in types.hal. |
| 59 | * |
| 60 | * @return keyBlob Opaque, encrypted descriptor of the generated key. A recommended |
| 61 | * implementation strategy is to include an encrypted copy of the key material, wrapped |
| 62 | * in a key unavailable outside secure hardware. |
| 63 | * |
| 64 | * @return keyCharacteristics Description of the generated key. See KeyCharacteristis in |
| 65 | * types.hal. |
| 66 | */ |
| 67 | generateKey(vec<KeyParameter> keyParams) |
| 68 | generates (ErrorCode error, vec<uint8_t> keyBlob, KeyCharacteristics keyCharacteristics); |
| 69 | |
| 70 | /** |
| 71 | * Imports a key, or key pair, returning a key blob and/or a description of the key. |
| 72 | * |
| 73 | * @param keyParams Key generation parameters are defined as keymaster tag/value pairs, provided |
| 74 | * in params. See Tag for the full list. |
| 75 | * |
| 76 | * @param keyFormat The format of the key material to import. |
| 77 | * |
| 78 | * @pram keyData The key material to import, in the format specifed in keyFormat. |
| 79 | * |
| 80 | * @return error See the ErrorCode enum. |
| 81 | * |
| 82 | * @return keyBlob Opaque, encrypted descriptor of the generated key, which will generally |
| 83 | * contain a copy of the key material, wrapped in a key unavailable outside secure |
| 84 | * hardware. |
| 85 | * |
| 86 | * @return keyCharacteristics Decription of the generated key. |
| 87 | */ |
| 88 | importKey(vec<KeyParameter> keyParams, KeyFormat keyFormat, vec<uint8_t> keyData) |
| 89 | generates (ErrorCode error, vec<uint8_t> keyBlob, KeyCharacteristics keyCharacteristics); |
| 90 | |
| 91 | /** |
| 92 | * Returns the characteristics of the specified key, if the keyBlob is valid (implementations |
| 93 | * must fully validate the integrity of the key). |
| 94 | * |
| 95 | * @param keyBlob The opaque descriptor returned by generateKey() or importKey(); |
| 96 | * |
| 97 | * @param clientId An opaque byte string identifying the client. This value must match the |
| 98 | * Tag::APPLICATION_ID data provided during key generation/import. Without the correct |
| 99 | * value, it must be computationally infeasible for the secure hardware to obtain the key |
| 100 | * material. |
| 101 | * |
| 102 | * @param appData An opaque byte string provided by the application. This value must match the |
| 103 | * Tag::APPLICATION_DATA data provided during key generation/import. Without the correct |
| 104 | * value, it must be computationally infeasible for the secure hardware to obtain the key |
| 105 | * material. |
| 106 | * |
| 107 | * @return error See the ErrorCode enum in types.hal. |
| 108 | * |
| 109 | * @return keyCharacteristics Decription of the generated key. See KeyCharacteristis in |
| 110 | * types.hal. |
| 111 | */ |
| 112 | getKeyCharacteristics(vec<uint8_t> keyBlob, vec<uint8_t> clientId, vec<uint8_t> appData) |
| 113 | generates (ErrorCode error, KeyCharacteristics keyCharacteristics); |
| 114 | |
| 115 | /** |
| 116 | * Exports a public key, returning the key in the specified format. |
| 117 | * |
| 118 | * @parm keyFormat The format used for export. See KeyFormat in types.hal. |
| 119 | * |
| 120 | * @param keyBlob The opaque descriptor returned by generateKey() or importKey(). The |
| 121 | * referenced key must be asymmetric. |
| 122 | * |
| 123 | * @param clientId An opaque byte string identifying the client. This value must match the |
| 124 | * Tag::APPLICATION_ID data provided during key generation/import. Without the correct |
| 125 | * value, it must be computationally infeasible for the secure hardware to obtain the key |
| 126 | * material. |
| 127 | * |
| 128 | * @param appData An opaque byte string provided by the application. This value must match the |
| 129 | * Tag::APPLICATION_DATA data provided during key generation/import. Without the correct |
| 130 | * value, it must be computationally infeasible for the secure hardware to obtain the key |
| 131 | * material. |
| 132 | * |
| 133 | * @return error See the ErrorCode enum in types.hal. |
| 134 | * |
| 135 | * @return keyMaterial The public key material in PKCS#8 format. |
| 136 | */ |
| 137 | exportKey(KeyFormat keyFormat, vec<uint8_t> keyBlob, vec<uint8_t> clientId, |
| 138 | vec<uint8_t> appData) generates (ErrorCode error, vec<uint8_t> keyMaterial); |
| 139 | |
| 140 | /** |
| 141 | * Generates a signed X.509 certificate chain attesting to the presence of keyToAttest in |
| 142 | * keymaster. The certificate must contain an extension with OID 1.3.6.1.4.1.11129.2.1.17 and |
| 143 | * value defined in: |
| 144 | * |
| 145 | * https://developer.android.com/training/articles/security-key-attestation.html. |
| 146 | * |
| 147 | * @param keyToAttest The opaque descriptor returned by generateKey() or importKey(). The |
| 148 | * referenced key must be asymmetric. |
| 149 | * |
| 150 | * @param attestParams Parameters for the attestation, notably Tag::ATTESTATION_CHALLENGE. |
| 151 | * |
| 152 | * @return error See the ErrorCode enum in types.hal. |
| 153 | * |
| 154 | * @return certChain The attestation certificate, and additional certificates back to the root |
| 155 | * attestation certificate, which clients will need to check against a known-good value. |
| 156 | */ |
| 157 | attestKey(vec<uint8_t> keyToAttest, vec<KeyParameter> attestParams) |
| 158 | generates (ErrorCode error, vec<vec<uint8_t>> certChain); |
| 159 | |
| 160 | /** |
| 161 | * Upgrades an old key blob. Keys can become "old" in two ways: Keymaster can be upgraded to a |
| 162 | * new version with an incompatible key blob format, or the system can be updated to invalidate |
| 163 | * the OS version and/or patch level. In either case, attempts to use an old key blob with |
| 164 | * getKeyCharacteristics(), exportKey(), attestKey() or begin() must result in keymaster |
| 165 | * returning ErrorCode::KEY_REQUIRES_UPGRADE. The caller must use this method to upgrade the |
| 166 | * key blob. |
| 167 | * |
| 168 | * @param keyBlobToUpgrade The opaque descriptor returned by generateKey() or importKey(); |
| 169 | * |
| 170 | * @param upgradeParams A parameter list containing any parameters needed to complete the |
| 171 | * upgrade, including Tag::APPLICATION_ID and Tag::APPLICATION_DATA. |
| 172 | * |
| 173 | * @return error See the ErrorCode enum. |
| 174 | * |
| 175 | * @return upgradedKeyBlob A new key blob that references the same key as keyBlobToUpgrade, but |
| 176 | * is in the new format, or has the new version data. |
| 177 | */ |
| 178 | upgradeKey(vec<uint8_t> keyBlobToUpgrade, vec<KeyParameter> upgradeParams) |
| 179 | generates (ErrorCode error, vec<uint8_t> upgradedKeyBlob); |
| 180 | |
| 181 | /** |
| 182 | * Deletes the key, or key pair, associated with the key blob. Calling this function on a key |
| 183 | * with Tag::ROLLBACK_RESISTANCE in its hardware-enforced authorization list must render the key |
| 184 | * permanently unusable. Keys without Tag::ROLLBACK_RESISTANCE may or may not be rendered |
| 185 | * unusable. |
| 186 | * |
| 187 | * @param keyBlob The opaque descriptor returned by generateKey() or importKey(); |
| 188 | * |
| 189 | * @return error See the ErrorCode enum. |
| 190 | */ |
| 191 | deleteKey(vec<uint8_t> keyBlob) generates (ErrorCode error); |
| 192 | |
| 193 | /** |
| 194 | * Deletes all keys in the hardware keystore. Used when keystore is reset completely. After |
| 195 | * this function is called all keys with Tag::ROLLBACK_RESISTANCE in their hardware-enforced |
| 196 | * authorization lists must be rendered permanently unusable. Keys without |
| 197 | * Tag::ROLLBACK_RESISTANCE may or may not be rendered unusable. |
| 198 | * |
| 199 | * @return error See the ErrorCode enum. |
| 200 | */ |
| 201 | deleteAllKeys() generates (ErrorCode error); |
| 202 | |
| 203 | /** |
| 204 | * Destroys knowledge of the device's ids. This prevents all device id attestation in the |
| 205 | * future. The destruction must be permanent so that not even a factory reset will restore the |
| 206 | * device ids. |
| 207 | * |
| 208 | * Device id attestation may be provided only if this method is fully implemented, allowing the |
| 209 | * user to permanently disable device id attestation. If this cannot be guaranteed, the device |
| 210 | * must never attest any device ids. |
| 211 | * |
| 212 | * This is a NOP if device id attestation is not supported. |
| 213 | * |
| 214 | * @return error See the ErrorCode enum. |
| 215 | */ |
| 216 | destroyAttestationIds() generates (ErrorCode error); |
| 217 | |
| 218 | /** |
| 219 | * Begins a cryptographic operation using the specified key. If all is well, begin() must |
| 220 | * return ErrorCode::OK and create an operation handle which must be passed to subsequent calls |
| 221 | * to update(), finish() or abort(). |
| 222 | * |
| 223 | * It is critical that each call to begin() be paired with a subsequent call to finish() or |
| 224 | * abort(), to allow the keymaster implementation to clean up any internal operation state. The |
| 225 | * caller's failure to do this may leak internal state space or other internal resources and may |
| 226 | * eventually cause begin() to return ErrorCode::TOO_MANY_OPERATIONS when it runs out of space |
| 227 | * for operations. Any result other than ErrorCode::OK from begin(), update() or finish() |
| 228 | * implicitly aborts the operation, in which case abort() need not be called (and must return |
| 229 | * ErrorCode::INVALID_OPERATION_HANDLE if called). |
| 230 | * |
| 231 | * @param purpose The purpose of the operation, one of KeyPurpose::ENCRYPT, KeyPurpose::DECRYPT, |
| 232 | * KeyPurpose::SIGN or KeyPurpose::VERIFY. Note that for AEAD modes, encryption and |
| 233 | * decryption imply signing and verification, respectively, but must be specified as |
| 234 | * KeyPurpose::ENCRYPT and KeyPurpose::DECRYPT. |
| 235 | * |
| 236 | * @param keyBlob The opaque key descriptor returned by generateKey() or importKey(). The key |
| 237 | * must have a purpose compatible with purpose and all of its usage requirements must be |
| 238 | * satisfied, or begin() must return an appropriate error code. |
| 239 | * |
| 240 | * @param inParams Additional parameters for the operation. If Tag::APPLICATION_ID or |
| 241 | * Tag::APPLICATION_DATA were provided during generation, they must be provided here, or |
| 242 | * the operation must fail with ErrorCode::INVALID_KEY_BLOB. For operations that require |
| 243 | * a nonce or IV, on keys that were generated with Tag::CALLER_NONCE, inParams may |
| 244 | * contain a tag Tag::NONCE. If Tag::NONCE is provided for a key without |
| 245 | * Tag:CALLER_NONCE, ErrorCode::CALLER_NONCE_PROHIBITED must be returned. |
| 246 | * |
| 247 | * @param authToken Authentication token. Callers that provide no token must set all numeric |
| 248 | * fields to zero and the MAC must be an empty vector. |
| 249 | * |
| 250 | * @return error See the ErrorCode enum in types.hal. |
| 251 | * |
| 252 | * @return outParams Output parameters. Used to return additional data from the operation |
| 253 | * initialization, notably to return the IV or nonce from operations that generate an IV |
| 254 | * or nonce. |
| 255 | * |
| 256 | * @return operationHandle The newly-created operation handle which must be passed to update(), |
| 257 | * finish() or abort(). |
| 258 | */ |
| 259 | begin(KeyPurpose purpose, vec<uint8_t> keyBlob, vec<KeyParameter> inParams, |
| 260 | HardwareAuthToken authToken) |
| 261 | generates (ErrorCode error, vec<KeyParameter> outParams, OperationHandle operationHandle); |
| 262 | |
| 263 | /** |
| 264 | * Provides data to, and possibly receives output from, an ongoing cryptographic operation begun |
| 265 | * with begin(). |
| 266 | * |
| 267 | * If operationHandle is invalid, update() must return ErrorCode::INVALID_OPERATION_HANDLE. |
| 268 | * |
| 269 | * update() may not consume all of the data provided in the data buffer. update() must return |
| 270 | * the amount consumed in inputConsumed. The caller may provide the unconsumed data in a |
| 271 | * subsequent call. |
| 272 | * |
| 273 | * @param operationHandle The operation handle returned by begin(). |
| 274 | * |
| 275 | * @param inParams Additional parameters for the operation. For AEAD modes, this is used to |
| 276 | * specify Tag::ADDITIONAL_DATA. Note that additional data may be provided in multiple |
| 277 | * calls to update(), but only until input data has been provided. |
| 278 | * |
| 279 | * @param input Data to be processed. Note that update() may or may not consume all of the data |
| 280 | * provided. See inputConsumed. |
| 281 | * |
| 282 | * @param authToken Authentication token. Callers that provide no token must set all numeric |
| 283 | * fields to zero and the MAC must be an empty vector. |
| 284 | * |
| 285 | * @return error See the ErrorCode enum in types.hal. |
| 286 | * |
| 287 | * @return inputConsumed Amount of data that was consumed by update(). If this is less than the |
| 288 | * amount provided, the caller may provide the remainder in a subsequent call to |
| 289 | * update() or finish(). Every call to update must consume at least one byte, and |
| 290 | * implementations should consume as much data as reasonably possible for each call. |
| 291 | * |
| 292 | * @return outParams Output parameters, used to return additional data from the operation. |
| 293 | * |
| 294 | * @return output The output data, if any. |
| 295 | */ |
| 296 | update(OperationHandle operationHandle, vec<KeyParameter> inParams, vec<uint8_t> input, |
| 297 | HardwareAuthToken authToken) |
| 298 | generates (ErrorCode error, uint32_t inputConsumed, vec<KeyParameter> outParams, |
| 299 | vec<uint8_t> output); |
| 300 | |
| 301 | /** |
| 302 | * Finalizes a cryptographic operation begun with begin() and invalidates operationHandle. |
| 303 | * |
| 304 | * @param operationHandle The operation handle returned by begin(). This handle must be invalid |
| 305 | * when finish() returns. |
| 306 | * |
| 307 | * @param inParams Additional parameters for the operation. For AEAD modes, this is used to |
| 308 | * specify Tag::ADDITIONAL_DATA, but only if no input data was provided to update(). |
| 309 | * |
| 310 | * @param input Data to be processed, per the parameters established in the call to begin(). |
| 311 | * finish() must consume all provided data or return ErrorCode::INVALID_INPUT_LENGTH. |
| 312 | * |
| 313 | * @param signature The signature to be verified if the purpose specified in the begin() call |
| 314 | * was KeyPurpose::VERIFY. |
| 315 | * |
| 316 | * @param authToken Authentication token. Callers that provide no token must set all numeric |
| 317 | * fields to zero and the MAC must be an empty vector. |
| 318 | * |
| 319 | * @return error See the ErrorCode enum in types.hal. |
| 320 | * |
| 321 | * @return outParams Any output parameters generated by finish(). |
| 322 | * |
| 323 | * @return output The output data, if any. |
| 324 | */ |
| 325 | finish(OperationHandle operationHandle, vec<KeyParameter> inParams, vec<uint8_t> input, |
| 326 | vec<uint8_t> signature, HardwareAuthToken authToken) |
| 327 | generates (ErrorCode error, vec<KeyParameter> outParams, vec<uint8_t> output); |
| 328 | |
| 329 | /** |
| 330 | * Aborts a cryptographic operation begun with begin(), freeing all internal resources and |
| 331 | * invalidating operationHandle. |
| 332 | * |
| 333 | * @param operationHandle The operation handle returned by begin(). This handle must be |
| 334 | * invalid when abort() returns. |
| 335 | * |
| 336 | * @return error See the ErrorCode enum in types.hal. |
| 337 | */ |
| 338 | abort(OperationHandle operationHandle) generates (ErrorCode error); |
| 339 | }; |