1 /*
2 * Copyright (C) 2014 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 #ifndef ANDROID_HARDWARE_KEYMASTER_DEFS_H
18 #define ANDROID_HARDWARE_KEYMASTER_DEFS_H
19
20 #include <stdint.h>
21 #include <stdlib.h>
22 #include <string.h>
23
24 #ifdef __cplusplus
25 extern "C" {
26 #endif // __cplusplus
27
28 /**
29 * Authorization tags each have an associated type. This enumeration facilitates tagging each with
30 * a type, by using the high four bits (of an implied 32-bit unsigned enum value) to specify up to
31 * 16 data types. These values are ORed with tag IDs to generate the final tag ID values.
32 */
33 typedef enum {
34 KM_INVALID = 0 << 28, /* Invalid type, used to designate a tag as uninitialized */
35 KM_ENUM = 1 << 28,
36 KM_ENUM_REP = 2 << 28, /* Repeatable enumeration value. */
37 KM_UINT = 3 << 28,
38 KM_UINT_REP = 4 << 28, /* Repeatable integer value */
39 KM_ULONG = 5 << 28,
40 KM_DATE = 6 << 28,
41 KM_BOOL = 7 << 28,
42 KM_BIGNUM = 8 << 28,
43 KM_BYTES = 9 << 28,
44 KM_ULONG_REP = 10 << 28, /* Repeatable long value */
45 } keymaster_tag_type_t;
46
47 typedef enum {
48 KM_TAG_INVALID = KM_INVALID | 0,
49
50 /*
51 * Tags that must be semantically enforced by hardware and software implementations.
52 */
53
54 /* Crypto parameters */
55 KM_TAG_PURPOSE = KM_ENUM_REP | 1, /* keymaster_purpose_t. */
56 KM_TAG_ALGORITHM = KM_ENUM | 2, /* keymaster_algorithm_t. */
57 KM_TAG_KEY_SIZE = KM_UINT | 3, /* Key size in bits. */
58 KM_TAG_BLOCK_MODE = KM_ENUM_REP | 4, /* keymaster_block_mode_t. */
59 KM_TAG_DIGEST = KM_ENUM_REP | 5, /* keymaster_digest_t. */
60 KM_TAG_PADDING = KM_ENUM_REP | 6, /* keymaster_padding_t. */
61 KM_TAG_CALLER_NONCE = KM_BOOL | 7, /* Allow caller to specify nonce or IV. */
62 KM_TAG_MIN_MAC_LENGTH = KM_UINT | 8, /* Minimum length of MAC or AEAD authentication tag in
63 * bits. */
64 KM_TAG_KDF = KM_ENUM_REP | 9, /* keymaster_kdf_t (keymaster2) */
65 KM_TAG_EC_CURVE = KM_ENUM | 10, /* keymaster_ec_curve_t (keymaster2) */
66
67 /* Algorithm-specific. */
68 KM_TAG_RSA_PUBLIC_EXPONENT = KM_ULONG | 200,
69 KM_TAG_ECIES_SINGLE_HASH_MODE = KM_BOOL | 201, /* Whether the ephemeral public key is fed into
70 * the KDF */
71 KM_TAG_INCLUDE_UNIQUE_ID = KM_BOOL | 202, /* If true, attestation certificates for this key
72 * will contain an application-scoped and
73 * time-bounded device-unique ID. (keymaster2) */
74
75 /* Other hardware-enforced. */
76 KM_TAG_BLOB_USAGE_REQUIREMENTS = KM_ENUM | 301, /* keymaster_key_blob_usage_requirements_t */
77 KM_TAG_BOOTLOADER_ONLY = KM_BOOL | 302, /* Usable only by bootloader */
78 KM_TAG_ROLLBACK_RESISTANCE = KM_BOOL | 303, /* Hardware enforced deletion with deleteKey
79 * or deleteAllKeys is supported */
80 KM_TAG_EARLY_BOOT_ONLY = KM_BOOL | 305, /* Key can only be used during early boot. */
81
82 /*
83 * Tags that should be semantically enforced by hardware if possible and will otherwise be
84 * enforced by software (keystore).
85 */
86
87 /* Key validity period */
88 KM_TAG_ACTIVE_DATETIME = KM_DATE | 400, /* Start of validity */
89 KM_TAG_ORIGINATION_EXPIRE_DATETIME = KM_DATE | 401, /* Date when new "messages" should no
90 longer be created. */
91 KM_TAG_USAGE_EXPIRE_DATETIME = KM_DATE | 402, /* Date when existing "messages" should no
92 longer be trusted. */
93 KM_TAG_MIN_SECONDS_BETWEEN_OPS = KM_UINT | 403, /* Minimum elapsed time between
94 cryptographic operations with the key. */
95 KM_TAG_MAX_USES_PER_BOOT = KM_UINT | 404, /* Number of times the key can be used per
96 boot. */
97
98 /* User authentication */
99 KM_TAG_ALL_USERS = KM_BOOL | 500, /* Reserved for future use -- ignore */
100 KM_TAG_USER_ID = KM_UINT | 501, /* Reserved for future use -- ignore */
101 KM_TAG_USER_SECURE_ID = KM_ULONG_REP | 502, /* Secure ID of authorized user or authenticator(s).
102 Disallowed if KM_TAG_ALL_USERS or
103 KM_TAG_NO_AUTH_REQUIRED is present. */
104 KM_TAG_NO_AUTH_REQUIRED = KM_BOOL | 503, /* If key is usable without authentication. */
105 KM_TAG_USER_AUTH_TYPE = KM_ENUM | 504, /* Bitmask of authenticator types allowed when
106 * KM_TAG_USER_SECURE_ID contains a secure user ID,
107 * rather than a secure authenticator ID. Defined in
108 * hw_authenticator_type_t in hw_auth_token.h. */
109 KM_TAG_AUTH_TIMEOUT = KM_UINT | 505, /* Required freshness of user authentication for
110 private/secret key operations, in seconds.
111 Public key operations require no authentication.
112 If absent, authentication is required for every
113 use. Authentication state is lost when the
114 device is powered off. */
115 KM_TAG_ALLOW_WHILE_ON_BODY = KM_BOOL | 506, /* Allow key to be used after authentication timeout
116 * if device is still on-body (requires secure
117 * on-body sensor. */
118 KM_TAG_TRUSTED_CONFIRMATION_REQUIRED = KM_BOOL | 508, /* Require user confirmation through a
119 * trusted UI to use this key */
120 KM_TAG_UNLOCKED_DEVICE_REQUIRED = KM_BOOL | 509, /* Require the device screen to be unlocked if the
121 * key is used. */
122
123 /* Application access control */
124 KM_TAG_ALL_APPLICATIONS = KM_BOOL | 600, /* Specified to indicate key is usable by all
125 * applications. */
126 KM_TAG_APPLICATION_ID = KM_BYTES | 601, /* Byte string identifying the authorized
127 * application. */
128 KM_TAG_EXPORTABLE = KM_BOOL | 602, /* If true, private/secret key can be exported, but
129 * only if all access control requirements for use are
130 * met. (keymaster2) */
131
132 /*
133 * Semantically unenforceable tags, either because they have no specific meaning or because
134 * they're informational only.
135 */
136 KM_TAG_APPLICATION_DATA = KM_BYTES | 700, /* Data provided by authorized application. */
137 KM_TAG_CREATION_DATETIME = KM_DATE | 701, /* Key creation time */
138 KM_TAG_ORIGIN = KM_ENUM | 702, /* keymaster_key_origin_t. */
139 KM_TAG_ROLLBACK_RESISTANT = KM_BOOL | 703, /* Whether key is rollback-resistant. */
140 KM_TAG_ROOT_OF_TRUST = KM_BYTES | 704, /* Root of trust ID. */
141 KM_TAG_OS_VERSION = KM_UINT | 705, /* Version of system (keymaster2) */
142 KM_TAG_OS_PATCHLEVEL = KM_UINT | 706, /* Patch level of system (keymaster2) */
143 KM_TAG_UNIQUE_ID = KM_BYTES | 707, /* Used to provide unique ID in attestation */
144 KM_TAG_ATTESTATION_CHALLENGE = KM_BYTES | 708, /* Used to provide challenge in attestation */
145 KM_TAG_ATTESTATION_APPLICATION_ID = KM_BYTES | 709, /* Used to identify the set of possible
146 * applications of which one has initiated
147 * a key attestation */
148 KM_TAG_ATTESTATION_ID_BRAND = KM_BYTES | 710, /* Used to provide the device's brand name to be
149 included in attestation */
150 KM_TAG_ATTESTATION_ID_DEVICE = KM_BYTES | 711, /* Used to provide the device's device name to be
151 included in attestation */
152 KM_TAG_ATTESTATION_ID_PRODUCT = KM_BYTES | 712, /* Used to provide the device's product name to
153 be included in attestation */
154 KM_TAG_ATTESTATION_ID_SERIAL = KM_BYTES | 713, /* Used to provide the device's serial number to
155 be included in attestation */
156 KM_TAG_ATTESTATION_ID_IMEI = KM_BYTES | 714, /* Used to provide the device's IMEI to be
157 included in attestation */
158 KM_TAG_ATTESTATION_ID_MEID = KM_BYTES | 715, /* Used to provide the device's MEID to be
159 included in attestation */
160 KM_TAG_ATTESTATION_ID_MANUFACTURER = KM_BYTES | 716, /* Used to provide the device's
161 manufacturer name to be included in
162 attestation */
163 KM_TAG_ATTESTATION_ID_MODEL = KM_BYTES | 717, /* Used to provide the device's model name to be
164 included in attestation */
165 KM_TAG_DEVICE_UNIQUE_ATTESTATION = KM_BOOL | 720, /* Indicates StrongBox device-unique attestation
166 is requested. */
167 KM_TAG_IDENTITY_CREDENTIAL_KEY = KM_BOOL | 721, /* This is an identity credential key */
168
169
170 /* Tags used only to provide data to or receive data from operations */
171 KM_TAG_ASSOCIATED_DATA = KM_BYTES | 1000, /* Used to provide associated data for AEAD modes. */
172 KM_TAG_NONCE = KM_BYTES | 1001, /* Nonce or Initialization Vector */
173 KM_TAG_AUTH_TOKEN = KM_BYTES | 1002, /* Authentication token that proves secure user
174 authentication has been performed. Structure
175 defined in hw_auth_token_t in hw_auth_token.h. */
176 KM_TAG_MAC_LENGTH = KM_UINT | 1003, /* MAC or AEAD authentication tag length in
177 * bits. */
178
179 KM_TAG_RESET_SINCE_ID_ROTATION = KM_BOOL | 1004, /* Whether the device has beeen factory reset
180 since the last unique ID rotation. Used for
181 key attestation. */
182 } keymaster_tag_t;
183
184 /**
185 * Algorithms that may be provided by keymaster implementations. Those that must be provided by all
186 * implementations are tagged as "required".
187 */
188 typedef enum {
189 /* Asymmetric algorithms. */
190 KM_ALGORITHM_RSA = 1,
191 // KM_ALGORITHM_DSA = 2, -- Removed, do not re-use value 2.
192 KM_ALGORITHM_EC = 3,
193
194 /* Block ciphers algorithms */
195 KM_ALGORITHM_AES = 32,
196 KM_ALGORITHM_TRIPLE_DES = 33,
197
198 /* MAC algorithms */
199 KM_ALGORITHM_HMAC = 128,
200 } keymaster_algorithm_t;
201
202 /**
203 * Symmetric block cipher modes provided by keymaster implementations.
204 */
205 typedef enum {
206 /* Unauthenticated modes, usable only for encryption/decryption and not generally recommended
207 * except for compatibility with existing other protocols. */
208 KM_MODE_ECB = 1,
209 KM_MODE_CBC = 2,
210 KM_MODE_CTR = 3,
211
212 /* Authenticated modes, usable for encryption/decryption and signing/verification. Recommended
213 * over unauthenticated modes for all purposes. */
214 KM_MODE_GCM = 32,
215 } keymaster_block_mode_t;
216
217 /**
218 * Padding modes that may be applied to plaintext for encryption operations. This list includes
219 * padding modes for both symmetric and asymmetric algorithms. Note that implementations should not
220 * provide all possible combinations of algorithm and padding, only the
221 * cryptographically-appropriate pairs.
222 */
223 typedef enum {
224 KM_PAD_NONE = 1, /* deprecated */
225 KM_PAD_RSA_OAEP = 2,
226 KM_PAD_RSA_PSS = 3,
227 KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4,
228 KM_PAD_RSA_PKCS1_1_5_SIGN = 5,
229 KM_PAD_PKCS7 = 64,
230 } keymaster_padding_t;
231
232 /**
233 * Digests provided by keymaster implementations.
234 */
235 typedef enum {
236 KM_DIGEST_NONE = 0,
237 KM_DIGEST_MD5 = 1, /* Optional, may not be implemented in hardware, will be handled in software
238 * if needed. */
239 KM_DIGEST_SHA1 = 2,
240 KM_DIGEST_SHA_2_224 = 3,
241 KM_DIGEST_SHA_2_256 = 4,
242 KM_DIGEST_SHA_2_384 = 5,
243 KM_DIGEST_SHA_2_512 = 6,
244 } keymaster_digest_t;
245
246 /*
247 * Key derivation functions, mostly used in ECIES.
248 */
249 typedef enum {
250 /* Do not apply a key derivation function; use the raw agreed key */
251 KM_KDF_NONE = 0,
252 /* HKDF defined in RFC 5869 with SHA256 */
253 KM_KDF_RFC5869_SHA256 = 1,
254 /* KDF1 defined in ISO 18033-2 with SHA1 */
255 KM_KDF_ISO18033_2_KDF1_SHA1 = 2,
256 /* KDF1 defined in ISO 18033-2 with SHA256 */
257 KM_KDF_ISO18033_2_KDF1_SHA256 = 3,
258 /* KDF2 defined in ISO 18033-2 with SHA1 */
259 KM_KDF_ISO18033_2_KDF2_SHA1 = 4,
260 /* KDF2 defined in ISO 18033-2 with SHA256 */
261 KM_KDF_ISO18033_2_KDF2_SHA256 = 5,
262 } keymaster_kdf_t;
263
264 /**
265 * Supported EC curves, used in ECDSA/ECIES.
266 */
267 typedef enum {
268 KM_EC_CURVE_P_224 = 0,
269 KM_EC_CURVE_P_256 = 1,
270 KM_EC_CURVE_P_384 = 2,
271 KM_EC_CURVE_P_521 = 3,
272 } keymaster_ec_curve_t;
273
274 /**
275 * The origin of a key (or pair), i.e. where it was generated. Note that KM_TAG_ORIGIN can be found
276 * in either the hardware-enforced or software-enforced list for a key, indicating whether the key
277 * is hardware or software-based. Specifically, a key with KM_ORIGIN_GENERATED in the
278 * hardware-enforced list is guaranteed never to have existed outide the secure hardware.
279 */
280 typedef enum {
281 KM_ORIGIN_GENERATED = 0, /* Generated in keymaster. Should not exist outside the TEE. */
282 KM_ORIGIN_DERIVED = 1, /* Derived inside keymaster. Likely exists off-device. */
283 KM_ORIGIN_IMPORTED = 2, /* Imported into keymaster. Existed as cleartext in Android. */
284 KM_ORIGIN_UNKNOWN = 3, /* Keymaster did not record origin. This value can only be seen on
285 * keys in a keymaster0 implementation. The keymaster0 adapter uses
286 * this value to document the fact that it is unkown whether the key
287 * was generated inside or imported into keymaster. */
288 } keymaster_key_origin_t;
289
290 /**
291 * Usability requirements of key blobs. This defines what system functionality must be available
292 * for the key to function. For example, key "blobs" which are actually handles referencing
293 * encrypted key material stored in the file system cannot be used until the file system is
294 * available, and should have BLOB_REQUIRES_FILE_SYSTEM. Other requirements entries will be added
295 * as needed for implementations.
296 */
297 typedef enum {
298 KM_BLOB_STANDALONE = 0,
299 KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
300 } keymaster_key_blob_usage_requirements_t;
301
302 /**
303 * Possible purposes of a key (or pair).
304 */
305 typedef enum {
306 KM_PURPOSE_ENCRYPT = 0, /* Usable with RSA, EC and AES keys. */
307 KM_PURPOSE_DECRYPT = 1, /* Usable with RSA, EC and AES keys. */
308 KM_PURPOSE_SIGN = 2, /* Usable with RSA, EC and HMAC keys. */
309 KM_PURPOSE_VERIFY = 3, /* Usable with RSA, EC and HMAC keys. */
310 KM_PURPOSE_DERIVE_KEY = 4, /* Usable with EC keys. */
311 KM_PURPOSE_WRAP = 5, /* Usable with wrapped keys. */
312
313 } keymaster_purpose_t;
314
315 typedef struct {
316 const uint8_t* data;
317 size_t data_length;
318 } keymaster_blob_t;
319
320 typedef struct {
321 keymaster_tag_t tag;
322 union {
323 uint32_t enumerated; /* KM_ENUM and KM_ENUM_REP */
324 bool boolean; /* KM_BOOL */
325 uint32_t integer; /* KM_INT and KM_INT_REP */
326 uint64_t long_integer; /* KM_LONG */
327 uint64_t date_time; /* KM_DATE */
328 keymaster_blob_t blob; /* KM_BIGNUM and KM_BYTES*/
329 };
330 } keymaster_key_param_t;
331
332 typedef struct {
333 keymaster_key_param_t* params; /* may be NULL if length == 0 */
334 size_t length;
335 } keymaster_key_param_set_t;
336
337 /**
338 * Parameters that define a key's characteristics, including authorized modes of usage and access
339 * control restrictions. The parameters are divided into two categories, those that are enforced by
340 * secure hardware, and those that are not. For a software-only keymaster implementation the
341 * enforced array must NULL. Hardware implementations must enforce everything in the enforced
342 * array.
343 */
344 typedef struct {
345 keymaster_key_param_set_t hw_enforced;
346 keymaster_key_param_set_t sw_enforced;
347 } keymaster_key_characteristics_t;
348
349 typedef struct {
350 const uint8_t* key_material;
351 size_t key_material_size;
352 } keymaster_key_blob_t;
353
354 typedef struct {
355 keymaster_blob_t* entries;
356 size_t entry_count;
357 } keymaster_cert_chain_t;
358
359 typedef enum {
360 KM_VERIFIED_BOOT_VERIFIED = 0, /* Full chain of trust extending from the bootloader to
361 * verified partitions, including the bootloader, boot
362 * partition, and all verified partitions*/
363 KM_VERIFIED_BOOT_SELF_SIGNED = 1, /* The boot partition has been verified using the embedded
364 * certificate, and the signature is valid. The bootloader
365 * displays a warning and the fingerprint of the public
366 * key before allowing the boot process to continue.*/
367 KM_VERIFIED_BOOT_UNVERIFIED = 2, /* The device may be freely modified. Device integrity is left
368 * to the user to verify out-of-band. The bootloader
369 * displays a warning to the user before allowing the boot
370 * process to continue */
371 KM_VERIFIED_BOOT_FAILED = 3, /* The device failed verification. The bootloader displays a
372 * warning and stops the boot process, so no keymaster
373 * implementation should ever actually return this value,
374 * since it should not run. Included here only for
375 * completeness. */
376 } keymaster_verified_boot_t;
377
378 typedef enum {
379 KM_SECURITY_LEVEL_SOFTWARE = 0,
380 KM_SECURITY_LEVEL_TRUSTED_ENVIRONMENT = 1,
381 KM_SECURITY_LEVEL_STRONGBOX = 2,
382 } keymaster_security_level_t;
383
384 /**
385 * Formats for key import and export.
386 */
387 typedef enum {
388 KM_KEY_FORMAT_X509 = 0, /* for public key export */
389 KM_KEY_FORMAT_PKCS8 = 1, /* for asymmetric key pair import */
390 KM_KEY_FORMAT_RAW = 3, /* for symmetric key import and export*/
391 } keymaster_key_format_t;
392
393 /**
394 * The keymaster operation API consists of begin, update, finish and abort. This is the type of the
395 * handle used to tie the sequence of calls together. A 64-bit value is used because it's important
396 * that handles not be predictable. Implementations must use strong random numbers for handle
397 * values.
398 */
399 typedef uint64_t keymaster_operation_handle_t;
400
401 typedef enum {
402 KM_ERROR_OK = 0,
403 KM_ERROR_ROOT_OF_TRUST_ALREADY_SET = -1,
404 KM_ERROR_UNSUPPORTED_PURPOSE = -2,
405 KM_ERROR_INCOMPATIBLE_PURPOSE = -3,
406 KM_ERROR_UNSUPPORTED_ALGORITHM = -4,
407 KM_ERROR_INCOMPATIBLE_ALGORITHM = -5,
408 KM_ERROR_UNSUPPORTED_KEY_SIZE = -6,
409 KM_ERROR_UNSUPPORTED_BLOCK_MODE = -7,
410 KM_ERROR_INCOMPATIBLE_BLOCK_MODE = -8,
411 KM_ERROR_UNSUPPORTED_MAC_LENGTH = -9,
412 KM_ERROR_UNSUPPORTED_PADDING_MODE = -10,
413 KM_ERROR_INCOMPATIBLE_PADDING_MODE = -11,
414 KM_ERROR_UNSUPPORTED_DIGEST = -12,
415 KM_ERROR_INCOMPATIBLE_DIGEST = -13,
416 KM_ERROR_INVALID_EXPIRATION_TIME = -14,
417 KM_ERROR_INVALID_USER_ID = -15,
418 KM_ERROR_INVALID_AUTHORIZATION_TIMEOUT = -16,
419 KM_ERROR_UNSUPPORTED_KEY_FORMAT = -17,
420 KM_ERROR_INCOMPATIBLE_KEY_FORMAT = -18,
421 KM_ERROR_UNSUPPORTED_KEY_ENCRYPTION_ALGORITHM = -19, /* For PKCS8 & PKCS12 */
422 KM_ERROR_UNSUPPORTED_KEY_VERIFICATION_ALGORITHM = -20, /* For PKCS8 & PKCS12 */
423 KM_ERROR_INVALID_INPUT_LENGTH = -21,
424 KM_ERROR_KEY_EXPORT_OPTIONS_INVALID = -22,
425 KM_ERROR_DELEGATION_NOT_ALLOWED = -23,
426 KM_ERROR_KEY_NOT_YET_VALID = -24,
427 KM_ERROR_KEY_EXPIRED = -25,
428 KM_ERROR_KEY_USER_NOT_AUTHENTICATED = -26,
429 KM_ERROR_OUTPUT_PARAMETER_NULL = -27,
430 KM_ERROR_INVALID_OPERATION_HANDLE = -28,
431 KM_ERROR_INSUFFICIENT_BUFFER_SPACE = -29,
432 KM_ERROR_VERIFICATION_FAILED = -30,
433 KM_ERROR_TOO_MANY_OPERATIONS = -31,
434 KM_ERROR_UNEXPECTED_NULL_POINTER = -32,
435 KM_ERROR_INVALID_KEY_BLOB = -33,
436 KM_ERROR_IMPORTED_KEY_NOT_ENCRYPTED = -34,
437 KM_ERROR_IMPORTED_KEY_DECRYPTION_FAILED = -35,
438 KM_ERROR_IMPORTED_KEY_NOT_SIGNED = -36,
439 KM_ERROR_IMPORTED_KEY_VERIFICATION_FAILED = -37,
440 KM_ERROR_INVALID_ARGUMENT = -38,
441 KM_ERROR_UNSUPPORTED_TAG = -39,
442 KM_ERROR_INVALID_TAG = -40,
443 KM_ERROR_MEMORY_ALLOCATION_FAILED = -41,
444 KM_ERROR_IMPORT_PARAMETER_MISMATCH = -44,
445 KM_ERROR_SECURE_HW_ACCESS_DENIED = -45,
446 KM_ERROR_OPERATION_CANCELLED = -46,
447 KM_ERROR_CONCURRENT_ACCESS_CONFLICT = -47,
448 KM_ERROR_SECURE_HW_BUSY = -48,
449 KM_ERROR_SECURE_HW_COMMUNICATION_FAILED = -49,
450 KM_ERROR_UNSUPPORTED_EC_FIELD = -50,
451 KM_ERROR_MISSING_NONCE = -51,
452 KM_ERROR_INVALID_NONCE = -52,
453 KM_ERROR_MISSING_MAC_LENGTH = -53,
454 KM_ERROR_KEY_RATE_LIMIT_EXCEEDED = -54,
455 KM_ERROR_CALLER_NONCE_PROHIBITED = -55,
456 KM_ERROR_KEY_MAX_OPS_EXCEEDED = -56,
457 KM_ERROR_INVALID_MAC_LENGTH = -57,
458 KM_ERROR_MISSING_MIN_MAC_LENGTH = -58,
459 KM_ERROR_UNSUPPORTED_MIN_MAC_LENGTH = -59,
460 KM_ERROR_UNSUPPORTED_KDF = -60,
461 KM_ERROR_UNSUPPORTED_EC_CURVE = -61,
462 KM_ERROR_KEY_REQUIRES_UPGRADE = -62,
463 KM_ERROR_ATTESTATION_CHALLENGE_MISSING = -63,
464 KM_ERROR_KEYMASTER_NOT_CONFIGURED = -64,
465 KM_ERROR_ATTESTATION_APPLICATION_ID_MISSING = -65,
466 KM_ERROR_CANNOT_ATTEST_IDS = -66,
467 KM_ERROR_ROLLBACK_RESISTANCE_UNAVAILABLE = -67,
468 KM_ERROR_NO_USER_CONFIRMATION = -71,
469 KM_ERROR_DEVICE_LOCKED = -72,
470 KM_ERROR_EARLY_BOOT_ENDED = -73,
471 KM_ERROR_ATTESTATION_KEYS_NOT_PROVISIONED = -74,
472 KM_ERROR_ATTESTATION_IDS_NOT_PROVISIONED = -75,
473
474 KM_ERROR_UNIMPLEMENTED = -100,
475 KM_ERROR_VERSION_MISMATCH = -101,
476
477 KM_ERROR_UNKNOWN_ERROR = -1000,
478 } keymaster_error_t;
479
480 /* Convenience functions for manipulating keymaster tag types */
481
keymaster_tag_get_type(keymaster_tag_t tag)482 static inline keymaster_tag_type_t keymaster_tag_get_type(keymaster_tag_t tag) {
483 return (keymaster_tag_type_t)(tag & (0xF << 28));
484 }
485
keymaster_tag_mask_type(keymaster_tag_t tag)486 static inline uint32_t keymaster_tag_mask_type(keymaster_tag_t tag) {
487 return tag & 0x0FFFFFFF;
488 }
489
keymaster_tag_type_repeatable(keymaster_tag_type_t type)490 static inline bool keymaster_tag_type_repeatable(keymaster_tag_type_t type) {
491 switch (type) {
492 case KM_UINT_REP:
493 case KM_ENUM_REP:
494 return true;
495 default:
496 return false;
497 }
498 }
499
keymaster_tag_repeatable(keymaster_tag_t tag)500 static inline bool keymaster_tag_repeatable(keymaster_tag_t tag) {
501 return keymaster_tag_type_repeatable(keymaster_tag_get_type(tag));
502 }
503
504 /* Convenience functions for manipulating keymaster_key_param_t structs */
505
keymaster_param_enum(keymaster_tag_t tag,uint32_t value)506 inline keymaster_key_param_t keymaster_param_enum(keymaster_tag_t tag, uint32_t value) {
507 // assert(keymaster_tag_get_type(tag) == KM_ENUM || keymaster_tag_get_type(tag) == KM_ENUM_REP);
508 keymaster_key_param_t param;
509 memset(¶m, 0, sizeof(param));
510 param.tag = tag;
511 param.enumerated = value;
512 return param;
513 }
514
keymaster_param_int(keymaster_tag_t tag,uint32_t value)515 inline keymaster_key_param_t keymaster_param_int(keymaster_tag_t tag, uint32_t value) {
516 // assert(keymaster_tag_get_type(tag) == KM_INT || keymaster_tag_get_type(tag) == KM_INT_REP);
517 keymaster_key_param_t param;
518 memset(¶m, 0, sizeof(param));
519 param.tag = tag;
520 param.integer = value;
521 return param;
522 }
523
keymaster_param_long(keymaster_tag_t tag,uint64_t value)524 inline keymaster_key_param_t keymaster_param_long(keymaster_tag_t tag, uint64_t value) {
525 // assert(keymaster_tag_get_type(tag) == KM_LONG);
526 keymaster_key_param_t param;
527 memset(¶m, 0, sizeof(param));
528 param.tag = tag;
529 param.long_integer = value;
530 return param;
531 }
532
keymaster_param_blob(keymaster_tag_t tag,const uint8_t * bytes,size_t bytes_len)533 inline keymaster_key_param_t keymaster_param_blob(keymaster_tag_t tag, const uint8_t* bytes,
534 size_t bytes_len) {
535 // assert(keymaster_tag_get_type(tag) == KM_BYTES || keymaster_tag_get_type(tag) == KM_BIGNUM);
536 keymaster_key_param_t param;
537 memset(¶m, 0, sizeof(param));
538 param.tag = tag;
539 param.blob.data = (uint8_t*)bytes;
540 param.blob.data_length = bytes_len;
541 return param;
542 }
543
keymaster_param_bool(keymaster_tag_t tag)544 inline keymaster_key_param_t keymaster_param_bool(keymaster_tag_t tag) {
545 // assert(keymaster_tag_get_type(tag) == KM_BOOL);
546 keymaster_key_param_t param;
547 memset(¶m, 0, sizeof(param));
548 param.tag = tag;
549 param.boolean = true;
550 return param;
551 }
552
keymaster_param_date(keymaster_tag_t tag,uint64_t value)553 inline keymaster_key_param_t keymaster_param_date(keymaster_tag_t tag, uint64_t value) {
554 // assert(keymaster_tag_get_type(tag) == KM_DATE);
555 keymaster_key_param_t param;
556 memset(¶m, 0, sizeof(param));
557 param.tag = tag;
558 param.date_time = value;
559 return param;
560 }
561
562 #define KEYMASTER_SIMPLE_COMPARE(a, b) (a < b) ? -1 : ((a > b) ? 1 : 0)
keymaster_param_compare(const keymaster_key_param_t * a,const keymaster_key_param_t * b)563 inline int keymaster_param_compare(const keymaster_key_param_t* a, const keymaster_key_param_t* b) {
564 int retval = KEYMASTER_SIMPLE_COMPARE((uint32_t)a->tag, (uint32_t)b->tag);
565 if (retval != 0)
566 return retval;
567
568 switch (keymaster_tag_get_type(a->tag)) {
569 case KM_INVALID:
570 case KM_BOOL:
571 return 0;
572 case KM_ENUM:
573 case KM_ENUM_REP:
574 return KEYMASTER_SIMPLE_COMPARE(a->enumerated, b->enumerated);
575 case KM_UINT:
576 case KM_UINT_REP:
577 return KEYMASTER_SIMPLE_COMPARE(a->integer, b->integer);
578 case KM_ULONG:
579 case KM_ULONG_REP:
580 return KEYMASTER_SIMPLE_COMPARE(a->long_integer, b->long_integer);
581 case KM_DATE:
582 return KEYMASTER_SIMPLE_COMPARE(a->date_time, b->date_time);
583 case KM_BIGNUM:
584 case KM_BYTES:
585 // Handle the empty cases.
586 if (a->blob.data_length != 0 && b->blob.data_length == 0)
587 return -1;
588 if (a->blob.data_length == 0 && b->blob.data_length == 0)
589 return 0;
590 if (a->blob.data_length == 0 && b->blob.data_length > 0)
591 return 1;
592
593 retval = memcmp(a->blob.data, b->blob.data, a->blob.data_length < b->blob.data_length
594 ? a->blob.data_length
595 : b->blob.data_length);
596 if (retval != 0)
597 return retval;
598 else if (a->blob.data_length != b->blob.data_length) {
599 // Equal up to the common length; longer one is larger.
600 if (a->blob.data_length < b->blob.data_length)
601 return -1;
602 if (a->blob.data_length > b->blob.data_length)
603 return 1;
604 }
605 }
606
607 return 0;
608 }
609 #undef KEYMASTER_SIMPLE_COMPARE
610
keymaster_free_param_values(keymaster_key_param_t * param,size_t param_count)611 inline void keymaster_free_param_values(keymaster_key_param_t* param, size_t param_count) {
612 while (param_count > 0) {
613 param_count--;
614 switch (keymaster_tag_get_type(param->tag)) {
615 case KM_BIGNUM:
616 case KM_BYTES:
617 free((void*)param->blob.data);
618 param->blob.data = NULL;
619 break;
620 default:
621 // NOP
622 break;
623 }
624 ++param;
625 }
626 }
627
keymaster_free_param_set(keymaster_key_param_set_t * set)628 inline void keymaster_free_param_set(keymaster_key_param_set_t* set) {
629 if (set) {
630 keymaster_free_param_values(set->params, set->length);
631 free(set->params);
632 set->params = NULL;
633 set->length = 0;
634 }
635 }
636
keymaster_free_characteristics(keymaster_key_characteristics_t * characteristics)637 inline void keymaster_free_characteristics(keymaster_key_characteristics_t* characteristics) {
638 if (characteristics) {
639 keymaster_free_param_set(&characteristics->hw_enforced);
640 keymaster_free_param_set(&characteristics->sw_enforced);
641 }
642 }
643
keymaster_free_cert_chain(keymaster_cert_chain_t * chain)644 inline void keymaster_free_cert_chain(keymaster_cert_chain_t* chain) {
645 if (chain) {
646 for (size_t i = 0; i < chain->entry_count; ++i) {
647 free((uint8_t*)chain->entries[i].data);
648 chain->entries[i].data = NULL;
649 chain->entries[i].data_length = 0;
650 }
651 free(chain->entries);
652 chain->entries = NULL;
653 chain->entry_count = 0;
654 }
655 }
656
657 #ifdef __cplusplus
658 } // extern "C"
659 #endif // __cplusplus
660
661 #endif // ANDROID_HARDWARE_KEYMASTER_DEFS_H
662