blob: b841832b7a48da2d3548f7eaf2e324f98708d3a5 [file] [log] [blame]
Shawn Willden1e50c672017-11-10 11:49:02 -07001/*
2 * Copyright (C) 2017 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.hardware.keymaster@4.0;
18
19import android.hardware.keymaster@3.0::ErrorCode;
20import 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 */
26interface 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};