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