blob: d92ce007da6ae799db9c7da8f4b6e87ffd22e3d3 [file] [log] [blame]
Shawn Willden9d645a02014-06-12 13:48:46 -06001/*
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
Shawn Willden7eaa15f2015-06-03 09:03:20 -060024#ifdef __cplusplus
Shawn Willdenc51d01e2015-03-18 18:59:52 -060025extern "C" {
26#endif // __cplusplus
Shawn Willden9d645a02014-06-12 13:48:46 -060027
Shawn Willden9d645a02014-06-12 13:48:46 -060028/**
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 */
33typedef 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. */
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +000037 KM_UINT = 3 << 28,
38 KM_UINT_REP = 4 << 28, /* Repeatable integer value */
39 KM_ULONG = 5 << 28,
Shawn Willden9d645a02014-06-12 13:48:46 -060040 KM_DATE = 6 << 28,
41 KM_BOOL = 7 << 28,
42 KM_BIGNUM = 8 << 28,
43 KM_BYTES = 9 << 28,
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +000044 KM_ULONG_REP = 10 << 28, /* Repeatable long value */
Shawn Willden9d645a02014-06-12 13:48:46 -060045} keymaster_tag_type_t;
46
47typedef 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 */
Shawn Willdencf30fe12015-12-21 16:29:10 -070055 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) */
Shawn Willden9d645a02014-06-12 13:48:46 -060066
Shawn Willden9d645a02014-06-12 13:48:46 -060067 /* Algorithm-specific. */
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +000068 KM_TAG_RSA_PUBLIC_EXPONENT = KM_ULONG | 200,
Thai Duong40d59c82015-04-02 21:41:37 -070069 KM_TAG_ECIES_SINGLE_HASH_MODE = KM_BOOL | 201, /* Whether the ephemeral public key is fed into
Shawn Willdencf30fe12015-12-21 16:29:10 -070070 * 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) */
Shawn Willden9d645a02014-06-12 13:48:46 -060074
Shawn Willdenfb769fc2015-05-11 09:24:48 -060075 /* 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 */
Matthew Maurer581f6f72019-12-10 06:58:19 -080078 KM_TAG_ROLLBACK_RESISTANCE = KM_BOOL | 303, /* Hardware enforced deletion with deleteKey
79 * or deleteAllKeys is supported */
Shawn Willdenfb769fc2015-05-11 09:24:48 -060080
Shawn Willden9d645a02014-06-12 13:48:46 -060081 /*
82 * Tags that should be semantically enforced by hardware if possible and will otherwise be
83 * enforced by software (keystore).
84 */
85
86 /* Key validity period */
87 KM_TAG_ACTIVE_DATETIME = KM_DATE | 400, /* Start of validity */
88 KM_TAG_ORIGINATION_EXPIRE_DATETIME = KM_DATE | 401, /* Date when new "messages" should no
89 longer be created. */
90 KM_TAG_USAGE_EXPIRE_DATETIME = KM_DATE | 402, /* Date when existing "messages" should no
91 longer be trusted. */
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +000092 KM_TAG_MIN_SECONDS_BETWEEN_OPS = KM_UINT | 403, /* Minimum elapsed time between
Shawn Willden9d645a02014-06-12 13:48:46 -060093 cryptographic operations with the key. */
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +000094 KM_TAG_MAX_USES_PER_BOOT = KM_UINT | 404, /* Number of times the key can be used per
Shawn Willdendc0007b2015-01-23 01:01:21 -070095 boot. */
Shawn Willden9d645a02014-06-12 13:48:46 -060096
97 /* User authentication */
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +000098 KM_TAG_ALL_USERS = KM_BOOL | 500, /* Reserved for future use -- ignore */
99 KM_TAG_USER_ID = KM_UINT | 501, /* Reserved for future use -- ignore */
100 KM_TAG_USER_SECURE_ID = KM_ULONG_REP | 502, /* Secure ID of authorized user or authenticator(s).
101 Disallowed if KM_TAG_ALL_USERS or
102 KM_TAG_NO_AUTH_REQUIRED is present. */
103 KM_TAG_NO_AUTH_REQUIRED = KM_BOOL | 503, /* If key is usable without authentication. */
104 KM_TAG_USER_AUTH_TYPE = KM_ENUM | 504, /* Bitmask of authenticator types allowed when
105 * KM_TAG_USER_SECURE_ID contains a secure user ID,
106 * rather than a secure authenticator ID. Defined in
107 * hw_authenticator_type_t in hw_auth_token.h. */
108 KM_TAG_AUTH_TIMEOUT = KM_UINT | 505, /* Required freshness of user authentication for
109 private/secret key operations, in seconds.
110 Public key operations require no authentication.
111 If absent, authentication is required for every
112 use. Authentication state is lost when the
113 device is powered off. */
Shawn Willden71ca0102016-01-26 07:00:27 -0700114 KM_TAG_ALLOW_WHILE_ON_BODY = KM_BOOL | 506, /* Allow key to be used after authentication timeout
115 * if device is still on-body (requires secure
116 * on-body sensor. */
Matthew Maurer0b9dc0d2019-03-18 13:37:02 -0700117 KM_TAG_TRUSTED_CONFIRMATION_REQUIRED = KM_BOOL | 508, /* Require user confirmation through a
118 * trusted UI to use this key */
119 KM_TAG_UNLOCKED_DEVICE_REQUIRED = KM_BOOL | 509, /* Require the device screen to be unlocked if the
Brian Young8cf28622018-02-23 18:03:26 +0000120 * key is used. */
Shawn Willden9d645a02014-06-12 13:48:46 -0600121
122 /* Application access control */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700123 KM_TAG_ALL_APPLICATIONS = KM_BOOL | 600, /* Specified to indicate key is usable by all
124 * applications. */
125 KM_TAG_APPLICATION_ID = KM_BYTES | 601, /* Byte string identifying the authorized
126 * application. */
127 KM_TAG_EXPORTABLE = KM_BOOL | 602, /* If true, private/secret key can be exported, but
128 * only if all access control requirements for use are
129 * met. (keymaster2) */
Shawn Willden9d645a02014-06-12 13:48:46 -0600130
131 /*
132 * Semantically unenforceable tags, either because they have no specific meaning or because
133 * they're informational only.
134 */
Shawn Willden7fd11182016-02-03 07:39:40 -0700135 KM_TAG_APPLICATION_DATA = KM_BYTES | 700, /* Data provided by authorized application. */
136 KM_TAG_CREATION_DATETIME = KM_DATE | 701, /* Key creation time */
137 KM_TAG_ORIGIN = KM_ENUM | 702, /* keymaster_key_origin_t. */
138 KM_TAG_ROLLBACK_RESISTANT = KM_BOOL | 703, /* Whether key is rollback-resistant. */
139 KM_TAG_ROOT_OF_TRUST = KM_BYTES | 704, /* Root of trust ID. */
140 KM_TAG_OS_VERSION = KM_UINT | 705, /* Version of system (keymaster2) */
141 KM_TAG_OS_PATCHLEVEL = KM_UINT | 706, /* Patch level of system (keymaster2) */
142 KM_TAG_UNIQUE_ID = KM_BYTES | 707, /* Used to provide unique ID in attestation */
143 KM_TAG_ATTESTATION_CHALLENGE = KM_BYTES | 708, /* Used to provide challenge in attestation */
Janis Danisevskisb62995e2016-05-20 18:11:41 +0100144 KM_TAG_ATTESTATION_APPLICATION_ID = KM_BYTES | 709, /* Used to identify the set of possible
145 * applications of which one has initiated
146 * a key attestation */
Bartosz Fabianowski9d2f5b92017-01-23 15:36:42 +0100147 KM_TAG_ATTESTATION_ID_BRAND = KM_BYTES | 710, /* Used to provide the device's brand name to be
148 included in attestation */
149 KM_TAG_ATTESTATION_ID_DEVICE = KM_BYTES | 711, /* Used to provide the device's device name to be
150 included in attestation */
151 KM_TAG_ATTESTATION_ID_PRODUCT = KM_BYTES | 712, /* Used to provide the device's product name to
152 be included in attestation */
153 KM_TAG_ATTESTATION_ID_SERIAL = KM_BYTES | 713, /* Used to provide the device's serial number to
154 be included in attestation */
155 KM_TAG_ATTESTATION_ID_IMEI = KM_BYTES | 714, /* Used to provide the device's IMEI to be
156 included in attestation */
157 KM_TAG_ATTESTATION_ID_MEID = KM_BYTES | 715, /* Used to provide the device's MEID to be
158 included in attestation */
Bartosz Fabianowski81b7b5f2017-03-20 14:01:35 +0100159 KM_TAG_ATTESTATION_ID_MANUFACTURER = KM_BYTES | 716, /* Used to provide the device's
160 manufacturer name to be included in
161 attestation */
162 KM_TAG_ATTESTATION_ID_MODEL = KM_BYTES | 717, /* Used to provide the device's model name to be
163 included in attestation */
Shawn Willden9d645a02014-06-12 13:48:46 -0600164
Shawn Willden67ba9e82015-02-06 17:04:53 -0700165 /* Tags used only to provide data to or receive data from operations */
166 KM_TAG_ASSOCIATED_DATA = KM_BYTES | 1000, /* Used to provide associated data for AEAD modes. */
Shawn Willden41e91e92015-01-30 06:23:26 -0700167 KM_TAG_NONCE = KM_BYTES | 1001, /* Nonce or Initialization Vector */
Shawn Willdenda89dde2015-06-18 12:09:20 -0600168 KM_TAG_AUTH_TOKEN = KM_BYTES | 1002, /* Authentication token that proves secure user
Shawn Willdenc3ab05c2015-03-14 08:23:41 -0600169 authentication has been performed. Structure
170 defined in hw_auth_token_t in hw_auth_token.h. */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700171 KM_TAG_MAC_LENGTH = KM_UINT | 1003, /* MAC or AEAD authentication tag length in
172 * bits. */
173
174 KM_TAG_RESET_SINCE_ID_ROTATION = KM_BOOL | 1004, /* Whether the device has beeen factory reset
175 since the last unique ID rotation. Used for
176 key attestation. */
Shawn Willden9d645a02014-06-12 13:48:46 -0600177} keymaster_tag_t;
178
179/**
180 * Algorithms that may be provided by keymaster implementations. Those that must be provided by all
Shawn Willdenfd4b4d52015-02-24 09:17:38 -0700181 * implementations are tagged as "required".
Shawn Willden9d645a02014-06-12 13:48:46 -0600182 */
183typedef enum {
184 /* Asymmetric algorithms. */
Shawn Willdene9797a72015-04-07 13:39:12 -0600185 KM_ALGORITHM_RSA = 1,
186 // KM_ALGORITHM_DSA = 2, -- Removed, do not re-use value 2.
187 KM_ALGORITHM_EC = 3,
188
189 /* Block ciphers algorithms */
190 KM_ALGORITHM_AES = 32,
Shawn Willden2b557082018-01-09 06:55:15 -0700191 KM_ALGORITHM_TRIPLE_DES = 33,
Shawn Willdene9797a72015-04-07 13:39:12 -0600192
Shawn Willden9d645a02014-06-12 13:48:46 -0600193 /* MAC algorithms */
Shawn Willdene9797a72015-04-07 13:39:12 -0600194 KM_ALGORITHM_HMAC = 128,
Shawn Willden9d645a02014-06-12 13:48:46 -0600195} keymaster_algorithm_t;
196
197/**
Shawn Willdenc7deeda2015-04-07 13:40:00 -0600198 * Symmetric block cipher modes provided by keymaster implementations.
Shawn Willden9d645a02014-06-12 13:48:46 -0600199 */
200typedef enum {
201 /* Unauthenticated modes, usable only for encryption/decryption and not generally recommended
202 * except for compatibility with existing other protocols. */
Shawn Willden4c19a3a2015-06-01 11:40:24 -0600203 KM_MODE_ECB = 1,
Shawn Willdenc7deeda2015-04-07 13:40:00 -0600204 KM_MODE_CBC = 2,
Shawn Willden4c19a3a2015-06-01 11:40:24 -0600205 KM_MODE_CTR = 3,
Shawn Willdenc7deeda2015-04-07 13:40:00 -0600206
Shawn Willden9d645a02014-06-12 13:48:46 -0600207 /* Authenticated modes, usable for encryption/decryption and signing/verification. Recommended
Shawn Willdenc7deeda2015-04-07 13:40:00 -0600208 * over unauthenticated modes for all purposes. */
Shawn Willden4c19a3a2015-06-01 11:40:24 -0600209 KM_MODE_GCM = 32,
Shawn Willden9d645a02014-06-12 13:48:46 -0600210} keymaster_block_mode_t;
211
212/**
213 * Padding modes that may be applied to plaintext for encryption operations. This list includes
214 * padding modes for both symmetric and asymmetric algorithms. Note that implementations should not
215 * provide all possible combinations of algorithm and padding, only the
216 * cryptographically-appropriate pairs.
217 */
218typedef enum {
Shawn Willden8412fdc2015-04-07 13:41:30 -0600219 KM_PAD_NONE = 1, /* deprecated */
220 KM_PAD_RSA_OAEP = 2,
221 KM_PAD_RSA_PSS = 3,
Shawn Willden9d645a02014-06-12 13:48:46 -0600222 KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4,
223 KM_PAD_RSA_PKCS1_1_5_SIGN = 5,
Shawn Willden8412fdc2015-04-07 13:41:30 -0600224 KM_PAD_PKCS7 = 64,
Shawn Willden9d645a02014-06-12 13:48:46 -0600225} keymaster_padding_t;
226
227/**
Shawn Willdenfe6c4f02015-04-07 14:02:28 -0600228 * Digests provided by keymaster implementations.
Shawn Willden9d645a02014-06-12 13:48:46 -0600229 */
230typedef enum {
Shawn Willdenfe6c4f02015-04-07 14:02:28 -0600231 KM_DIGEST_NONE = 0,
232 KM_DIGEST_MD5 = 1, /* Optional, may not be implemented in hardware, will be handled in software
233 * if needed. */
234 KM_DIGEST_SHA1 = 2,
235 KM_DIGEST_SHA_2_224 = 3,
236 KM_DIGEST_SHA_2_256 = 4,
237 KM_DIGEST_SHA_2_384 = 5,
238 KM_DIGEST_SHA_2_512 = 6,
Shawn Willden9d645a02014-06-12 13:48:46 -0600239} keymaster_digest_t;
240
Thai Duong40d59c82015-04-02 21:41:37 -0700241/*
242 * Key derivation functions, mostly used in ECIES.
243 */
244typedef enum {
Shawn Willdencf30fe12015-12-21 16:29:10 -0700245 /* Do not apply a key derivation function; use the raw agreed key */
246 KM_KDF_NONE = 0,
Thai Duong40d59c82015-04-02 21:41:37 -0700247 /* HKDF defined in RFC 5869 with SHA256 */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700248 KM_KDF_RFC5869_SHA256 = 1,
Thai Duong40d59c82015-04-02 21:41:37 -0700249 /* KDF1 defined in ISO 18033-2 with SHA1 */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700250 KM_KDF_ISO18033_2_KDF1_SHA1 = 2,
Thai Duong40d59c82015-04-02 21:41:37 -0700251 /* KDF1 defined in ISO 18033-2 with SHA256 */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700252 KM_KDF_ISO18033_2_KDF1_SHA256 = 3,
Thai Duong40d59c82015-04-02 21:41:37 -0700253 /* KDF2 defined in ISO 18033-2 with SHA1 */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700254 KM_KDF_ISO18033_2_KDF2_SHA1 = 4,
Thai Duong40d59c82015-04-02 21:41:37 -0700255 /* KDF2 defined in ISO 18033-2 with SHA256 */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700256 KM_KDF_ISO18033_2_KDF2_SHA256 = 5,
Thai Duong40d59c82015-04-02 21:41:37 -0700257} keymaster_kdf_t;
258
259/**
260 * Supported EC curves, used in ECDSA/ECIES.
261 */
262typedef enum {
263 KM_EC_CURVE_P_224 = 0,
264 KM_EC_CURVE_P_256 = 1,
265 KM_EC_CURVE_P_384 = 2,
266 KM_EC_CURVE_P_521 = 3,
267} keymaster_ec_curve_t;
268
Shawn Willden9d645a02014-06-12 13:48:46 -0600269/**
Shawn Willden8d6cf252015-04-07 13:56:30 -0600270 * The origin of a key (or pair), i.e. where it was generated. Note that KM_TAG_ORIGIN can be found
271 * in either the hardware-enforced or software-enforced list for a key, indicating whether the key
272 * is hardware or software-based. Specifically, a key with KM_ORIGIN_GENERATED in the
273 * hardware-enforced list is guaranteed never to have existed outide the secure hardware.
Shawn Willden9d645a02014-06-12 13:48:46 -0600274 */
275typedef enum {
Shawn Willdencf30fe12015-12-21 16:29:10 -0700276 KM_ORIGIN_GENERATED = 0, /* Generated in keymaster. Should not exist outside the TEE. */
277 KM_ORIGIN_DERIVED = 1, /* Derived inside keymaster. Likely exists off-device. */
278 KM_ORIGIN_IMPORTED = 2, /* Imported into keymaster. Existed as cleartext in Android. */
Shawn Willdend359b042015-04-13 11:07:24 -0600279 KM_ORIGIN_UNKNOWN = 3, /* Keymaster did not record origin. This value can only be seen on
280 * keys in a keymaster0 implementation. The keymaster0 adapter uses
281 * this value to document the fact that it is unkown whether the key
282 * was generated inside or imported into keymaster. */
Shawn Willden9d645a02014-06-12 13:48:46 -0600283} keymaster_key_origin_t;
284
285/**
286 * Usability requirements of key blobs. This defines what system functionality must be available
287 * for the key to function. For example, key "blobs" which are actually handles referencing
288 * encrypted key material stored in the file system cannot be used until the file system is
289 * available, and should have BLOB_REQUIRES_FILE_SYSTEM. Other requirements entries will be added
Shawn Willdencf30fe12015-12-21 16:29:10 -0700290 * as needed for implementations.
Shawn Willden9d645a02014-06-12 13:48:46 -0600291 */
292typedef enum {
293 KM_BLOB_STANDALONE = 0,
294 KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
295} keymaster_key_blob_usage_requirements_t;
296
297/**
Shawn Willdencf30fe12015-12-21 16:29:10 -0700298 * Possible purposes of a key (or pair).
Shawn Willden9d645a02014-06-12 13:48:46 -0600299 */
300typedef enum {
Shawn Willdencf30fe12015-12-21 16:29:10 -0700301 KM_PURPOSE_ENCRYPT = 0, /* Usable with RSA, EC and AES keys. */
302 KM_PURPOSE_DECRYPT = 1, /* Usable with RSA, EC and AES keys. */
303 KM_PURPOSE_SIGN = 2, /* Usable with RSA, EC and HMAC keys. */
304 KM_PURPOSE_VERIFY = 3, /* Usable with RSA, EC and HMAC keys. */
305 KM_PURPOSE_DERIVE_KEY = 4, /* Usable with EC keys. */
Frank Salim343f3092017-10-05 21:58:47 -0700306 KM_PURPOSE_WRAP = 5, /* Usable with wrapped keys. */
307
Shawn Willden9d645a02014-06-12 13:48:46 -0600308} keymaster_purpose_t;
309
310typedef struct {
311 const uint8_t* data;
312 size_t data_length;
313} keymaster_blob_t;
314
315typedef struct {
316 keymaster_tag_t tag;
317 union {
318 uint32_t enumerated; /* KM_ENUM and KM_ENUM_REP */
319 bool boolean; /* KM_BOOL */
320 uint32_t integer; /* KM_INT and KM_INT_REP */
321 uint64_t long_integer; /* KM_LONG */
322 uint64_t date_time; /* KM_DATE */
323 keymaster_blob_t blob; /* KM_BIGNUM and KM_BYTES*/
324 };
325} keymaster_key_param_t;
326
327typedef struct {
328 keymaster_key_param_t* params; /* may be NULL if length == 0 */
329 size_t length;
330} keymaster_key_param_set_t;
331
332/**
333 * Parameters that define a key's characteristics, including authorized modes of usage and access
334 * control restrictions. The parameters are divided into two categories, those that are enforced by
335 * secure hardware, and those that are not. For a software-only keymaster implementation the
336 * enforced array must NULL. Hardware implementations must enforce everything in the enforced
337 * array.
338 */
339typedef struct {
340 keymaster_key_param_set_t hw_enforced;
341 keymaster_key_param_set_t sw_enforced;
342} keymaster_key_characteristics_t;
343
344typedef struct {
345 const uint8_t* key_material;
346 size_t key_material_size;
347} keymaster_key_blob_t;
348
Shawn Willdencf30fe12015-12-21 16:29:10 -0700349typedef struct {
350 keymaster_blob_t* entries;
351 size_t entry_count;
352} keymaster_cert_chain_t;
353
Shawn Willden30802762016-03-09 19:42:47 -0700354typedef enum {
355 KM_VERIFIED_BOOT_VERIFIED = 0, /* Full chain of trust extending from the bootloader to
356 * verified partitions, including the bootloader, boot
357 * partition, and all verified partitions*/
358 KM_VERIFIED_BOOT_SELF_SIGNED = 1, /* The boot partition has been verified using the embedded
359 * certificate, and the signature is valid. The bootloader
360 * displays a warning and the fingerprint of the public
361 * key before allowing the boot process to continue.*/
362 KM_VERIFIED_BOOT_UNVERIFIED = 2, /* The device may be freely modified. Device integrity is left
363 * to the user to verify out-of-band. The bootloader
364 * displays a warning to the user before allowing the boot
365 * process to continue */
366 KM_VERIFIED_BOOT_FAILED = 3, /* The device failed verification. The bootloader displays a
367 * warning and stops the boot process, so no keymaster
368 * implementation should ever actually return this value,
369 * since it should not run. Included here only for
370 * completeness. */
371} keymaster_verified_boot_t;
372
Shawn Willdenaeb15d62016-03-19 08:56:43 -0600373typedef enum {
374 KM_SECURITY_LEVEL_SOFTWARE = 0,
375 KM_SECURITY_LEVEL_TRUSTED_ENVIRONMENT = 1,
376} keymaster_security_level_t;
377
Shawn Willden9d645a02014-06-12 13:48:46 -0600378/**
Shawn Willdencf30fe12015-12-21 16:29:10 -0700379 * Formats for key import and export.
Shawn Willden9d645a02014-06-12 13:48:46 -0600380 */
381typedef enum {
Shawn Willdenfb769fc2015-05-11 09:24:48 -0600382 KM_KEY_FORMAT_X509 = 0, /* for public key export */
383 KM_KEY_FORMAT_PKCS8 = 1, /* for asymmetric key pair import */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700384 KM_KEY_FORMAT_RAW = 3, /* for symmetric key import and export*/
Shawn Willden9d645a02014-06-12 13:48:46 -0600385} keymaster_key_format_t;
386
387/**
388 * The keymaster operation API consists of begin, update, finish and abort. This is the type of the
389 * handle used to tie the sequence of calls together. A 64-bit value is used because it's important
390 * that handles not be predictable. Implementations must use strong random numbers for handle
391 * values.
392 */
393typedef uint64_t keymaster_operation_handle_t;
394
395typedef enum {
396 KM_ERROR_OK = 0,
397 KM_ERROR_ROOT_OF_TRUST_ALREADY_SET = -1,
398 KM_ERROR_UNSUPPORTED_PURPOSE = -2,
399 KM_ERROR_INCOMPATIBLE_PURPOSE = -3,
400 KM_ERROR_UNSUPPORTED_ALGORITHM = -4,
401 KM_ERROR_INCOMPATIBLE_ALGORITHM = -5,
402 KM_ERROR_UNSUPPORTED_KEY_SIZE = -6,
403 KM_ERROR_UNSUPPORTED_BLOCK_MODE = -7,
404 KM_ERROR_INCOMPATIBLE_BLOCK_MODE = -8,
Shawn Willden6b424be2015-01-26 13:04:28 -0700405 KM_ERROR_UNSUPPORTED_MAC_LENGTH = -9,
Shawn Willden9d645a02014-06-12 13:48:46 -0600406 KM_ERROR_UNSUPPORTED_PADDING_MODE = -10,
407 KM_ERROR_INCOMPATIBLE_PADDING_MODE = -11,
408 KM_ERROR_UNSUPPORTED_DIGEST = -12,
409 KM_ERROR_INCOMPATIBLE_DIGEST = -13,
410 KM_ERROR_INVALID_EXPIRATION_TIME = -14,
411 KM_ERROR_INVALID_USER_ID = -15,
412 KM_ERROR_INVALID_AUTHORIZATION_TIMEOUT = -16,
413 KM_ERROR_UNSUPPORTED_KEY_FORMAT = -17,
414 KM_ERROR_INCOMPATIBLE_KEY_FORMAT = -18,
415 KM_ERROR_UNSUPPORTED_KEY_ENCRYPTION_ALGORITHM = -19, /* For PKCS8 & PKCS12 */
416 KM_ERROR_UNSUPPORTED_KEY_VERIFICATION_ALGORITHM = -20, /* For PKCS8 & PKCS12 */
417 KM_ERROR_INVALID_INPUT_LENGTH = -21,
418 KM_ERROR_KEY_EXPORT_OPTIONS_INVALID = -22,
419 KM_ERROR_DELEGATION_NOT_ALLOWED = -23,
420 KM_ERROR_KEY_NOT_YET_VALID = -24,
421 KM_ERROR_KEY_EXPIRED = -25,
422 KM_ERROR_KEY_USER_NOT_AUTHENTICATED = -26,
423 KM_ERROR_OUTPUT_PARAMETER_NULL = -27,
424 KM_ERROR_INVALID_OPERATION_HANDLE = -28,
425 KM_ERROR_INSUFFICIENT_BUFFER_SPACE = -29,
426 KM_ERROR_VERIFICATION_FAILED = -30,
427 KM_ERROR_TOO_MANY_OPERATIONS = -31,
428 KM_ERROR_UNEXPECTED_NULL_POINTER = -32,
429 KM_ERROR_INVALID_KEY_BLOB = -33,
430 KM_ERROR_IMPORTED_KEY_NOT_ENCRYPTED = -34,
431 KM_ERROR_IMPORTED_KEY_DECRYPTION_FAILED = -35,
432 KM_ERROR_IMPORTED_KEY_NOT_SIGNED = -36,
433 KM_ERROR_IMPORTED_KEY_VERIFICATION_FAILED = -37,
434 KM_ERROR_INVALID_ARGUMENT = -38,
435 KM_ERROR_UNSUPPORTED_TAG = -39,
436 KM_ERROR_INVALID_TAG = -40,
437 KM_ERROR_MEMORY_ALLOCATION_FAILED = -41,
Shawn Willden9d645a02014-06-12 13:48:46 -0600438 KM_ERROR_IMPORT_PARAMETER_MISMATCH = -44,
439 KM_ERROR_SECURE_HW_ACCESS_DENIED = -45,
440 KM_ERROR_OPERATION_CANCELLED = -46,
441 KM_ERROR_CONCURRENT_ACCESS_CONFLICT = -47,
442 KM_ERROR_SECURE_HW_BUSY = -48,
443 KM_ERROR_SECURE_HW_COMMUNICATION_FAILED = -49,
444 KM_ERROR_UNSUPPORTED_EC_FIELD = -50,
Shawn Willdened941112015-03-11 21:53:59 -0600445 KM_ERROR_MISSING_NONCE = -51,
446 KM_ERROR_INVALID_NONCE = -52,
Shawn Willden4144c642015-06-01 11:40:34 -0600447 KM_ERROR_MISSING_MAC_LENGTH = -53,
Shawn Willden396d6cb2015-06-18 12:16:17 -0600448 KM_ERROR_KEY_RATE_LIMIT_EXCEEDED = -54,
Shawn Willden4bdd7cb2015-04-28 00:00:27 -0600449 KM_ERROR_CALLER_NONCE_PROHIBITED = -55,
Shawn Willden396d6cb2015-06-18 12:16:17 -0600450 KM_ERROR_KEY_MAX_OPS_EXCEEDED = -56,
Shawn Willdena3f0ab52015-07-08 06:04:52 -0600451 KM_ERROR_INVALID_MAC_LENGTH = -57,
452 KM_ERROR_MISSING_MIN_MAC_LENGTH = -58,
453 KM_ERROR_UNSUPPORTED_MIN_MAC_LENGTH = -59,
Thai Duong40d59c82015-04-02 21:41:37 -0700454 KM_ERROR_UNSUPPORTED_KDF = -60,
455 KM_ERROR_UNSUPPORTED_EC_CURVE = -61,
Shawn Willdencf30fe12015-12-21 16:29:10 -0700456 KM_ERROR_KEY_REQUIRES_UPGRADE = -62,
Shawn Willden7fd11182016-02-03 07:39:40 -0700457 KM_ERROR_ATTESTATION_CHALLENGE_MISSING = -63,
Shawn Willden30802762016-03-09 19:42:47 -0700458 KM_ERROR_KEYMASTER_NOT_CONFIGURED = -64,
Janis Danisevskis36966852016-06-01 13:39:09 -0700459 KM_ERROR_ATTESTATION_APPLICATION_ID_MISSING = -65,
Bartosz Fabianowski9d2f5b92017-01-23 15:36:42 +0100460 KM_ERROR_CANNOT_ATTEST_IDS = -66,
Matthew Maurer581f6f72019-12-10 06:58:19 -0800461 KM_ERROR_ROLLBACK_RESISTANCE_UNAVAILABLE = -67,
Matthew Maurer0b9dc0d2019-03-18 13:37:02 -0700462 KM_ERROR_NO_USER_CONFIRMATION = -71,
Brian Young8cf28622018-02-23 18:03:26 +0000463 KM_ERROR_DEVICE_LOCKED = -72,
Shawn Willdened941112015-03-11 21:53:59 -0600464
Shawn Willden9d645a02014-06-12 13:48:46 -0600465 KM_ERROR_UNIMPLEMENTED = -100,
466 KM_ERROR_VERSION_MISMATCH = -101,
467
Shawn Willden9d645a02014-06-12 13:48:46 -0600468 KM_ERROR_UNKNOWN_ERROR = -1000,
469} keymaster_error_t;
470
Shawn Willden9d645a02014-06-12 13:48:46 -0600471/* Convenience functions for manipulating keymaster tag types */
472
473static inline keymaster_tag_type_t keymaster_tag_get_type(keymaster_tag_t tag) {
474 return (keymaster_tag_type_t)(tag & (0xF << 28));
475}
476
477static inline uint32_t keymaster_tag_mask_type(keymaster_tag_t tag) {
478 return tag & 0x0FFFFFFF;
479}
480
481static inline bool keymaster_tag_type_repeatable(keymaster_tag_type_t type) {
482 switch (type) {
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +0000483 case KM_UINT_REP:
Shawn Willden9d645a02014-06-12 13:48:46 -0600484 case KM_ENUM_REP:
485 return true;
486 default:
487 return false;
488 }
489}
490
491static inline bool keymaster_tag_repeatable(keymaster_tag_t tag) {
492 return keymaster_tag_type_repeatable(keymaster_tag_get_type(tag));
493}
494
495/* Convenience functions for manipulating keymaster_key_param_t structs */
496
497inline keymaster_key_param_t keymaster_param_enum(keymaster_tag_t tag, uint32_t value) {
498 // assert(keymaster_tag_get_type(tag) == KM_ENUM || keymaster_tag_get_type(tag) == KM_ENUM_REP);
499 keymaster_key_param_t param;
500 memset(&param, 0, sizeof(param));
501 param.tag = tag;
502 param.enumerated = value;
503 return param;
504}
505
506inline keymaster_key_param_t keymaster_param_int(keymaster_tag_t tag, uint32_t value) {
507 // assert(keymaster_tag_get_type(tag) == KM_INT || keymaster_tag_get_type(tag) == KM_INT_REP);
508 keymaster_key_param_t param;
509 memset(&param, 0, sizeof(param));
510 param.tag = tag;
511 param.integer = value;
512 return param;
513}
514
515inline keymaster_key_param_t keymaster_param_long(keymaster_tag_t tag, uint64_t value) {
516 // assert(keymaster_tag_get_type(tag) == KM_LONG);
517 keymaster_key_param_t param;
518 memset(&param, 0, sizeof(param));
519 param.tag = tag;
520 param.long_integer = value;
521 return param;
522}
523
524inline keymaster_key_param_t keymaster_param_blob(keymaster_tag_t tag, const uint8_t* bytes,
525 size_t bytes_len) {
526 // assert(keymaster_tag_get_type(tag) == KM_BYTES || keymaster_tag_get_type(tag) == KM_BIGNUM);
527 keymaster_key_param_t param;
528 memset(&param, 0, sizeof(param));
529 param.tag = tag;
530 param.blob.data = (uint8_t*)bytes;
531 param.blob.data_length = bytes_len;
532 return param;
533}
534
535inline keymaster_key_param_t keymaster_param_bool(keymaster_tag_t tag) {
536 // assert(keymaster_tag_get_type(tag) == KM_BOOL);
537 keymaster_key_param_t param;
538 memset(&param, 0, sizeof(param));
539 param.tag = tag;
540 param.boolean = true;
541 return param;
542}
543
544inline keymaster_key_param_t keymaster_param_date(keymaster_tag_t tag, uint64_t value) {
545 // assert(keymaster_tag_get_type(tag) == KM_DATE);
546 keymaster_key_param_t param;
547 memset(&param, 0, sizeof(param));
548 param.tag = tag;
549 param.date_time = value;
550 return param;
551}
552
Shawn Willden67411d62015-03-04 10:00:38 -0700553#define KEYMASTER_SIMPLE_COMPARE(a, b) (a < b) ? -1 : ((a > b) ? 1 : 0)
554inline int keymaster_param_compare(const keymaster_key_param_t* a, const keymaster_key_param_t* b) {
Tucker Sylvestro28a872e2016-10-05 14:39:39 -0400555 int retval = KEYMASTER_SIMPLE_COMPARE((uint32_t)a->tag, (uint32_t)b->tag);
Shawn Willden67411d62015-03-04 10:00:38 -0700556 if (retval != 0)
557 return retval;
558
559 switch (keymaster_tag_get_type(a->tag)) {
560 case KM_INVALID:
561 case KM_BOOL:
562 return 0;
563 case KM_ENUM:
564 case KM_ENUM_REP:
565 return KEYMASTER_SIMPLE_COMPARE(a->enumerated, b->enumerated);
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +0000566 case KM_UINT:
567 case KM_UINT_REP:
Shawn Willden67411d62015-03-04 10:00:38 -0700568 return KEYMASTER_SIMPLE_COMPARE(a->integer, b->integer);
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +0000569 case KM_ULONG:
570 case KM_ULONG_REP:
Shawn Willden67411d62015-03-04 10:00:38 -0700571 return KEYMASTER_SIMPLE_COMPARE(a->long_integer, b->long_integer);
572 case KM_DATE:
573 return KEYMASTER_SIMPLE_COMPARE(a->date_time, b->date_time);
574 case KM_BIGNUM:
575 case KM_BYTES:
576 // Handle the empty cases.
577 if (a->blob.data_length != 0 && b->blob.data_length == 0)
578 return -1;
579 if (a->blob.data_length == 0 && b->blob.data_length == 0)
580 return 0;
581 if (a->blob.data_length == 0 && b->blob.data_length > 0)
582 return 1;
583
584 retval = memcmp(a->blob.data, b->blob.data, a->blob.data_length < b->blob.data_length
585 ? a->blob.data_length
586 : b->blob.data_length);
587 if (retval != 0)
588 return retval;
589 else if (a->blob.data_length != b->blob.data_length) {
590 // Equal up to the common length; longer one is larger.
591 if (a->blob.data_length < b->blob.data_length)
592 return -1;
593 if (a->blob.data_length > b->blob.data_length)
594 return 1;
Pirama Arumuga Nainare0dc1382019-01-15 10:31:39 -0800595 }
Shawn Willden67411d62015-03-04 10:00:38 -0700596 }
597
598 return 0;
599}
600#undef KEYMASTER_SIMPLE_COMPARE
601
Shawn Willden9d645a02014-06-12 13:48:46 -0600602inline void keymaster_free_param_values(keymaster_key_param_t* param, size_t param_count) {
Chad Brubakera3c0ae12015-08-12 12:46:44 -0700603 while (param_count > 0) {
604 param_count--;
Shawn Willden9d645a02014-06-12 13:48:46 -0600605 switch (keymaster_tag_get_type(param->tag)) {
606 case KM_BIGNUM:
607 case KM_BYTES:
608 free((void*)param->blob.data);
609 param->blob.data = NULL;
610 break;
611 default:
612 // NOP
613 break;
614 }
615 ++param;
616 }
617}
618
619inline void keymaster_free_param_set(keymaster_key_param_set_t* set) {
620 if (set) {
621 keymaster_free_param_values(set->params, set->length);
622 free(set->params);
623 set->params = NULL;
Shawn Willdene366efd2016-03-20 09:07:50 -0600624 set->length = 0;
Shawn Willden9d645a02014-06-12 13:48:46 -0600625 }
626}
627
628inline void keymaster_free_characteristics(keymaster_key_characteristics_t* characteristics) {
629 if (characteristics) {
630 keymaster_free_param_set(&characteristics->hw_enforced);
631 keymaster_free_param_set(&characteristics->sw_enforced);
632 }
633}
634
Shawn Willdencf30fe12015-12-21 16:29:10 -0700635inline void keymaster_free_cert_chain(keymaster_cert_chain_t* chain) {
636 if (chain) {
637 for (size_t i = 0; i < chain->entry_count; ++i) {
638 free((uint8_t*)chain->entries[i].data);
639 chain->entries[i].data = NULL;
640 chain->entries[i].data_length = 0;
641 }
642 free(chain->entries);
643 chain->entries = NULL;
644 chain->entry_count = 0;
645 }
646}
647
Shawn Willden7eaa15f2015-06-03 09:03:20 -0600648#ifdef __cplusplus
Shawn Willdenc51d01e2015-03-18 18:59:52 -0600649} // extern "C"
650#endif // __cplusplus
Shawn Willden9d645a02014-06-12 13:48:46 -0600651
652#endif // ANDROID_HARDWARE_KEYMASTER_DEFS_H