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