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