diff options
author | Janis Danisevskis | 2016-10-12 05:23:58 -0500 |
---|---|---|
committer | Shawn Willden | 2016-12-20 10:09:29 -0600 |
commit | 34d8809c7e61416820de2acb21b70ca914f6e622 (patch) | |
tree | a17d50f25454b83e743a9c143fe2216edc5c5da7 | |
parent | cd6300e95796c0ee8353561a05c0491bfc46ec1f (diff) | |
download | platform-hardware-interfaces-34d8809c7e61416820de2acb21b70ca914f6e622.tar.gz platform-hardware-interfaces-34d8809c7e61416820de2acb21b70ca914f6e622.tar.xz platform-hardware-interfaces-34d8809c7e61416820de2acb21b70ca914f6e622.zip |
Add interface definition for binderized Keymaster HAL
Test: accepted by hidl-gen
Bug: 32020919,32962548
Change-Id: Ib0decb231527e944e6b673017b721ea4601b7b2a
-rw-r--r-- | keymaster/3.0/Android.bp | 56 | ||||
-rw-r--r-- | keymaster/3.0/IKeymasterDevice.hal | 324 | ||||
-rw-r--r-- | keymaster/3.0/types.hal | 414 | ||||
-rw-r--r-- | keymaster/Android.bp | 4 |
4 files changed, 798 insertions, 0 deletions
diff --git a/keymaster/3.0/Android.bp b/keymaster/3.0/Android.bp new file mode 100644 index 00000000..3c2034b8 --- /dev/null +++ b/keymaster/3.0/Android.bp | |||
@@ -0,0 +1,56 @@ | |||
1 | // This file is autogenerated by hidl-gen. Do not edit manually. | ||
2 | |||
3 | genrule { | ||
4 | name: "android.hardware.keymaster@3.0_genc++", | ||
5 | tools: ["hidl-gen"], | ||
6 | cmd: "$(location hidl-gen) -o $(genDir) -Lc++ -randroid.hardware:hardware/interfaces -randroid.hidl:system/libhidl/transport android.hardware.keymaster@3.0", | ||
7 | srcs: [ | ||
8 | "types.hal", | ||
9 | "IKeymasterDevice.hal", | ||
10 | ], | ||
11 | out: [ | ||
12 | "android/hardware/keymaster/3.0/types.cpp", | ||
13 | "android/hardware/keymaster/3.0/KeymasterDeviceAll.cpp", | ||
14 | ], | ||
15 | } | ||
16 | |||
17 | genrule { | ||
18 | name: "android.hardware.keymaster@3.0_genc++_headers", | ||
19 | tools: ["hidl-gen"], | ||
20 | cmd: "$(location hidl-gen) -o $(genDir) -Lc++ -randroid.hardware:hardware/interfaces -randroid.hidl:system/libhidl/transport android.hardware.keymaster@3.0", | ||
21 | srcs: [ | ||
22 | "types.hal", | ||
23 | "IKeymasterDevice.hal", | ||
24 | ], | ||
25 | out: [ | ||
26 | "android/hardware/keymaster/3.0/types.h", | ||
27 | "android/hardware/keymaster/3.0/IKeymasterDevice.h", | ||
28 | "android/hardware/keymaster/3.0/IHwKeymasterDevice.h", | ||
29 | "android/hardware/keymaster/3.0/BnKeymasterDevice.h", | ||
30 | "android/hardware/keymaster/3.0/BpKeymasterDevice.h", | ||
31 | "android/hardware/keymaster/3.0/BsKeymasterDevice.h", | ||
32 | ], | ||
33 | } | ||
34 | |||
35 | cc_library_shared { | ||
36 | name: "android.hardware.keymaster@3.0", | ||
37 | generated_sources: ["android.hardware.keymaster@3.0_genc++"], | ||
38 | generated_headers: ["android.hardware.keymaster@3.0_genc++_headers"], | ||
39 | export_generated_headers: ["android.hardware.keymaster@3.0_genc++_headers"], | ||
40 | shared_libs: [ | ||
41 | "libhidlbase", | ||
42 | "libhidltransport", | ||
43 | "libhwbinder", | ||
44 | "liblog", | ||
45 | "libutils", | ||
46 | "libcutils", | ||
47 | "android.hidl.base@1.0", | ||
48 | ], | ||
49 | export_shared_lib_headers: [ | ||
50 | "libhidlbase", | ||
51 | "libhidltransport", | ||
52 | "libhwbinder", | ||
53 | "libutils", | ||
54 | "android.hidl.base@1.0", | ||
55 | ], | ||
56 | } | ||
diff --git a/keymaster/3.0/IKeymasterDevice.hal b/keymaster/3.0/IKeymasterDevice.hal new file mode 100644 index 00000000..19669c8a --- /dev/null +++ b/keymaster/3.0/IKeymasterDevice.hal | |||
@@ -0,0 +1,324 @@ | |||
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 | getHardwareFeatures() | ||
48 | generates(bool isSecure, bool supportsEllipticCurve, | ||
49 | bool supportsSymmetricCryptography, bool supportsAttestation); | ||
50 | |||
51 | /** | ||
52 | * Adds entropy to the RNG used by keymaster. Entropy added through this method is guaranteed | ||
53 | * not to be the only source of entropy used, and the mixing function is required to be secure, | ||
54 | * in the sense that if the RNG is seeded (from any source) with any data the attacker cannot | ||
55 | * predict (or control), then the RNG output is indistinguishable from random. Thus, if the | ||
56 | * entropy from any source is good, the output must be good. | ||
57 | * | ||
58 | * @param data Bytes to be mixed into the RNG. | ||
59 | * | ||
60 | * @return error See the ErrorCode enum in types.hal. | ||
61 | */ | ||
62 | addRngEntropy(vec<uint8_t> data) generates(ErrorCode error); | ||
63 | |||
64 | /** | ||
65 | * Generates a key, or key pair, returning a key blob and/or a description of the key. | ||
66 | * | ||
67 | * @param keyParams Key generation parameters are defined as keymaster tag/value pairs, provided | ||
68 | * in params. See Tag in types.hal for the full list. | ||
69 | * | ||
70 | * @return error See the ErrorCode enum in types.hal. | ||
71 | * | ||
72 | * @return keyBlob Opaque, encrypted descriptor of the generated key, which generally contains a | ||
73 | * copy of the key material, wrapped in a key unavailable outside secure hardware. | ||
74 | * | ||
75 | * @return keyCharacteristics Description of the generated key. See KeyCharacteristis in | ||
76 | * types.hal. | ||
77 | */ | ||
78 | generateKey(vec<KeyParameter> keyParams) | ||
79 | generates(ErrorCode error, vec<uint8_t> keyBlob, KeyCharacteristics keyCharacteristics); | ||
80 | |||
81 | /** | ||
82 | * Imports a key, or key pair, returning a key blob and/or a description of the key. | ||
83 | * | ||
84 | * @param keyParams Key generation parameters are defined as keymaster tag/value pairs, provided | ||
85 | * in params. See Tag for the full list. | ||
86 | * | ||
87 | * @param keyFormat The format of the key material to import. See KeyFormat in types.hal. | ||
88 | * | ||
89 | * @pram keyData The key material to import, in the format specifed in keyFormat. | ||
90 | * | ||
91 | * @return error See the ErrorCode enum. | ||
92 | * | ||
93 | * @return keyBlob Opaque, encrypted descriptor of the generated key, which will generally | ||
94 | * contain a copy of the key material, wrapped in a key unavailable outside secure | ||
95 | * hardware. | ||
96 | * | ||
97 | * @return keyCharacteristics Decription of the generated key. See KeyCharacteristis. | ||
98 | * | ||
99 | * @return error See the ErrorCode enum. | ||
100 | */ | ||
101 | importKey(vec<KeyParameter> params, KeyFormat keyFormat, vec<uint8_t> keyData) | ||
102 | generates(ErrorCode error, vec<uint8_t> keyBlob, KeyCharacteristics keyCharacteristics); | ||
103 | |||
104 | /** | ||
105 | * Returns the characteristics of the specified key, if the keyBlob is valid (implementations | ||
106 | * must fully validate the integrity of the key). | ||
107 | * | ||
108 | * @param keyBlob The opaque descriptor returned by generateKey() or importKey(); | ||
109 | * | ||
110 | * @param clientId An opaque byte string identifying the client. This value must match the | ||
111 | * Tag::APPLICATION_ID data provided during key generation/import. Without the | ||
112 | * correct value it must be cryptographically impossible for the secure hardware to | ||
113 | * obtain the key material. | ||
114 | * | ||
115 | * @param appData An opaque byte string provided by the application. This value must match the | ||
116 | * Tag::APPLICATION_DATA data provided during key generation/import. Without the | ||
117 | * correct value it must be cryptographically impossible for the secure hardware to | ||
118 | * obtain the key material. | ||
119 | * | ||
120 | * @return error See the ErrorCode enum in types.hal. | ||
121 | * | ||
122 | * @return keyCharacteristics Decription of the generated key. See KeyCharacteristis in | ||
123 | * types.hal. | ||
124 | */ | ||
125 | getKeyCharacteristics(vec<uint8_t> keyBlob, vec<uint8_t> clientId, vec<uint8_t> appData) | ||
126 | generates(ErrorCode error, KeyCharacteristics keyCharacteristics); | ||
127 | |||
128 | /** | ||
129 | * Exports a public key, returning the key in the specified format. | ||
130 | * | ||
131 | * @parm keyFormat The format used for export. See KeyFormat in types.hal. | ||
132 | * | ||
133 | * @param keyBlob The opaque descriptor returned by generateKey() or importKey(). The | ||
134 | * referenced key must be asymmetric. | ||
135 | * | ||
136 | * @param clientId An opaque byte string identifying the client. This value must match the | ||
137 | * Tag::APPLICATION_ID data provided during key generation/import. Without the | ||
138 | * correct value it must be cryptographically impossible for the secure hardware to | ||
139 | * obtain the key material. | ||
140 | * | ||
141 | * @param appData An opaque byte string provided by the application. This value must match the | ||
142 | * Tag::APPLICATION_DATA data provided during key generation/import. Without the | ||
143 | * correct value it must be cryptographically impossible for the secure hardware to | ||
144 | * obtain the key material. | ||
145 | * | ||
146 | * @return error See the ErrorCode enum in types.hal. | ||
147 | * | ||
148 | * @return keyMaterial The public key material in PKCS#8 format. | ||
149 | */ | ||
150 | exportKey(KeyFormat keyFormat, vec<uint8_t> keyBlob, vec<uint8_t> clientId, | ||
151 | vec<uint8_t> appData) generates(ErrorCode error, vec<uint8_t> keyMaterial); | ||
152 | |||
153 | /** | ||
154 | * Generates a signed X.509 certificate chain attesting to the presence of keyToAttest in | ||
155 | * keymaster. The certificate will contain an extension with OID 1.3.6.1.4.1.11129.2.1.17 and | ||
156 | * value defined in: | ||
157 | * | ||
158 | * https://developer.android.com/training/articles/security-key-attestation.html. | ||
159 | * | ||
160 | * @param keyToAttest The opaque descriptor returned by generateKey() or importKey(). The | ||
161 | * referenced key must be asymmetric. | ||
162 | * | ||
163 | * @param attestParams Parameters for the attestation, notably Tag::ATTESTATION_CHALLENGE. | ||
164 | * | ||
165 | * @return error See the ErrorCode enum in types.hal. | ||
166 | */ | ||
167 | attestKey(vec<uint8_t> keyToAttest, vec<KeyParameter> attestParams) | ||
168 | generates(ErrorCode error, vec<vec<uint8_t>> certChain); | ||
169 | |||
170 | /** | ||
171 | * Upgrades an old key. Keys can become "old" in two ways: Keymaster can be upgraded to a new | ||
172 | * version, or the system can be updated to invalidate the OS version and/or patch level. In | ||
173 | * either case, attempts to use an old key with getKeyCharacteristics(), exportKey(), | ||
174 | * attestKey() or begin() will result in keymaster returning | ||
175 | * ErrorCode::KEY_REQUIRES_UPGRADE. This method must then be called to upgrade the key. | ||
176 | * | ||
177 | * @param keyBlobToUpgrade The opaque descriptor returned by generateKey() or importKey(); | ||
178 | * | ||
179 | * @param upgradeParams A parameter list containing any parameters needed to complete the | ||
180 | * upgrade, including Tag::APPLICATION_ID and Tag::APPLICATION_DATA. | ||
181 | * | ||
182 | * @return error See the ErrorCode enum. | ||
183 | */ | ||
184 | upgradeKey(vec<uint8_t> keyBlobToUpgrade, vec<KeyParameter> upgradeParams) | ||
185 | generates(ErrorCode error, vec<uint8_t> upgradedKeyBlob); | ||
186 | |||
187 | /** | ||
188 | * Deletes the key, or key pair, associated with the key blob. After calling this function it | ||
189 | * will be impossible to use the key for any other operations. May be applied to keys from | ||
190 | * foreign roots of trust (keys not usable under the current root of trust). | ||
191 | * | ||
192 | * This is a NOP for keys that don't have rollback protection. | ||
193 | * | ||
194 | * @param keyBlobToUpgrade The opaque descriptor returned by generateKey() or importKey(); | ||
195 | * | ||
196 | * @return error See the ErrorCode enum. | ||
197 | */ | ||
198 | deleteKey(vec<uint8_t> keyBlob) generates(ErrorCode error); | ||
199 | |||
200 | /** | ||
201 | * Deletes all keys in the hardware keystore. Used when keystore is reset completely. After | ||
202 | * calling this function it will be impossible to use any previously generated or imported key | ||
203 | * blobs for any operations. | ||
204 | * | ||
205 | * This is a NOP if keys don't have rollback protection. | ||
206 | * | ||
207 | * @return error See the ErrorCode enum. | ||
208 | */ | ||
209 | deleteAllKeys() generates(ErrorCode error); | ||
210 | |||
211 | /** | ||
212 | * Begins a cryptographic operation using the specified key. If all is well, begin() will return | ||
213 | * ErrorCode::OK and create an operation handle which must be passed to subsequent calls to | ||
214 | * update(), finish() or abort(). | ||
215 | * | ||
216 | * It is critical that each call to begin() be paired with a subsequent call to finish() or | ||
217 | * abort(), to allow the keymaster implementation to clean up any internal operation state. | ||
218 | * Failure to do this may leak internal state space or other internal resources and may | ||
219 | * eventually cause begin() to return ErrorCode::TOO_MANY_OPERATIONS when it runs out of space | ||
220 | * for operations. Any result other than ErrorCode::OK from begin(), update() or finish() | ||
221 | * implicitly aborts the operation, in which case abort() need not be called (and will return | ||
222 | * ErrorCode::INVALID_OPERATION_HANDLE if called). | ||
223 | * | ||
224 | * @param purpose The purpose of the operation, one of KeyPurpose::ENCRYPT, KeyPurpose::DECRYPT, | ||
225 | * KeyPurpose::SIGN or KeyPurpose::VERIFY. Note that for AEAD modes, encryption and | ||
226 | * decryption imply signing and verification, respectively, but must be specified as | ||
227 | * KeyPurpose::ENCRYPT and KeyPurpose::DECRYPT. | ||
228 | * | ||
229 | * @param keyBlob The opaque key descriptor returned by generateKey() or importKey(). The key | ||
230 | * must have a purpose compatible with purpose and all of its usage requirements | ||
231 | * must be satisfied, or begin() will return an appropriate error code. | ||
232 | * | ||
233 | * @param inParams Additional parameters for the operation. This is typically used to provide | ||
234 | * authentication data, with Tag::AUTH_TOKEN. If Tag::APPLICATION_ID or | ||
235 | * Tag::APPLICATION_DATA were provided during generation, they must be provided | ||
236 | * here, or the operation will fail with ErrorCode::INVALID_KEY_BLOB. For operations | ||
237 | * that require a nonce or IV, on keys that were generated with Tag::CALLER_NONCE, | ||
238 | * inParams may contain a tag Tag::NONCE. | ||
239 | * | ||
240 | * @return error See the ErrorCode enum in types.hal. | ||
241 | * | ||
242 | * @return outParams Output parameters. Used to return additional data from the operation | ||
243 | * initialization, notably to return the IV or nonce from operations that generate | ||
244 | * an IV or nonce. | ||
245 | * | ||
246 | * @return operationHandle The newly-created operation handle which must be passed to update(), | ||
247 | * finish() or abort(). | ||
248 | */ | ||
249 | begin(KeyPurpose purpose, vec<uint8_t> key, vec<KeyParameter> inParams) | ||
250 | generates(ErrorCode error, vec<KeyParameter> outParams, OperationHandle operationHandle); | ||
251 | |||
252 | /** | ||
253 | * Provides data to, and possibly receives output from, an ongoing cryptographic operation begun | ||
254 | * with begin(). | ||
255 | * | ||
256 | * If operationHandle is invalid, update() will return ErrorCode::INVALID_OPERATION_HANDLE. | ||
257 | * | ||
258 | * update() may not consume all of the data provided in the data buffer. update() will return | ||
259 | * the amount consumed in inputConsumed. The caller may provide the unconsumed data in a | ||
260 | * subsequent call. | ||
261 | * | ||
262 | * @param operationHandle The operation handle returned by begin(). | ||
263 | * | ||
264 | * @param inParams Additional parameters for the operation. For AEAD modes, this is used to | ||
265 | * specify Tag::ADDITIONAL_DATA. Note that additional data may be provided in | ||
266 | * multiple calls to update(), but only until input data has been provided. | ||
267 | * | ||
268 | * @param input Data to be processed, per the parameters established in the call to begin(). | ||
269 | * Note that update() may or may not consume all of the data provided. See | ||
270 | * inputConsumed. | ||
271 | * | ||
272 | * @return error See the ErrorCode enum in types.hal. | ||
273 | * | ||
274 | * @return inputConsumed Amount of data that was consumed by update(). If this is less than the | ||
275 | * amount provided, the caller may provide the remainder in a subsequent call to | ||
276 | * update() or finish(). | ||
277 | * | ||
278 | * @return outParams Output parameters, used to return additional data from the operation The | ||
279 | * caller takes ownership of the output parameters array and must free it with | ||
280 | * keymaster_free_param_set(). | ||
281 | * | ||
282 | * @return output The output data, if any. | ||
283 | */ | ||
284 | update(OperationHandle operationHandle, vec<KeyParameter> inParams, vec<uint8_t> input) | ||
285 | generates(ErrorCode error, uint32_t inputConsumed, vec<KeyParameter> outParams, | ||
286 | vec<uint8_t> output); | ||
287 | |||
288 | /** | ||
289 | * Finalizes a cryptographic operation begun with begin() and invalidates operationHandle. | ||
290 | * | ||
291 | * @param operationHandle The operation handle returned by begin(). This handle will be | ||
292 | * invalid when finish() returns. | ||
293 | * | ||
294 | * @param inParams Additional parameters for the operation. For AEAD modes, this is used to | ||
295 | * specify Tag::ADDITIONAL_DATA, but only if no input data was provided to update(). | ||
296 | * | ||
297 | * @param input Data to be processed, per the parameters established in the call to | ||
298 | * begin(). finish() must consume all provided data or return | ||
299 | * ErrorCode::INVALID_INPUT_LENGTH. | ||
300 | * | ||
301 | * @param signature The signature to be verified if the purpose specified in the begin() call | ||
302 | * was KeyPurpose::VERIFY. | ||
303 | * | ||
304 | * @return error See the ErrorCode enum in types.hal. | ||
305 | * | ||
306 | * @return outParams Any output parameters generated by finish(). | ||
307 | * | ||
308 | * @return output The output data, if any. | ||
309 | */ | ||
310 | finish(OperationHandle operationHandle, vec<KeyParameter> inParams, vec<uint8_t> input, | ||
311 | vec<uint8_t> signature) | ||
312 | generates(ErrorCode error, vec<KeyParameter> outParams, vec<uint8_t> output); | ||
313 | |||
314 | /** | ||
315 | * Aborts a cryptographic operation begun with begin(), freeing all internal resources and | ||
316 | * invalidating operationHandle. | ||
317 | * | ||
318 | * @param operationHandle The operation handle returned by begin(). This handle will be | ||
319 | * invalid when abort() returns. | ||
320 | * | ||
321 | * @return error See the ErrorCode enum in types.hal. | ||
322 | */ | ||
323 | abort(OperationHandle operationHandle) generates(ErrorCode error); | ||
324 | }; | ||
diff --git a/keymaster/3.0/types.hal b/keymaster/3.0/types.hal new file mode 100644 index 00000000..e99e9c8d --- /dev/null +++ b/keymaster/3.0/types.hal | |||
@@ -0,0 +1,414 @@ | |||
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 | enum TagType : uint32_t { | ||
20 | INVALID = 0 << 28, /* Invalid type, used to designate a tag as uninitialized */ | ||
21 | ENUM = 1 << 28, | ||
22 | ENUM_REP = 2 << 28, /* Repeatable enumeration value. */ | ||
23 | UINT = 3 << 28, | ||
24 | UINT_REP = 4 << 28, /* Repeatable integer value */ | ||
25 | ULONG = 5 << 28, | ||
26 | DATE = 6 << 28, | ||
27 | BOOL = 7 << 28, | ||
28 | BIGNUM = 8 << 28, | ||
29 | BYTES = 9 << 28, | ||
30 | ULONG_REP = 10 << 28, /* Repeatable long value */ | ||
31 | }; | ||
32 | |||
33 | enum Tag : uint32_t { | ||
34 | INVALID = TagType:INVALID | 0, | ||
35 | |||
36 | /* | ||
37 | * Tags that must be semantically enforced by hardware and software implementations. | ||
38 | */ | ||
39 | |||
40 | /* Crypto parameters */ | ||
41 | PURPOSE = TagType:ENUM_REP | 1, /* KeyPurpose. */ | ||
42 | ALGORITHM = TagType:ENUM | 2, /* Algorithm. */ | ||
43 | KEY_SIZE = TagType:UINT | 3, /* Key size in bits. */ | ||
44 | BLOCK_MODE = TagType:ENUM_REP | 4, /* BlockMode. */ | ||
45 | DIGEST = TagType:ENUM_REP | 5, /* Digest. */ | ||
46 | PADDING = TagType:ENUM_REP | 6, /* PaddingMode. */ | ||
47 | CALLER_NONCE = TagType:BOOL | 7, /* Allow caller to specify nonce or IV. */ | ||
48 | MIN_MAC_LENGTH = TagType:UINT | 8, /* Minimum length of MAC or AEAD authentication tag in | ||
49 | * bits. */ | ||
50 | KDF = TagType:ENUM_REP | 9, /* KeyDerivationFunction. */ | ||
51 | EC_CURVE = TagType:ENUM | 10, /* EcCurve. */ | ||
52 | |||
53 | /* Algorithm-specific. */ | ||
54 | RSA_PUBLIC_EXPONENT = TagType:ULONG | 200, | ||
55 | ECIES_SINGLE_HASH_MODE = TagType:BOOL | 201, /* Whether the ephemeral public key is fed into the | ||
56 | * KDF. */ | ||
57 | INCLUDE_UNIQUE_ID = TagType:BOOL | 202, /* If true, attestation certificates for this key | ||
58 | * will contain an application-scoped and | ||
59 | * time-bounded device-unique ID.*/ | ||
60 | |||
61 | /* Other hardware-enforced. */ | ||
62 | BLOB_USAGE_REQUIREMENTS = TagType:ENUM | 301, /* KeyBlobUsageRequirements. */ | ||
63 | BOOTLOADER_ONLY = TagType:BOOL | 302, /* Usable only by bootloader. */ | ||
64 | |||
65 | /* | ||
66 | * Tags that should be semantically enforced by hardware if possible and will otherwise be | ||
67 | * enforced by software (keystore). | ||
68 | */ | ||
69 | |||
70 | /* Key validity period */ | ||
71 | ACTIVE_DATETIME = TagType:DATE | 400, /* Start of validity. */ | ||
72 | ORIGINATION_EXPIRE_DATETIME = TagType:DATE | 401, /* Date when new "messages" should no longer | ||
73 | * be created. */ | ||
74 | USAGE_EXPIRE_DATETIME = TagType:DATE | 402, /* Date when existing "messages" should no | ||
75 | * longer be trusted. */ | ||
76 | MIN_SECONDS_BETWEEN_OPS = TagType:UINT | 403, /* Minimum elapsed time between | ||
77 | * cryptographic operations with the key. */ | ||
78 | MAX_USES_PER_BOOT = TagType:UINT | 404, /* Number of times the key can be used per | ||
79 | * boot. */ | ||
80 | |||
81 | /* User authentication */ | ||
82 | ALL_USERS = TagType:BOOL | 500, /* Reserved for future use -- ignore. */ | ||
83 | USER_ID = TagType:UINT | 501, /* Reserved for future use -- ignore. */ | ||
84 | USER_SECURE_ID = TagType:ULONG_REP | 502, /* Secure ID of authorized user or authenticator(s). | ||
85 | * Disallowed if ALL_USERS or NO_AUTH_REQUIRED is | ||
86 | * present. */ | ||
87 | NO_AUTH_REQUIRED = TagType:BOOL | 503, /* If key is usable without authentication. */ | ||
88 | USER_AUTH_TYPE = TagType:ENUM | 504, /* Bitmask of authenticator types allowed when | ||
89 | * USER_SECURE_ID contains a secure user ID, rather | ||
90 | * than a secure authenticator ID. Defined in | ||
91 | * HardwareAuthenticatorType. */ | ||
92 | AUTH_TIMEOUT = TagType:UINT | 505, /* Required freshness of user authentication for | ||
93 | * private/secret key operations, in seconds. Public | ||
94 | * key operations require no authentication. If | ||
95 | * absent, authentication is required for every use. | ||
96 | * Authentication state is lost when the device is | ||
97 | * powered off. */ | ||
98 | ALLOW_WHILE_ON_BODY = TagType:BOOL | 506, /* Allow key to be used after authentication timeout | ||
99 | * if device is still on-body (requires secure on-body | ||
100 | * sensor. */ | ||
101 | |||
102 | /* Application access control */ | ||
103 | ALL_APPLICATIONS = TagType:BOOL | 600, /* Specified to indicate key is usable by all | ||
104 | * applications. */ | ||
105 | APPLICATION_ID = TagType:BYTES | 601, /* Byte string identifying the authorized application. */ | ||
106 | EXPORTABLE = TagType:BOOL | 602, /* If true, private/secret key can be exported, but only | ||
107 | * if all access control requirements for use are | ||
108 | * met. (keymaster2) */ | ||
109 | |||
110 | /* | ||
111 | * Semantically unenforceable tags, either because they have no specific meaning or because | ||
112 | * they're informational only. | ||
113 | */ | ||
114 | APPLICATION_DATA = TagType:BYTES | 700, /* Data provided by authorized application. */ | ||
115 | CREATION_DATETIME = TagType:DATE | 701, /* Key creation time */ | ||
116 | ORIGIN = TagType:ENUM | 702, /* keymaster_key_origin_t. */ | ||
117 | ROLLBACK_RESISTANT = TagType:BOOL | 703, /* Whether key is rollback-resistant. */ | ||
118 | ROOT_OF_TRUST = TagType:BYTES | 704, /* Root of trust ID. */ | ||
119 | OS_VERSION = TagType:UINT | 705, /* Version of system (keymaster2) */ | ||
120 | OS_PATCHLEVEL = TagType:UINT | 706, /* Patch level of system (keymaster2) */ | ||
121 | UNIQUE_ID = TagType:BYTES | 707, /* Used to provide unique ID in attestation */ | ||
122 | ATTESTATION_CHALLENGE = TagType:BYTES | 708, /* Used to provide challenge in attestation */ | ||
123 | ATTESTATION_APPLICATION_ID = TagType:BYTES | 709, /* Used to identify the set of possible | ||
124 | * applications of which one has initiated a | ||
125 | * key attestation */ | ||
126 | |||
127 | /* Tags used only to provide data to or receive data from operations */ | ||
128 | ASSOCIATED_DATA = TagType:BYTES | 1000, /* Used to provide associated data for AEAD modes. */ | ||
129 | NONCE = TagType:BYTES | 1001, /* Nonce or Initialization Vector */ | ||
130 | AUTH_TOKEN = TagType:BYTES | 1002, /* Authentication token that proves secure user | ||
131 | * authentication has been performed. Structure defined | ||
132 | * in hw_auth_token_t in hw_auth_token.h. */ | ||
133 | MAC_LENGTH = TagType:UINT | 1003, /* MAC or AEAD authentication tag length in bits. */ | ||
134 | |||
135 | RESET_SINCE_ID_ROTATION = TagType:BOOL | 1004, /* Whether the device has beeen factory reset | ||
136 | * since the last unique ID rotation. Used for | ||
137 | * key attestation. */ | ||
138 | }; | ||
139 | |||
140 | enum Algorithm : uint32_t { | ||
141 | /* Asymmetric algorithms. */ | ||
142 | RSA = 1, | ||
143 | // DSA = 2, -- Removed, do not re-use value 2. | ||
144 | EC = 3, | ||
145 | |||
146 | /* Block ciphers algorithms */ | ||
147 | AES = 32, | ||
148 | |||
149 | /* MAC algorithms */ | ||
150 | HMAC = 128, | ||
151 | }; | ||
152 | |||
153 | /** | ||
154 | * Symmetric block cipher modes provided by keymaster implementations. | ||
155 | */ | ||
156 | enum BlockMode : uint32_t { | ||
157 | /* Unauthenticated modes, usable only for encryption/decryption and not generally recommended | ||
158 | * except for compatibility with existing other protocols. */ | ||
159 | ECB = 1, | ||
160 | CBC = 2, | ||
161 | CTR = 3, | ||
162 | |||
163 | /* Authenticated modes, usable for encryption/decryption and signing/verification. Recommended | ||
164 | * over unauthenticated modes for all purposes. */ | ||
165 | GCM = 32, | ||
166 | }; | ||
167 | |||
168 | /** | ||
169 | * Padding modes that may be applied to plaintext for encryption operations. This list includes | ||
170 | * padding modes for both symmetric and asymmetric algorithms. Note that implementations should not | ||
171 | * provide all possible combinations of algorithm and padding, only the | ||
172 | * cryptographically-appropriate pairs. | ||
173 | */ | ||
174 | enum PaddingMode : uint32_t { | ||
175 | NONE = 1, /* deprecated */ | ||
176 | RSA_OAEP = 2, | ||
177 | RSA_PSS = 3, | ||
178 | RSA_PKCS1_1_5_ENCRYPT = 4, | ||
179 | RSA_PKCS1_1_5_SIGN = 5, | ||
180 | PKCS7 = 64, | ||
181 | }; | ||
182 | |||
183 | /** | ||
184 | * Digests provided by keymaster implementations. | ||
185 | */ | ||
186 | enum Digest : uint32_t { | ||
187 | NONE = 0, | ||
188 | MD5 = 1, /* Optional, may not be implemented in hardware, will be handled in software if | ||
189 | * needed. */ | ||
190 | SHA1 = 2, | ||
191 | SHA_2_224 = 3, | ||
192 | SHA_2_256 = 4, | ||
193 | SHA_2_384 = 5, | ||
194 | SHA_2_512 = 6, | ||
195 | }; | ||
196 | |||
197 | /** | ||
198 | * Supported EC curves, used in ECDSA | ||
199 | */ | ||
200 | enum EcCurve : uint32_t { | ||
201 | P_224 = 0, | ||
202 | P_256 = 1, | ||
203 | P_384 = 2, | ||
204 | P_521 = 3, | ||
205 | }; | ||
206 | |||
207 | /** | ||
208 | * The origin of a key (or pair), i.e. where it was generated. Note that ORIGIN can be found in | ||
209 | * either the hardware-enforced or software-enforced list for a key, indicating whether the key is | ||
210 | * hardware or software-based. Specifically, a key with GENERATED in the hardware-enforced list is | ||
211 | * guaranteed never to have existed outide the secure hardware. | ||
212 | */ | ||
213 | enum KeyOrigin : uint32_t { | ||
214 | GENERATED = 0, /* Generated in keymaster. Should not exist outside the TEE. */ | ||
215 | DERIVED = 1, /* Derived inside keymaster. Likely exists off-device. */ | ||
216 | IMPORTED = 2, /* Imported into keymaster. Existed as cleartext in Android. */ | ||
217 | UNKNOWN = 3, /* Keymaster did not record origin. This value can only be seen on keys in a | ||
218 | * keymaster0 implementation. The keymaster0 adapter uses this value to document | ||
219 | * the fact that it is unkown whether the key was generated inside or imported | ||
220 | * into keymaster. */ | ||
221 | }; | ||
222 | |||
223 | /** | ||
224 | * Usability requirements of key blobs. This defines what system functionality must be available | ||
225 | * for the key to function. For example, key "blobs" which are actually handles referencing | ||
226 | * encrypted key material stored in the file system cannot be used until the file system is | ||
227 | * available, and should have BLOB_REQUIRES_FILE_SYSTEM. Other requirements entries will be added | ||
228 | * as needed for implementations. | ||
229 | */ | ||
230 | enum KeyBlobUsageRequirements : uint32_t { | ||
231 | STANDALONE = 0, | ||
232 | REQUIRES_FILE_SYSTEM = 1, | ||
233 | }; | ||
234 | |||
235 | /** | ||
236 | * Possible purposes of a key (or pair). | ||
237 | */ | ||
238 | enum KeyPurpose : uint32_t { | ||
239 | ENCRYPT = 0, /* Usable with RSA, EC and AES keys. */ | ||
240 | DECRYPT = 1, /* Usable with RSA, EC and AES keys. */ | ||
241 | SIGN = 2, /* Usable with RSA, EC and HMAC keys. */ | ||
242 | VERIFY = 3, /* Usable with RSA, EC and HMAC keys. */ | ||
243 | DERIVE_KEY = 4, /* Usable with EC keys. */ | ||
244 | }; | ||
245 | |||
246 | /** | ||
247 | * Keymaster error codes. | ||
248 | */ | ||
249 | enum ErrorCode : uint32_t { | ||
250 | OK = 0, | ||
251 | ROOT_OF_TRUST_ALREADY_SET = -1, | ||
252 | UNSUPPORTED_PURPOSE = -2, | ||
253 | INCOMPATIBLE_PURPOSE = -3, | ||
254 | UNSUPPORTED_ALGORITHM = -4, | ||
255 | INCOMPATIBLE_ALGORITHM = -5, | ||
256 | UNSUPPORTED_KEY_SIZE = -6, | ||
257 | UNSUPPORTED_BLOCK_MODE = -7, | ||
258 | INCOMPATIBLE_BLOCK_MODE = -8, | ||
259 | UNSUPPORTED_MAC_LENGTH = -9, | ||
260 | UNSUPPORTED_PADDING_MODE = -10, | ||
261 | INCOMPATIBLE_PADDING_MODE = -11, | ||
262 | UNSUPPORTED_DIGEST = -12, | ||
263 | INCOMPATIBLE_DIGEST = -13, | ||
264 | INVALID_EXPIRATION_TIME = -14, | ||
265 | INVALID_USER_ID = -15, | ||
266 | INVALID_AUTHORIZATION_TIMEOUT = -16, | ||
267 | UNSUPPORTED_KEY_FORMAT = -17, | ||
268 | INCOMPATIBLE_KEY_FORMAT = -18, | ||
269 | UNSUPPORTED_KEY_ENCRYPTION_ALGORITHM = -19, /* For PKCS8 & PKCS12 */ | ||
270 | UNSUPPORTED_KEY_VERIFICATION_ALGORITHM = -20, /* For PKCS8 & PKCS12 */ | ||
271 | INVALID_INPUT_LENGTH = -21, | ||
272 | KEY_EXPORT_OPTIONS_INVALID = -22, | ||
273 | DELEGATION_NOT_ALLOWED = -23, | ||
274 | KEY_NOT_YET_VALID = -24, | ||
275 | KEY_EXPIRED = -25, | ||
276 | KEY_USER_NOT_AUTHENTICATED = -26, | ||
277 | OUTPUT_PARAMETER_NULL = -27, | ||
278 | INVALID_OPERATION_HANDLE = -28, | ||
279 | INSUFFICIENT_BUFFER_SPACE = -29, | ||
280 | VERIFICATION_FAILED = -30, | ||
281 | TOO_MANY_OPERATIONS = -31, | ||
282 | UNEXPECTED_NULL_POINTER = -32, | ||
283 | INVALID_KEY_BLOB = -33, | ||
284 | IMPORTED_KEY_NOT_ENCRYPTED = -34, | ||
285 | IMPORTED_KEY_DECRYPTION_FAILED = -35, | ||
286 | IMPORTED_KEY_NOT_SIGNED = -36, | ||
287 | IMPORTED_KEY_VERIFICATION_FAILED = -37, | ||
288 | INVALID_ARGUMENT = -38, | ||
289 | UNSUPPORTED_TAG = -39, | ||
290 | INVALID_TAG = -40, | ||
291 | MEMORY_ALLOCATION_FAILED = -41, | ||
292 | IMPORT_PARAMETER_MISMATCH = -44, | ||
293 | SECURE_HW_ACCESS_DENIED = -45, | ||
294 | OPERATION_CANCELLED = -46, | ||
295 | CONCURRENT_ACCESS_CONFLICT = -47, | ||
296 | SECURE_HW_BUSY = -48, | ||
297 | SECURE_HW_COMMUNICATION_FAILED = -49, | ||
298 | UNSUPPORTED_EC_FIELD = -50, | ||
299 | MISSING_NONCE = -51, | ||
300 | INVALID_NONCE = -52, | ||
301 | MISSING_MAC_LENGTH = -53, | ||
302 | KEY_RATE_LIMIT_EXCEEDED = -54, | ||
303 | CALLER_NONCE_PROHIBITED = -55, | ||
304 | KEY_MAX_OPS_EXCEEDED = -56, | ||
305 | INVALID_MAC_LENGTH = -57, | ||
306 | MISSING_MIN_MAC_LENGTH = -58, | ||
307 | UNSUPPORTED_MIN_MAC_LENGTH = -59, | ||
308 | UNSUPPORTED_KDF = -60, | ||
309 | UNSUPPORTED_EC_CURVE = -61, | ||
310 | KEY_REQUIRES_UPGRADE = -62, | ||
311 | ATTESTATION_CHALLENGE_MISSING = -63, | ||
312 | KEYMASTER_NOT_CONFIGURED = -64, | ||
313 | ATTESTATION_APPLICATION_ID_MISSING = -65, | ||
314 | |||
315 | UNIMPLEMENTED = -100, | ||
316 | VERSION_MISMATCH = -101, | ||
317 | |||
318 | UNKNOWN_ERROR = -1000, | ||
319 | }; | ||
320 | |||
321 | /** | ||
322 | * Key derivation functions, mostly used in ECIES. | ||
323 | */ | ||
324 | enum KeyDerivationFunction : uint32_t { | ||
325 | /* Do not apply a key derivation function; use the raw agreed key */ | ||
326 | NONE = 0, | ||
327 | /* HKDF defined in RFC 5869 with SHA256 */ | ||
328 | RFC5869_SHA256 = 1, | ||
329 | /* KDF1 defined in ISO 18033-2 with SHA1 */ | ||
330 | ISO18033_2_KDF1_SHA1 = 2, | ||
331 | /* KDF1 defined in ISO 18033-2 with SHA256 */ | ||
332 | ISO18033_2_KDF1_SHA256 = 3, | ||
333 | /* KDF2 defined in ISO 18033-2 with SHA1 */ | ||
334 | ISO18033_2_KDF2_SHA1 = 4, | ||
335 | /* KDF2 defined in ISO 18033-2 with SHA256 */ | ||
336 | ISO18033_2_KDF2_SHA256 = 5, | ||
337 | }; | ||
338 | |||
339 | /** | ||
340 | * Hardware authentication type, used by HardwareAuthTokens to specify the mechanism used to | ||
341 | * authentiate the user, and in KeyCharacteristics to specify the allowable mechanisms for | ||
342 | * authenticating to activate a key. | ||
343 | */ | ||
344 | enum HardwareAuthenticatorType : uint32_t { | ||
345 | NONE = 0, | ||
346 | PASSWORD = 1 << 0, | ||
347 | FINGERPRINT = 1 << 1, | ||
348 | // Additional entries must be powers of 2. | ||
349 | ANY = 0xFFFFFFFF, | ||
350 | }; | ||
351 | |||
352 | struct KeyParameter { | ||
353 | /* Discriminates the uinon/blob field used. The blob cannot be coincided with the union, but | ||
354 | * only one of "f" and "blob" is ever used at a time. */ | ||
355 | Tag tag; | ||
356 | union IntegerParams { | ||
357 | /* Enum types */ | ||
358 | Algorithm algorithm; | ||
359 | BlockMode blockMode; | ||
360 | PaddingMode paddingMode; | ||
361 | Digest digest; | ||
362 | EcCurve ecCurve; | ||
363 | KeyOrigin origin; | ||
364 | KeyBlobUsageRequirements keyBlobUsageRequirements; | ||
365 | KeyPurpose purpose; | ||
366 | KeyDerivationFunction keyDerivationFunction; | ||
367 | HardwareAuthenticatorType hardwareAuthenticatorType; | ||
368 | |||
369 | /* Other types */ | ||
370 | bool boolValue; // Always true, if a boolean tag is present. | ||
371 | uint32_t integer; | ||
372 | uint64_t longInteger; | ||
373 | uint64_t dateTime; | ||
374 | }; | ||
375 | IntegerParams f; // Hidl does not support anonymous unions, so we have to name it. | ||
376 | vec<uint8_t> blob; | ||
377 | }; | ||
378 | |||
379 | struct KeyCharacteristics { | ||
380 | vec<KeyParameter> softwareEnforced; | ||
381 | vec<KeyParameter> teeEnforced; | ||
382 | }; | ||
383 | |||
384 | /** | ||
385 | * Data used to prove successful authentication. | ||
386 | */ | ||
387 | struct HardwareAuthToken { | ||
388 | uint64_t challenge; | ||
389 | uint64_t userId; // Secure User ID, not Android user ID. | ||
390 | uint64_t authenticatorId; // Secure authenticator ID. | ||
391 | uint32_t authenticatorType; // HardwareAuthenticatorType, in network order. | ||
392 | uint64_t timestamp; // In network order. | ||
393 | uint8_t[32] hmac; // HMAC is computed over 0 || challenge || user_id || | ||
394 | // authenticator_id || authenticator_type || timestamp, with a | ||
395 | // prefixed 0 byte (which was a version field in Keymaster1 and | ||
396 | // Keymaster2) and the fields packed (no padding; so you probably | ||
397 | // can't just compute over the bytes of the struct). | ||
398 | }; | ||
399 | |||
400 | enum SecurityLevel : uint32_t { | ||
401 | SOFTWARE = 0, | ||
402 | TRUSTED_ENVIRONMENT = 1, | ||
403 | }; | ||
404 | |||
405 | /** | ||
406 | * Formats for key import and export. | ||
407 | */ | ||
408 | enum KeyFormat : uint32_t { | ||
409 | X509 = 0, /* for public key export */ | ||
410 | PKCS8 = 1, /* for asymmetric key pair import */ | ||
411 | RAW = 3, /* for symmetric key import and export*/ | ||
412 | }; | ||
413 | |||
414 | typedef uint64_t OperationHandle; | ||
diff --git a/keymaster/Android.bp b/keymaster/Android.bp new file mode 100644 index 00000000..09b8cb28 --- /dev/null +++ b/keymaster/Android.bp | |||
@@ -0,0 +1,4 @@ | |||
1 | // This is an autogenerated file, do not edit. | ||
2 | subdirs = [ | ||
3 | "3.0", | ||
4 | ] | ||