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