blob: 5d29a243c31d40f2a19738fc3fb0c44678f028a4 [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) */
Chirag Pathak39fd3062020-12-21 18:44:53 -050074 KM_TAG_RSA_OAEP_MGF_DIGEST = KM_ENUM_REP | 203, /* keymaster_digest_t. */
Shawn Willden9d645a02014-06-12 13:48:46 -060075
Shawn Willdenfb769fc2015-05-11 09:24:48 -060076 /* 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 */
Matthew Maurer581f6f72019-12-10 06:58:19 -080079 KM_TAG_ROLLBACK_RESISTANCE = KM_BOOL | 303, /* Hardware enforced deletion with deleteKey
80 * or deleteAllKeys is supported */
Shawn Willdene59d5b12020-01-15 17:52:53 -070081 KM_TAG_EARLY_BOOT_ONLY = KM_BOOL | 305, /* Key can only be used during early boot. */
Shawn Willdenfb769fc2015-05-11 09:24:48 -060082
Shawn Willden9d645a02014-06-12 13:48:46 -060083 /*
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. */
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +000094 KM_TAG_MIN_SECONDS_BETWEEN_OPS = KM_UINT | 403, /* Minimum elapsed time between
Shawn Willden9d645a02014-06-12 13:48:46 -060095 cryptographic operations with the key. */
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +000096 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 -070097 boot. */
Shawn Willden9d645a02014-06-12 13:48:46 -060098
99 /* User authentication */
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +0000100 KM_TAG_ALL_USERS = KM_BOOL | 500, /* Reserved for future use -- ignore */
101 KM_TAG_USER_ID = KM_UINT | 501, /* Reserved for future use -- ignore */
102 KM_TAG_USER_SECURE_ID = KM_ULONG_REP | 502, /* Secure ID of authorized user or authenticator(s).
103 Disallowed if KM_TAG_ALL_USERS or
104 KM_TAG_NO_AUTH_REQUIRED is present. */
105 KM_TAG_NO_AUTH_REQUIRED = KM_BOOL | 503, /* If key is usable without authentication. */
106 KM_TAG_USER_AUTH_TYPE = KM_ENUM | 504, /* Bitmask of authenticator types allowed when
107 * KM_TAG_USER_SECURE_ID contains a secure user ID,
108 * rather than a secure authenticator ID. Defined in
109 * hw_authenticator_type_t in hw_auth_token.h. */
110 KM_TAG_AUTH_TIMEOUT = KM_UINT | 505, /* Required freshness of user authentication for
111 private/secret key operations, in seconds.
112 Public key operations require no authentication.
113 If absent, authentication is required for every
114 use. Authentication state is lost when the
115 device is powered off. */
Shawn Willden71ca0102016-01-26 07:00:27 -0700116 KM_TAG_ALLOW_WHILE_ON_BODY = KM_BOOL | 506, /* Allow key to be used after authentication timeout
117 * if device is still on-body (requires secure
118 * on-body sensor. */
Selene Huang5d3c1ec2020-08-27 01:58:04 -0700119 KM_TAG_TRUSTED_USER_PRESENCE_REQUIRED = KM_BOOL | 507,/* Require test of user presence
120 * to use this key. */
Matthew Maurer0b9dc0d2019-03-18 13:37:02 -0700121 KM_TAG_TRUSTED_CONFIRMATION_REQUIRED = KM_BOOL | 508, /* Require user confirmation through a
Selene Huang5d3c1ec2020-08-27 01:58:04 -0700122 * trusted UI to use this key. */
Matthew Maurer0b9dc0d2019-03-18 13:37:02 -0700123 KM_TAG_UNLOCKED_DEVICE_REQUIRED = KM_BOOL | 509, /* Require the device screen to be unlocked if the
Brian Young8cf28622018-02-23 18:03:26 +0000124 * key is used. */
Shawn Willden9d645a02014-06-12 13:48:46 -0600125
126 /* Application access control */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700127 KM_TAG_ALL_APPLICATIONS = KM_BOOL | 600, /* Specified to indicate key is usable by all
128 * applications. */
129 KM_TAG_APPLICATION_ID = KM_BYTES | 601, /* Byte string identifying the authorized
130 * application. */
131 KM_TAG_EXPORTABLE = KM_BOOL | 602, /* If true, private/secret key can be exported, but
132 * only if all access control requirements for use are
133 * met. (keymaster2) */
Shawn Willden9d645a02014-06-12 13:48:46 -0600134
135 /*
136 * Semantically unenforceable tags, either because they have no specific meaning or because
137 * they're informational only.
138 */
Shawn Willden7fd11182016-02-03 07:39:40 -0700139 KM_TAG_APPLICATION_DATA = KM_BYTES | 700, /* Data provided by authorized application. */
140 KM_TAG_CREATION_DATETIME = KM_DATE | 701, /* Key creation time */
141 KM_TAG_ORIGIN = KM_ENUM | 702, /* keymaster_key_origin_t. */
142 KM_TAG_ROLLBACK_RESISTANT = KM_BOOL | 703, /* Whether key is rollback-resistant. */
143 KM_TAG_ROOT_OF_TRUST = KM_BYTES | 704, /* Root of trust ID. */
144 KM_TAG_OS_VERSION = KM_UINT | 705, /* Version of system (keymaster2) */
145 KM_TAG_OS_PATCHLEVEL = KM_UINT | 706, /* Patch level of system (keymaster2) */
146 KM_TAG_UNIQUE_ID = KM_BYTES | 707, /* Used to provide unique ID in attestation */
147 KM_TAG_ATTESTATION_CHALLENGE = KM_BYTES | 708, /* Used to provide challenge in attestation */
Janis Danisevskisb62995e2016-05-20 18:11:41 +0100148 KM_TAG_ATTESTATION_APPLICATION_ID = KM_BYTES | 709, /* Used to identify the set of possible
149 * applications of which one has initiated
150 * a key attestation */
Bartosz Fabianowski9d2f5b92017-01-23 15:36:42 +0100151 KM_TAG_ATTESTATION_ID_BRAND = KM_BYTES | 710, /* Used to provide the device's brand name to be
152 included in attestation */
153 KM_TAG_ATTESTATION_ID_DEVICE = KM_BYTES | 711, /* Used to provide the device's device name to be
154 included in attestation */
155 KM_TAG_ATTESTATION_ID_PRODUCT = KM_BYTES | 712, /* Used to provide the device's product name to
156 be included in attestation */
157 KM_TAG_ATTESTATION_ID_SERIAL = KM_BYTES | 713, /* Used to provide the device's serial number to
158 be included in attestation */
159 KM_TAG_ATTESTATION_ID_IMEI = KM_BYTES | 714, /* Used to provide the device's IMEI to be
160 included in attestation */
161 KM_TAG_ATTESTATION_ID_MEID = KM_BYTES | 715, /* Used to provide the device's MEID to be
162 included in attestation */
Bartosz Fabianowski81b7b5f2017-03-20 14:01:35 +0100163 KM_TAG_ATTESTATION_ID_MANUFACTURER = KM_BYTES | 716, /* Used to provide the device's
164 manufacturer name to be included in
165 attestation */
166 KM_TAG_ATTESTATION_ID_MODEL = KM_BYTES | 717, /* Used to provide the device's model name to be
167 included in attestation */
Selene Huang5d3c1ec2020-08-27 01:58:04 -0700168 KM_TAG_VENDOR_PATCHLEVEL = KM_UINT | 718, /* specifies the vendor image security patch
169 level with which the key may be used */
170 KM_TAG_BOOT_PATCHLEVEL = KM_UINT | 719, /* specifies the boot image (kernel) security
171 patch level with which the key may be used */
172 KM_TAG_DEVICE_UNIQUE_ATTESTATION = KM_BOOL | 720, /* Indicates StrongBox device-unique
173 attestation is requested. */
Selene Huang79a5bd62020-02-13 13:11:20 -0800174 KM_TAG_IDENTITY_CREDENTIAL_KEY = KM_BOOL | 721, /* This is an identity credential key */
Selene Huang5d3c1ec2020-08-27 01:58:04 -0700175 KM_TAG_STORAGE_KEY = KM_BOOL | 722, /* storage encryption key */
Shawn Willden9d645a02014-06-12 13:48:46 -0600176
Shawn Willden67ba9e82015-02-06 17:04:53 -0700177 /* Tags used only to provide data to or receive data from operations */
178 KM_TAG_ASSOCIATED_DATA = KM_BYTES | 1000, /* Used to provide associated data for AEAD modes. */
Shawn Willden41e91e92015-01-30 06:23:26 -0700179 KM_TAG_NONCE = KM_BYTES | 1001, /* Nonce or Initialization Vector */
Shawn Willdenda89dde2015-06-18 12:09:20 -0600180 KM_TAG_AUTH_TOKEN = KM_BYTES | 1002, /* Authentication token that proves secure user
Shawn Willdenc3ab05c2015-03-14 08:23:41 -0600181 authentication has been performed. Structure
182 defined in hw_auth_token_t in hw_auth_token.h. */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700183 KM_TAG_MAC_LENGTH = KM_UINT | 1003, /* MAC or AEAD authentication tag length in
184 * bits. */
185
186 KM_TAG_RESET_SINCE_ID_ROTATION = KM_BOOL | 1004, /* Whether the device has beeen factory reset
Selene Huang5d3c1ec2020-08-27 01:58:04 -0700187 since the last unique ID rotation. Used
188 for key attestation. */
189
190 KM_TAG_CONFIRMATION_TOKEN = KM_BYTES | 1005, /* used to deliver a cryptographic token
191 proving that the user confirmed a signing
192 request. */
Selene Huangd7dcd782020-08-27 01:58:04 -0700193
194 KM_TAG_CERTIFICATE_SERIAL = KM_UINT | 1006, /* The serial number that should be
195 set in the attestation certificate
196 to be generated. */
197
198 KM_TAG_CERTIFICATE_SUBJECT = KM_BYTES | 1007, /* A DER-encoded X.500 subject that should be
199 set in the attestation certificate
200 to be generated. */
201
202
Shawn Willden9d645a02014-06-12 13:48:46 -0600203} keymaster_tag_t;
204
205/**
206 * Algorithms that may be provided by keymaster implementations. Those that must be provided by all
Shawn Willdenfd4b4d52015-02-24 09:17:38 -0700207 * implementations are tagged as "required".
Shawn Willden9d645a02014-06-12 13:48:46 -0600208 */
209typedef enum {
210 /* Asymmetric algorithms. */
Shawn Willdene9797a72015-04-07 13:39:12 -0600211 KM_ALGORITHM_RSA = 1,
212 // KM_ALGORITHM_DSA = 2, -- Removed, do not re-use value 2.
213 KM_ALGORITHM_EC = 3,
214
215 /* Block ciphers algorithms */
216 KM_ALGORITHM_AES = 32,
Shawn Willden2b557082018-01-09 06:55:15 -0700217 KM_ALGORITHM_TRIPLE_DES = 33,
Shawn Willdene9797a72015-04-07 13:39:12 -0600218
Shawn Willden9d645a02014-06-12 13:48:46 -0600219 /* MAC algorithms */
Shawn Willdene9797a72015-04-07 13:39:12 -0600220 KM_ALGORITHM_HMAC = 128,
Shawn Willden9d645a02014-06-12 13:48:46 -0600221} keymaster_algorithm_t;
222
223/**
Shawn Willdenc7deeda2015-04-07 13:40:00 -0600224 * Symmetric block cipher modes provided by keymaster implementations.
Shawn Willden9d645a02014-06-12 13:48:46 -0600225 */
226typedef enum {
227 /* Unauthenticated modes, usable only for encryption/decryption and not generally recommended
228 * except for compatibility with existing other protocols. */
Shawn Willden4c19a3a2015-06-01 11:40:24 -0600229 KM_MODE_ECB = 1,
Shawn Willdenc7deeda2015-04-07 13:40:00 -0600230 KM_MODE_CBC = 2,
Shawn Willden4c19a3a2015-06-01 11:40:24 -0600231 KM_MODE_CTR = 3,
Shawn Willdenc7deeda2015-04-07 13:40:00 -0600232
Shawn Willden9d645a02014-06-12 13:48:46 -0600233 /* Authenticated modes, usable for encryption/decryption and signing/verification. Recommended
Shawn Willdenc7deeda2015-04-07 13:40:00 -0600234 * over unauthenticated modes for all purposes. */
Shawn Willden4c19a3a2015-06-01 11:40:24 -0600235 KM_MODE_GCM = 32,
Shawn Willden9d645a02014-06-12 13:48:46 -0600236} keymaster_block_mode_t;
237
238/**
239 * Padding modes that may be applied to plaintext for encryption operations. This list includes
240 * padding modes for both symmetric and asymmetric algorithms. Note that implementations should not
241 * provide all possible combinations of algorithm and padding, only the
242 * cryptographically-appropriate pairs.
243 */
244typedef enum {
Shawn Willden8412fdc2015-04-07 13:41:30 -0600245 KM_PAD_NONE = 1, /* deprecated */
246 KM_PAD_RSA_OAEP = 2,
247 KM_PAD_RSA_PSS = 3,
Shawn Willden9d645a02014-06-12 13:48:46 -0600248 KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4,
249 KM_PAD_RSA_PKCS1_1_5_SIGN = 5,
Shawn Willden8412fdc2015-04-07 13:41:30 -0600250 KM_PAD_PKCS7 = 64,
Shawn Willden9d645a02014-06-12 13:48:46 -0600251} keymaster_padding_t;
252
253/**
Shawn Willdenfe6c4f02015-04-07 14:02:28 -0600254 * Digests provided by keymaster implementations.
Shawn Willden9d645a02014-06-12 13:48:46 -0600255 */
256typedef enum {
Shawn Willdenfe6c4f02015-04-07 14:02:28 -0600257 KM_DIGEST_NONE = 0,
258 KM_DIGEST_MD5 = 1, /* Optional, may not be implemented in hardware, will be handled in software
259 * if needed. */
260 KM_DIGEST_SHA1 = 2,
261 KM_DIGEST_SHA_2_224 = 3,
262 KM_DIGEST_SHA_2_256 = 4,
263 KM_DIGEST_SHA_2_384 = 5,
264 KM_DIGEST_SHA_2_512 = 6,
Shawn Willden9d645a02014-06-12 13:48:46 -0600265} keymaster_digest_t;
266
Thai Duong40d59c82015-04-02 21:41:37 -0700267/*
268 * Key derivation functions, mostly used in ECIES.
269 */
270typedef enum {
Shawn Willdencf30fe12015-12-21 16:29:10 -0700271 /* Do not apply a key derivation function; use the raw agreed key */
272 KM_KDF_NONE = 0,
Thai Duong40d59c82015-04-02 21:41:37 -0700273 /* HKDF defined in RFC 5869 with SHA256 */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700274 KM_KDF_RFC5869_SHA256 = 1,
Thai Duong40d59c82015-04-02 21:41:37 -0700275 /* KDF1 defined in ISO 18033-2 with SHA1 */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700276 KM_KDF_ISO18033_2_KDF1_SHA1 = 2,
Thai Duong40d59c82015-04-02 21:41:37 -0700277 /* KDF1 defined in ISO 18033-2 with SHA256 */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700278 KM_KDF_ISO18033_2_KDF1_SHA256 = 3,
Thai Duong40d59c82015-04-02 21:41:37 -0700279 /* KDF2 defined in ISO 18033-2 with SHA1 */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700280 KM_KDF_ISO18033_2_KDF2_SHA1 = 4,
Thai Duong40d59c82015-04-02 21:41:37 -0700281 /* KDF2 defined in ISO 18033-2 with SHA256 */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700282 KM_KDF_ISO18033_2_KDF2_SHA256 = 5,
Thai Duong40d59c82015-04-02 21:41:37 -0700283} keymaster_kdf_t;
284
285/**
286 * Supported EC curves, used in ECDSA/ECIES.
287 */
288typedef enum {
289 KM_EC_CURVE_P_224 = 0,
290 KM_EC_CURVE_P_256 = 1,
291 KM_EC_CURVE_P_384 = 2,
292 KM_EC_CURVE_P_521 = 3,
293} keymaster_ec_curve_t;
294
Shawn Willden9d645a02014-06-12 13:48:46 -0600295/**
Shawn Willden8d6cf252015-04-07 13:56:30 -0600296 * The origin of a key (or pair), i.e. where it was generated. Note that KM_TAG_ORIGIN can be found
297 * in either the hardware-enforced or software-enforced list for a key, indicating whether the key
298 * is hardware or software-based. Specifically, a key with KM_ORIGIN_GENERATED in the
299 * hardware-enforced list is guaranteed never to have existed outide the secure hardware.
Shawn Willden9d645a02014-06-12 13:48:46 -0600300 */
301typedef enum {
Shawn Willdencf30fe12015-12-21 16:29:10 -0700302 KM_ORIGIN_GENERATED = 0, /* Generated in keymaster. Should not exist outside the TEE. */
303 KM_ORIGIN_DERIVED = 1, /* Derived inside keymaster. Likely exists off-device. */
304 KM_ORIGIN_IMPORTED = 2, /* Imported into keymaster. Existed as cleartext in Android. */
Shawn Willdend359b042015-04-13 11:07:24 -0600305 KM_ORIGIN_UNKNOWN = 3, /* Keymaster did not record origin. This value can only be seen on
306 * keys in a keymaster0 implementation. The keymaster0 adapter uses
307 * this value to document the fact that it is unkown whether the key
308 * was generated inside or imported into keymaster. */
Shawn Willden9d645a02014-06-12 13:48:46 -0600309} keymaster_key_origin_t;
310
311/**
312 * Usability requirements of key blobs. This defines what system functionality must be available
313 * for the key to function. For example, key "blobs" which are actually handles referencing
314 * encrypted key material stored in the file system cannot be used until the file system is
315 * available, and should have BLOB_REQUIRES_FILE_SYSTEM. Other requirements entries will be added
Shawn Willdencf30fe12015-12-21 16:29:10 -0700316 * as needed for implementations.
Shawn Willden9d645a02014-06-12 13:48:46 -0600317 */
318typedef enum {
319 KM_BLOB_STANDALONE = 0,
320 KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
321} keymaster_key_blob_usage_requirements_t;
322
323/**
Shawn Willdencf30fe12015-12-21 16:29:10 -0700324 * Possible purposes of a key (or pair).
Shawn Willden9d645a02014-06-12 13:48:46 -0600325 */
326typedef enum {
Shawn Willdencf30fe12015-12-21 16:29:10 -0700327 KM_PURPOSE_ENCRYPT = 0, /* Usable with RSA, EC and AES keys. */
328 KM_PURPOSE_DECRYPT = 1, /* Usable with RSA, EC and AES keys. */
329 KM_PURPOSE_SIGN = 2, /* Usable with RSA, EC and HMAC keys. */
330 KM_PURPOSE_VERIFY = 3, /* Usable with RSA, EC and HMAC keys. */
331 KM_PURPOSE_DERIVE_KEY = 4, /* Usable with EC keys. */
Frank Salim343f3092017-10-05 21:58:47 -0700332 KM_PURPOSE_WRAP = 5, /* Usable with wrapped keys. */
David Zeuthen3107e472021-01-25 13:09:36 -0500333 KM_PURPOSE_AGREE_KEY = 6, /* Usable with EC keys. */
Frank Salim343f3092017-10-05 21:58:47 -0700334
Shawn Willden9d645a02014-06-12 13:48:46 -0600335} keymaster_purpose_t;
336
337typedef struct {
338 const uint8_t* data;
339 size_t data_length;
340} keymaster_blob_t;
341
342typedef struct {
343 keymaster_tag_t tag;
344 union {
345 uint32_t enumerated; /* KM_ENUM and KM_ENUM_REP */
346 bool boolean; /* KM_BOOL */
347 uint32_t integer; /* KM_INT and KM_INT_REP */
348 uint64_t long_integer; /* KM_LONG */
349 uint64_t date_time; /* KM_DATE */
350 keymaster_blob_t blob; /* KM_BIGNUM and KM_BYTES*/
351 };
352} keymaster_key_param_t;
353
354typedef struct {
355 keymaster_key_param_t* params; /* may be NULL if length == 0 */
356 size_t length;
357} keymaster_key_param_set_t;
358
359/**
360 * Parameters that define a key's characteristics, including authorized modes of usage and access
361 * control restrictions. The parameters are divided into two categories, those that are enforced by
362 * secure hardware, and those that are not. For a software-only keymaster implementation the
363 * enforced array must NULL. Hardware implementations must enforce everything in the enforced
364 * array.
365 */
366typedef struct {
367 keymaster_key_param_set_t hw_enforced;
368 keymaster_key_param_set_t sw_enforced;
369} keymaster_key_characteristics_t;
370
371typedef struct {
372 const uint8_t* key_material;
373 size_t key_material_size;
374} keymaster_key_blob_t;
375
Shawn Willdencf30fe12015-12-21 16:29:10 -0700376typedef struct {
377 keymaster_blob_t* entries;
378 size_t entry_count;
379} keymaster_cert_chain_t;
380
Shawn Willden30802762016-03-09 19:42:47 -0700381typedef enum {
382 KM_VERIFIED_BOOT_VERIFIED = 0, /* Full chain of trust extending from the bootloader to
383 * verified partitions, including the bootloader, boot
384 * partition, and all verified partitions*/
385 KM_VERIFIED_BOOT_SELF_SIGNED = 1, /* The boot partition has been verified using the embedded
386 * certificate, and the signature is valid. The bootloader
387 * displays a warning and the fingerprint of the public
388 * key before allowing the boot process to continue.*/
389 KM_VERIFIED_BOOT_UNVERIFIED = 2, /* The device may be freely modified. Device integrity is left
390 * to the user to verify out-of-band. The bootloader
391 * displays a warning to the user before allowing the boot
392 * process to continue */
393 KM_VERIFIED_BOOT_FAILED = 3, /* The device failed verification. The bootloader displays a
394 * warning and stops the boot process, so no keymaster
395 * implementation should ever actually return this value,
396 * since it should not run. Included here only for
397 * completeness. */
398} keymaster_verified_boot_t;
399
Shawn Willdenaeb15d62016-03-19 08:56:43 -0600400typedef enum {
401 KM_SECURITY_LEVEL_SOFTWARE = 0,
402 KM_SECURITY_LEVEL_TRUSTED_ENVIRONMENT = 1,
Shawn Willdene59d5b12020-01-15 17:52:53 -0700403 KM_SECURITY_LEVEL_STRONGBOX = 2,
Shawn Willdenaeb15d62016-03-19 08:56:43 -0600404} keymaster_security_level_t;
405
Shawn Willden9d645a02014-06-12 13:48:46 -0600406/**
Shawn Willdencf30fe12015-12-21 16:29:10 -0700407 * Formats for key import and export.
Shawn Willden9d645a02014-06-12 13:48:46 -0600408 */
409typedef enum {
Shawn Willdenfb769fc2015-05-11 09:24:48 -0600410 KM_KEY_FORMAT_X509 = 0, /* for public key export */
411 KM_KEY_FORMAT_PKCS8 = 1, /* for asymmetric key pair import */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700412 KM_KEY_FORMAT_RAW = 3, /* for symmetric key import and export*/
Shawn Willden9d645a02014-06-12 13:48:46 -0600413} keymaster_key_format_t;
414
415/**
416 * The keymaster operation API consists of begin, update, finish and abort. This is the type of the
417 * handle used to tie the sequence of calls together. A 64-bit value is used because it's important
418 * that handles not be predictable. Implementations must use strong random numbers for handle
419 * values.
420 */
421typedef uint64_t keymaster_operation_handle_t;
422
423typedef enum {
424 KM_ERROR_OK = 0,
425 KM_ERROR_ROOT_OF_TRUST_ALREADY_SET = -1,
426 KM_ERROR_UNSUPPORTED_PURPOSE = -2,
427 KM_ERROR_INCOMPATIBLE_PURPOSE = -3,
428 KM_ERROR_UNSUPPORTED_ALGORITHM = -4,
429 KM_ERROR_INCOMPATIBLE_ALGORITHM = -5,
430 KM_ERROR_UNSUPPORTED_KEY_SIZE = -6,
431 KM_ERROR_UNSUPPORTED_BLOCK_MODE = -7,
432 KM_ERROR_INCOMPATIBLE_BLOCK_MODE = -8,
Shawn Willden6b424be2015-01-26 13:04:28 -0700433 KM_ERROR_UNSUPPORTED_MAC_LENGTH = -9,
Shawn Willden9d645a02014-06-12 13:48:46 -0600434 KM_ERROR_UNSUPPORTED_PADDING_MODE = -10,
435 KM_ERROR_INCOMPATIBLE_PADDING_MODE = -11,
436 KM_ERROR_UNSUPPORTED_DIGEST = -12,
437 KM_ERROR_INCOMPATIBLE_DIGEST = -13,
438 KM_ERROR_INVALID_EXPIRATION_TIME = -14,
439 KM_ERROR_INVALID_USER_ID = -15,
440 KM_ERROR_INVALID_AUTHORIZATION_TIMEOUT = -16,
441 KM_ERROR_UNSUPPORTED_KEY_FORMAT = -17,
442 KM_ERROR_INCOMPATIBLE_KEY_FORMAT = -18,
443 KM_ERROR_UNSUPPORTED_KEY_ENCRYPTION_ALGORITHM = -19, /* For PKCS8 & PKCS12 */
444 KM_ERROR_UNSUPPORTED_KEY_VERIFICATION_ALGORITHM = -20, /* For PKCS8 & PKCS12 */
445 KM_ERROR_INVALID_INPUT_LENGTH = -21,
446 KM_ERROR_KEY_EXPORT_OPTIONS_INVALID = -22,
447 KM_ERROR_DELEGATION_NOT_ALLOWED = -23,
448 KM_ERROR_KEY_NOT_YET_VALID = -24,
449 KM_ERROR_KEY_EXPIRED = -25,
450 KM_ERROR_KEY_USER_NOT_AUTHENTICATED = -26,
451 KM_ERROR_OUTPUT_PARAMETER_NULL = -27,
452 KM_ERROR_INVALID_OPERATION_HANDLE = -28,
453 KM_ERROR_INSUFFICIENT_BUFFER_SPACE = -29,
454 KM_ERROR_VERIFICATION_FAILED = -30,
455 KM_ERROR_TOO_MANY_OPERATIONS = -31,
456 KM_ERROR_UNEXPECTED_NULL_POINTER = -32,
457 KM_ERROR_INVALID_KEY_BLOB = -33,
458 KM_ERROR_IMPORTED_KEY_NOT_ENCRYPTED = -34,
459 KM_ERROR_IMPORTED_KEY_DECRYPTION_FAILED = -35,
460 KM_ERROR_IMPORTED_KEY_NOT_SIGNED = -36,
461 KM_ERROR_IMPORTED_KEY_VERIFICATION_FAILED = -37,
462 KM_ERROR_INVALID_ARGUMENT = -38,
463 KM_ERROR_UNSUPPORTED_TAG = -39,
464 KM_ERROR_INVALID_TAG = -40,
465 KM_ERROR_MEMORY_ALLOCATION_FAILED = -41,
Shawn Willden9d645a02014-06-12 13:48:46 -0600466 KM_ERROR_IMPORT_PARAMETER_MISMATCH = -44,
467 KM_ERROR_SECURE_HW_ACCESS_DENIED = -45,
468 KM_ERROR_OPERATION_CANCELLED = -46,
469 KM_ERROR_CONCURRENT_ACCESS_CONFLICT = -47,
470 KM_ERROR_SECURE_HW_BUSY = -48,
471 KM_ERROR_SECURE_HW_COMMUNICATION_FAILED = -49,
472 KM_ERROR_UNSUPPORTED_EC_FIELD = -50,
Shawn Willdened941112015-03-11 21:53:59 -0600473 KM_ERROR_MISSING_NONCE = -51,
474 KM_ERROR_INVALID_NONCE = -52,
Shawn Willden4144c642015-06-01 11:40:34 -0600475 KM_ERROR_MISSING_MAC_LENGTH = -53,
Shawn Willden396d6cb2015-06-18 12:16:17 -0600476 KM_ERROR_KEY_RATE_LIMIT_EXCEEDED = -54,
Shawn Willden4bdd7cb2015-04-28 00:00:27 -0600477 KM_ERROR_CALLER_NONCE_PROHIBITED = -55,
Shawn Willden396d6cb2015-06-18 12:16:17 -0600478 KM_ERROR_KEY_MAX_OPS_EXCEEDED = -56,
Shawn Willdena3f0ab52015-07-08 06:04:52 -0600479 KM_ERROR_INVALID_MAC_LENGTH = -57,
480 KM_ERROR_MISSING_MIN_MAC_LENGTH = -58,
481 KM_ERROR_UNSUPPORTED_MIN_MAC_LENGTH = -59,
Thai Duong40d59c82015-04-02 21:41:37 -0700482 KM_ERROR_UNSUPPORTED_KDF = -60,
483 KM_ERROR_UNSUPPORTED_EC_CURVE = -61,
Shawn Willdencf30fe12015-12-21 16:29:10 -0700484 KM_ERROR_KEY_REQUIRES_UPGRADE = -62,
Shawn Willden7fd11182016-02-03 07:39:40 -0700485 KM_ERROR_ATTESTATION_CHALLENGE_MISSING = -63,
Shawn Willden30802762016-03-09 19:42:47 -0700486 KM_ERROR_KEYMASTER_NOT_CONFIGURED = -64,
Janis Danisevskis36966852016-06-01 13:39:09 -0700487 KM_ERROR_ATTESTATION_APPLICATION_ID_MISSING = -65,
Bartosz Fabianowski9d2f5b92017-01-23 15:36:42 +0100488 KM_ERROR_CANNOT_ATTEST_IDS = -66,
Matthew Maurer581f6f72019-12-10 06:58:19 -0800489 KM_ERROR_ROLLBACK_RESISTANCE_UNAVAILABLE = -67,
Matthew Maurer0b9dc0d2019-03-18 13:37:02 -0700490 KM_ERROR_NO_USER_CONFIRMATION = -71,
Brian Young8cf28622018-02-23 18:03:26 +0000491 KM_ERROR_DEVICE_LOCKED = -72,
Shawn Willdene59d5b12020-01-15 17:52:53 -0700492 KM_ERROR_EARLY_BOOT_ENDED = -73,
493 KM_ERROR_ATTESTATION_KEYS_NOT_PROVISIONED = -74,
494 KM_ERROR_ATTESTATION_IDS_NOT_PROVISIONED = -75,
Chirag Pathak39fd3062020-12-21 18:44:53 -0500495 KM_ERROR_INCOMPATIBLE_MGF_DIGEST = -78,
496 KM_ERROR_UNSUPPORTED_MGF_DIGEST = -79,
Shawn Willdened941112015-03-11 21:53:59 -0600497
Shawn Willden9d645a02014-06-12 13:48:46 -0600498 KM_ERROR_UNIMPLEMENTED = -100,
499 KM_ERROR_VERSION_MISMATCH = -101,
500
Shawn Willden9d645a02014-06-12 13:48:46 -0600501 KM_ERROR_UNKNOWN_ERROR = -1000,
502} keymaster_error_t;
503
Shawn Willden9d645a02014-06-12 13:48:46 -0600504/* Convenience functions for manipulating keymaster tag types */
505
506static inline keymaster_tag_type_t keymaster_tag_get_type(keymaster_tag_t tag) {
507 return (keymaster_tag_type_t)(tag & (0xF << 28));
508}
509
510static inline uint32_t keymaster_tag_mask_type(keymaster_tag_t tag) {
511 return tag & 0x0FFFFFFF;
512}
513
514static inline bool keymaster_tag_type_repeatable(keymaster_tag_type_t type) {
515 switch (type) {
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +0000516 case KM_UINT_REP:
Shawn Willden9d645a02014-06-12 13:48:46 -0600517 case KM_ENUM_REP:
518 return true;
519 default:
520 return false;
521 }
522}
523
524static inline bool keymaster_tag_repeatable(keymaster_tag_t tag) {
525 return keymaster_tag_type_repeatable(keymaster_tag_get_type(tag));
526}
527
528/* Convenience functions for manipulating keymaster_key_param_t structs */
529
530inline keymaster_key_param_t keymaster_param_enum(keymaster_tag_t tag, uint32_t value) {
531 // assert(keymaster_tag_get_type(tag) == KM_ENUM || keymaster_tag_get_type(tag) == KM_ENUM_REP);
532 keymaster_key_param_t param;
533 memset(&param, 0, sizeof(param));
534 param.tag = tag;
535 param.enumerated = value;
536 return param;
537}
538
539inline keymaster_key_param_t keymaster_param_int(keymaster_tag_t tag, uint32_t value) {
540 // assert(keymaster_tag_get_type(tag) == KM_INT || keymaster_tag_get_type(tag) == KM_INT_REP);
541 keymaster_key_param_t param;
542 memset(&param, 0, sizeof(param));
543 param.tag = tag;
544 param.integer = value;
545 return param;
546}
547
548inline keymaster_key_param_t keymaster_param_long(keymaster_tag_t tag, uint64_t value) {
549 // assert(keymaster_tag_get_type(tag) == KM_LONG);
550 keymaster_key_param_t param;
551 memset(&param, 0, sizeof(param));
552 param.tag = tag;
553 param.long_integer = value;
554 return param;
555}
556
557inline keymaster_key_param_t keymaster_param_blob(keymaster_tag_t tag, const uint8_t* bytes,
558 size_t bytes_len) {
559 // assert(keymaster_tag_get_type(tag) == KM_BYTES || keymaster_tag_get_type(tag) == KM_BIGNUM);
560 keymaster_key_param_t param;
561 memset(&param, 0, sizeof(param));
562 param.tag = tag;
563 param.blob.data = (uint8_t*)bytes;
564 param.blob.data_length = bytes_len;
565 return param;
566}
567
568inline keymaster_key_param_t keymaster_param_bool(keymaster_tag_t tag) {
569 // assert(keymaster_tag_get_type(tag) == KM_BOOL);
570 keymaster_key_param_t param;
571 memset(&param, 0, sizeof(param));
572 param.tag = tag;
573 param.boolean = true;
574 return param;
575}
576
577inline keymaster_key_param_t keymaster_param_date(keymaster_tag_t tag, uint64_t value) {
578 // assert(keymaster_tag_get_type(tag) == KM_DATE);
579 keymaster_key_param_t param;
580 memset(&param, 0, sizeof(param));
581 param.tag = tag;
582 param.date_time = value;
583 return param;
584}
585
Shawn Willden67411d62015-03-04 10:00:38 -0700586#define KEYMASTER_SIMPLE_COMPARE(a, b) (a < b) ? -1 : ((a > b) ? 1 : 0)
587inline int keymaster_param_compare(const keymaster_key_param_t* a, const keymaster_key_param_t* b) {
Tucker Sylvestro28a872e2016-10-05 14:39:39 -0400588 int retval = KEYMASTER_SIMPLE_COMPARE((uint32_t)a->tag, (uint32_t)b->tag);
Shawn Willden67411d62015-03-04 10:00:38 -0700589 if (retval != 0)
590 return retval;
591
592 switch (keymaster_tag_get_type(a->tag)) {
593 case KM_INVALID:
594 case KM_BOOL:
595 return 0;
596 case KM_ENUM:
597 case KM_ENUM_REP:
598 return KEYMASTER_SIMPLE_COMPARE(a->enumerated, b->enumerated);
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +0000599 case KM_UINT:
600 case KM_UINT_REP:
Shawn Willden67411d62015-03-04 10:00:38 -0700601 return KEYMASTER_SIMPLE_COMPARE(a->integer, b->integer);
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +0000602 case KM_ULONG:
603 case KM_ULONG_REP:
Shawn Willden67411d62015-03-04 10:00:38 -0700604 return KEYMASTER_SIMPLE_COMPARE(a->long_integer, b->long_integer);
605 case KM_DATE:
606 return KEYMASTER_SIMPLE_COMPARE(a->date_time, b->date_time);
607 case KM_BIGNUM:
608 case KM_BYTES:
609 // Handle the empty cases.
610 if (a->blob.data_length != 0 && b->blob.data_length == 0)
611 return -1;
612 if (a->blob.data_length == 0 && b->blob.data_length == 0)
613 return 0;
614 if (a->blob.data_length == 0 && b->blob.data_length > 0)
615 return 1;
616
617 retval = memcmp(a->blob.data, b->blob.data, a->blob.data_length < b->blob.data_length
618 ? a->blob.data_length
619 : b->blob.data_length);
620 if (retval != 0)
621 return retval;
622 else if (a->blob.data_length != b->blob.data_length) {
623 // Equal up to the common length; longer one is larger.
624 if (a->blob.data_length < b->blob.data_length)
625 return -1;
626 if (a->blob.data_length > b->blob.data_length)
627 return 1;
Pirama Arumuga Nainare0dc1382019-01-15 10:31:39 -0800628 }
Shawn Willden67411d62015-03-04 10:00:38 -0700629 }
630
631 return 0;
632}
633#undef KEYMASTER_SIMPLE_COMPARE
634
Shawn Willden9d645a02014-06-12 13:48:46 -0600635inline void keymaster_free_param_values(keymaster_key_param_t* param, size_t param_count) {
Chad Brubakera3c0ae12015-08-12 12:46:44 -0700636 while (param_count > 0) {
637 param_count--;
Shawn Willden9d645a02014-06-12 13:48:46 -0600638 switch (keymaster_tag_get_type(param->tag)) {
639 case KM_BIGNUM:
640 case KM_BYTES:
641 free((void*)param->blob.data);
642 param->blob.data = NULL;
643 break;
644 default:
645 // NOP
646 break;
647 }
648 ++param;
649 }
650}
651
652inline void keymaster_free_param_set(keymaster_key_param_set_t* set) {
653 if (set) {
654 keymaster_free_param_values(set->params, set->length);
655 free(set->params);
656 set->params = NULL;
Shawn Willdene366efd2016-03-20 09:07:50 -0600657 set->length = 0;
Shawn Willden9d645a02014-06-12 13:48:46 -0600658 }
659}
660
661inline void keymaster_free_characteristics(keymaster_key_characteristics_t* characteristics) {
662 if (characteristics) {
663 keymaster_free_param_set(&characteristics->hw_enforced);
664 keymaster_free_param_set(&characteristics->sw_enforced);
665 }
666}
667
Shawn Willdencf30fe12015-12-21 16:29:10 -0700668inline void keymaster_free_cert_chain(keymaster_cert_chain_t* chain) {
669 if (chain) {
670 for (size_t i = 0; i < chain->entry_count; ++i) {
671 free((uint8_t*)chain->entries[i].data);
672 chain->entries[i].data = NULL;
673 chain->entries[i].data_length = 0;
674 }
675 free(chain->entries);
676 chain->entries = NULL;
677 chain->entry_count = 0;
678 }
679}
680
Shawn Willden7eaa15f2015-06-03 09:03:20 -0600681#ifdef __cplusplus
Shawn Willdenc51d01e2015-03-18 18:59:52 -0600682} // extern "C"
683#endif // __cplusplus
Shawn Willden9d645a02014-06-12 13:48:46 -0600684
685#endif // ANDROID_HARDWARE_KEYMASTER_DEFS_H