blob: fd53adfea5ffc0ade39b769a7b55b2e9b0422737 [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 */
78
Shawn Willden9d645a02014-06-12 13:48:46 -060079 /*
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. */
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +000090 KM_TAG_MIN_SECONDS_BETWEEN_OPS = KM_UINT | 403, /* Minimum elapsed time between
Shawn Willden9d645a02014-06-12 13:48:46 -060091 cryptographic operations with the key. */
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +000092 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 -070093 boot. */
Shawn Willden9d645a02014-06-12 13:48:46 -060094
95 /* User authentication */
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +000096 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. */
Shawn Willden71ca0102016-01-26 07:00:27 -0700112 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. */
Shawn Willden9d645a02014-06-12 13:48:46 -0600115
116 /* Application access control */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700117 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) */
Shawn Willden9d645a02014-06-12 13:48:46 -0600124
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. */
Shawn Willden70335f32015-07-08 09:57:16 -0600133 KM_TAG_ROOT_OF_TRUST = KM_BYTES | 704, /* Root of trust ID. */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700134 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 */
Shawn Willden9d645a02014-06-12 13:48:46 -0600137
Shawn Willden67ba9e82015-02-06 17:04:53 -0700138 /* Tags used only to provide data to or receive data from operations */
139 KM_TAG_ASSOCIATED_DATA = KM_BYTES | 1000, /* Used to provide associated data for AEAD modes. */
Shawn Willden41e91e92015-01-30 06:23:26 -0700140 KM_TAG_NONCE = KM_BYTES | 1001, /* Nonce or Initialization Vector */
Shawn Willdenda89dde2015-06-18 12:09:20 -0600141 KM_TAG_AUTH_TOKEN = KM_BYTES | 1002, /* Authentication token that proves secure user
Shawn Willdenc3ab05c2015-03-14 08:23:41 -0600142 authentication has been performed. Structure
143 defined in hw_auth_token_t in hw_auth_token.h. */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700144 KM_TAG_MAC_LENGTH = KM_UINT | 1003, /* MAC or AEAD authentication tag length in
145 * bits. */
146
147 KM_TAG_RESET_SINCE_ID_ROTATION = KM_BOOL | 1004, /* Whether the device has beeen factory reset
148 since the last unique ID rotation. Used for
149 key attestation. */
Shawn Willden9d645a02014-06-12 13:48:46 -0600150} keymaster_tag_t;
151
152/**
153 * Algorithms that may be provided by keymaster implementations. Those that must be provided by all
Shawn Willdenfd4b4d52015-02-24 09:17:38 -0700154 * implementations are tagged as "required".
Shawn Willden9d645a02014-06-12 13:48:46 -0600155 */
156typedef enum {
157 /* Asymmetric algorithms. */
Shawn Willdene9797a72015-04-07 13:39:12 -0600158 KM_ALGORITHM_RSA = 1,
159 // KM_ALGORITHM_DSA = 2, -- Removed, do not re-use value 2.
160 KM_ALGORITHM_EC = 3,
161
162 /* Block ciphers algorithms */
163 KM_ALGORITHM_AES = 32,
164
Shawn Willden9d645a02014-06-12 13:48:46 -0600165 /* MAC algorithms */
Shawn Willdene9797a72015-04-07 13:39:12 -0600166 KM_ALGORITHM_HMAC = 128,
Shawn Willden9d645a02014-06-12 13:48:46 -0600167} keymaster_algorithm_t;
168
169/**
Shawn Willdenc7deeda2015-04-07 13:40:00 -0600170 * Symmetric block cipher modes provided by keymaster implementations.
Shawn Willden9d645a02014-06-12 13:48:46 -0600171 */
172typedef enum {
173 /* Unauthenticated modes, usable only for encryption/decryption and not generally recommended
174 * except for compatibility with existing other protocols. */
Shawn Willden4c19a3a2015-06-01 11:40:24 -0600175 KM_MODE_ECB = 1,
Shawn Willdenc7deeda2015-04-07 13:40:00 -0600176 KM_MODE_CBC = 2,
Shawn Willden4c19a3a2015-06-01 11:40:24 -0600177 KM_MODE_CTR = 3,
Shawn Willdenc7deeda2015-04-07 13:40:00 -0600178
Shawn Willden9d645a02014-06-12 13:48:46 -0600179 /* Authenticated modes, usable for encryption/decryption and signing/verification. Recommended
Shawn Willdenc7deeda2015-04-07 13:40:00 -0600180 * over unauthenticated modes for all purposes. */
Shawn Willden4c19a3a2015-06-01 11:40:24 -0600181 KM_MODE_GCM = 32,
Shawn Willden9d645a02014-06-12 13:48:46 -0600182} keymaster_block_mode_t;
183
184/**
185 * Padding modes that may be applied to plaintext for encryption operations. This list includes
186 * padding modes for both symmetric and asymmetric algorithms. Note that implementations should not
187 * provide all possible combinations of algorithm and padding, only the
188 * cryptographically-appropriate pairs.
189 */
190typedef enum {
Shawn Willden8412fdc2015-04-07 13:41:30 -0600191 KM_PAD_NONE = 1, /* deprecated */
192 KM_PAD_RSA_OAEP = 2,
193 KM_PAD_RSA_PSS = 3,
Shawn Willden9d645a02014-06-12 13:48:46 -0600194 KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4,
195 KM_PAD_RSA_PKCS1_1_5_SIGN = 5,
Shawn Willden8412fdc2015-04-07 13:41:30 -0600196 KM_PAD_PKCS7 = 64,
Shawn Willden9d645a02014-06-12 13:48:46 -0600197} keymaster_padding_t;
198
199/**
Shawn Willdenfe6c4f02015-04-07 14:02:28 -0600200 * Digests provided by keymaster implementations.
Shawn Willden9d645a02014-06-12 13:48:46 -0600201 */
202typedef enum {
Shawn Willdenfe6c4f02015-04-07 14:02:28 -0600203 KM_DIGEST_NONE = 0,
204 KM_DIGEST_MD5 = 1, /* Optional, may not be implemented in hardware, will be handled in software
205 * if needed. */
206 KM_DIGEST_SHA1 = 2,
207 KM_DIGEST_SHA_2_224 = 3,
208 KM_DIGEST_SHA_2_256 = 4,
209 KM_DIGEST_SHA_2_384 = 5,
210 KM_DIGEST_SHA_2_512 = 6,
Shawn Willden9d645a02014-06-12 13:48:46 -0600211} keymaster_digest_t;
212
Thai Duong40d59c82015-04-02 21:41:37 -0700213/*
214 * Key derivation functions, mostly used in ECIES.
215 */
216typedef enum {
Shawn Willdencf30fe12015-12-21 16:29:10 -0700217 /* Do not apply a key derivation function; use the raw agreed key */
218 KM_KDF_NONE = 0,
Thai Duong40d59c82015-04-02 21:41:37 -0700219 /* HKDF defined in RFC 5869 with SHA256 */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700220 KM_KDF_RFC5869_SHA256 = 1,
Thai Duong40d59c82015-04-02 21:41:37 -0700221 /* KDF1 defined in ISO 18033-2 with SHA1 */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700222 KM_KDF_ISO18033_2_KDF1_SHA1 = 2,
Thai Duong40d59c82015-04-02 21:41:37 -0700223 /* KDF1 defined in ISO 18033-2 with SHA256 */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700224 KM_KDF_ISO18033_2_KDF1_SHA256 = 3,
Thai Duong40d59c82015-04-02 21:41:37 -0700225 /* KDF2 defined in ISO 18033-2 with SHA1 */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700226 KM_KDF_ISO18033_2_KDF2_SHA1 = 4,
Thai Duong40d59c82015-04-02 21:41:37 -0700227 /* KDF2 defined in ISO 18033-2 with SHA256 */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700228 KM_KDF_ISO18033_2_KDF2_SHA256 = 5,
Thai Duong40d59c82015-04-02 21:41:37 -0700229} keymaster_kdf_t;
230
231/**
232 * Supported EC curves, used in ECDSA/ECIES.
233 */
234typedef enum {
235 KM_EC_CURVE_P_224 = 0,
236 KM_EC_CURVE_P_256 = 1,
237 KM_EC_CURVE_P_384 = 2,
238 KM_EC_CURVE_P_521 = 3,
239} keymaster_ec_curve_t;
240
Shawn Willden9d645a02014-06-12 13:48:46 -0600241/**
Shawn Willden8d6cf252015-04-07 13:56:30 -0600242 * The origin of a key (or pair), i.e. where it was generated. Note that KM_TAG_ORIGIN can be found
243 * in either the hardware-enforced or software-enforced list for a key, indicating whether the key
244 * is hardware or software-based. Specifically, a key with KM_ORIGIN_GENERATED in the
245 * hardware-enforced list is guaranteed never to have existed outide the secure hardware.
Shawn Willden9d645a02014-06-12 13:48:46 -0600246 */
247typedef enum {
Shawn Willdencf30fe12015-12-21 16:29:10 -0700248 KM_ORIGIN_GENERATED = 0, /* Generated in keymaster. Should not exist outside the TEE. */
249 KM_ORIGIN_DERIVED = 1, /* Derived inside keymaster. Likely exists off-device. */
250 KM_ORIGIN_IMPORTED = 2, /* Imported into keymaster. Existed as cleartext in Android. */
Shawn Willdend359b042015-04-13 11:07:24 -0600251 KM_ORIGIN_UNKNOWN = 3, /* Keymaster did not record origin. This value can only be seen on
252 * keys in a keymaster0 implementation. The keymaster0 adapter uses
253 * this value to document the fact that it is unkown whether the key
254 * was generated inside or imported into keymaster. */
Shawn Willden9d645a02014-06-12 13:48:46 -0600255} keymaster_key_origin_t;
256
257/**
258 * Usability requirements of key blobs. This defines what system functionality must be available
259 * for the key to function. For example, key "blobs" which are actually handles referencing
260 * encrypted key material stored in the file system cannot be used until the file system is
261 * available, and should have BLOB_REQUIRES_FILE_SYSTEM. Other requirements entries will be added
Shawn Willdencf30fe12015-12-21 16:29:10 -0700262 * as needed for implementations.
Shawn Willden9d645a02014-06-12 13:48:46 -0600263 */
264typedef enum {
265 KM_BLOB_STANDALONE = 0,
266 KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
267} keymaster_key_blob_usage_requirements_t;
268
269/**
Shawn Willdencf30fe12015-12-21 16:29:10 -0700270 * Possible purposes of a key (or pair).
Shawn Willden9d645a02014-06-12 13:48:46 -0600271 */
272typedef enum {
Shawn Willdencf30fe12015-12-21 16:29:10 -0700273 KM_PURPOSE_ENCRYPT = 0, /* Usable with RSA, EC and AES keys. */
274 KM_PURPOSE_DECRYPT = 1, /* Usable with RSA, EC and AES keys. */
275 KM_PURPOSE_SIGN = 2, /* Usable with RSA, EC and HMAC keys. */
276 KM_PURPOSE_VERIFY = 3, /* Usable with RSA, EC and HMAC keys. */
277 KM_PURPOSE_DERIVE_KEY = 4, /* Usable with EC keys. */
Shawn Willden9d645a02014-06-12 13:48:46 -0600278} keymaster_purpose_t;
279
280typedef struct {
281 const uint8_t* data;
282 size_t data_length;
283} keymaster_blob_t;
284
285typedef struct {
286 keymaster_tag_t tag;
287 union {
288 uint32_t enumerated; /* KM_ENUM and KM_ENUM_REP */
289 bool boolean; /* KM_BOOL */
290 uint32_t integer; /* KM_INT and KM_INT_REP */
291 uint64_t long_integer; /* KM_LONG */
292 uint64_t date_time; /* KM_DATE */
293 keymaster_blob_t blob; /* KM_BIGNUM and KM_BYTES*/
294 };
295} keymaster_key_param_t;
296
297typedef struct {
298 keymaster_key_param_t* params; /* may be NULL if length == 0 */
299 size_t length;
300} keymaster_key_param_set_t;
301
302/**
303 * Parameters that define a key's characteristics, including authorized modes of usage and access
304 * control restrictions. The parameters are divided into two categories, those that are enforced by
305 * secure hardware, and those that are not. For a software-only keymaster implementation the
306 * enforced array must NULL. Hardware implementations must enforce everything in the enforced
307 * array.
308 */
309typedef struct {
310 keymaster_key_param_set_t hw_enforced;
311 keymaster_key_param_set_t sw_enforced;
312} keymaster_key_characteristics_t;
313
314typedef struct {
315 const uint8_t* key_material;
316 size_t key_material_size;
317} keymaster_key_blob_t;
318
Shawn Willdencf30fe12015-12-21 16:29:10 -0700319typedef struct {
320 keymaster_blob_t* entries;
321 size_t entry_count;
322} keymaster_cert_chain_t;
323
Shawn Willden9d645a02014-06-12 13:48:46 -0600324/**
Shawn Willdencf30fe12015-12-21 16:29:10 -0700325 * Formats for key import and export.
Shawn Willden9d645a02014-06-12 13:48:46 -0600326 */
327typedef enum {
Shawn Willdenfb769fc2015-05-11 09:24:48 -0600328 KM_KEY_FORMAT_X509 = 0, /* for public key export */
329 KM_KEY_FORMAT_PKCS8 = 1, /* for asymmetric key pair import */
Shawn Willdencf30fe12015-12-21 16:29:10 -0700330 KM_KEY_FORMAT_RAW = 3, /* for symmetric key import and export*/
Shawn Willden9d645a02014-06-12 13:48:46 -0600331} keymaster_key_format_t;
332
333/**
334 * The keymaster operation API consists of begin, update, finish and abort. This is the type of the
335 * handle used to tie the sequence of calls together. A 64-bit value is used because it's important
336 * that handles not be predictable. Implementations must use strong random numbers for handle
337 * values.
338 */
339typedef uint64_t keymaster_operation_handle_t;
340
341typedef enum {
342 KM_ERROR_OK = 0,
343 KM_ERROR_ROOT_OF_TRUST_ALREADY_SET = -1,
344 KM_ERROR_UNSUPPORTED_PURPOSE = -2,
345 KM_ERROR_INCOMPATIBLE_PURPOSE = -3,
346 KM_ERROR_UNSUPPORTED_ALGORITHM = -4,
347 KM_ERROR_INCOMPATIBLE_ALGORITHM = -5,
348 KM_ERROR_UNSUPPORTED_KEY_SIZE = -6,
349 KM_ERROR_UNSUPPORTED_BLOCK_MODE = -7,
350 KM_ERROR_INCOMPATIBLE_BLOCK_MODE = -8,
Shawn Willden6b424be2015-01-26 13:04:28 -0700351 KM_ERROR_UNSUPPORTED_MAC_LENGTH = -9,
Shawn Willden9d645a02014-06-12 13:48:46 -0600352 KM_ERROR_UNSUPPORTED_PADDING_MODE = -10,
353 KM_ERROR_INCOMPATIBLE_PADDING_MODE = -11,
354 KM_ERROR_UNSUPPORTED_DIGEST = -12,
355 KM_ERROR_INCOMPATIBLE_DIGEST = -13,
356 KM_ERROR_INVALID_EXPIRATION_TIME = -14,
357 KM_ERROR_INVALID_USER_ID = -15,
358 KM_ERROR_INVALID_AUTHORIZATION_TIMEOUT = -16,
359 KM_ERROR_UNSUPPORTED_KEY_FORMAT = -17,
360 KM_ERROR_INCOMPATIBLE_KEY_FORMAT = -18,
361 KM_ERROR_UNSUPPORTED_KEY_ENCRYPTION_ALGORITHM = -19, /* For PKCS8 & PKCS12 */
362 KM_ERROR_UNSUPPORTED_KEY_VERIFICATION_ALGORITHM = -20, /* For PKCS8 & PKCS12 */
363 KM_ERROR_INVALID_INPUT_LENGTH = -21,
364 KM_ERROR_KEY_EXPORT_OPTIONS_INVALID = -22,
365 KM_ERROR_DELEGATION_NOT_ALLOWED = -23,
366 KM_ERROR_KEY_NOT_YET_VALID = -24,
367 KM_ERROR_KEY_EXPIRED = -25,
368 KM_ERROR_KEY_USER_NOT_AUTHENTICATED = -26,
369 KM_ERROR_OUTPUT_PARAMETER_NULL = -27,
370 KM_ERROR_INVALID_OPERATION_HANDLE = -28,
371 KM_ERROR_INSUFFICIENT_BUFFER_SPACE = -29,
372 KM_ERROR_VERIFICATION_FAILED = -30,
373 KM_ERROR_TOO_MANY_OPERATIONS = -31,
374 KM_ERROR_UNEXPECTED_NULL_POINTER = -32,
375 KM_ERROR_INVALID_KEY_BLOB = -33,
376 KM_ERROR_IMPORTED_KEY_NOT_ENCRYPTED = -34,
377 KM_ERROR_IMPORTED_KEY_DECRYPTION_FAILED = -35,
378 KM_ERROR_IMPORTED_KEY_NOT_SIGNED = -36,
379 KM_ERROR_IMPORTED_KEY_VERIFICATION_FAILED = -37,
380 KM_ERROR_INVALID_ARGUMENT = -38,
381 KM_ERROR_UNSUPPORTED_TAG = -39,
382 KM_ERROR_INVALID_TAG = -40,
383 KM_ERROR_MEMORY_ALLOCATION_FAILED = -41,
Shawn Willden9d645a02014-06-12 13:48:46 -0600384 KM_ERROR_IMPORT_PARAMETER_MISMATCH = -44,
385 KM_ERROR_SECURE_HW_ACCESS_DENIED = -45,
386 KM_ERROR_OPERATION_CANCELLED = -46,
387 KM_ERROR_CONCURRENT_ACCESS_CONFLICT = -47,
388 KM_ERROR_SECURE_HW_BUSY = -48,
389 KM_ERROR_SECURE_HW_COMMUNICATION_FAILED = -49,
390 KM_ERROR_UNSUPPORTED_EC_FIELD = -50,
Shawn Willdened941112015-03-11 21:53:59 -0600391 KM_ERROR_MISSING_NONCE = -51,
392 KM_ERROR_INVALID_NONCE = -52,
Shawn Willden4144c642015-06-01 11:40:34 -0600393 KM_ERROR_MISSING_MAC_LENGTH = -53,
Shawn Willden396d6cb2015-06-18 12:16:17 -0600394 KM_ERROR_KEY_RATE_LIMIT_EXCEEDED = -54,
Shawn Willden4bdd7cb2015-04-28 00:00:27 -0600395 KM_ERROR_CALLER_NONCE_PROHIBITED = -55,
Shawn Willden396d6cb2015-06-18 12:16:17 -0600396 KM_ERROR_KEY_MAX_OPS_EXCEEDED = -56,
Shawn Willdena3f0ab52015-07-08 06:04:52 -0600397 KM_ERROR_INVALID_MAC_LENGTH = -57,
398 KM_ERROR_MISSING_MIN_MAC_LENGTH = -58,
399 KM_ERROR_UNSUPPORTED_MIN_MAC_LENGTH = -59,
Thai Duong40d59c82015-04-02 21:41:37 -0700400 KM_ERROR_UNSUPPORTED_KDF = -60,
401 KM_ERROR_UNSUPPORTED_EC_CURVE = -61,
Shawn Willdencf30fe12015-12-21 16:29:10 -0700402 KM_ERROR_KEY_REQUIRES_UPGRADE = -62,
Shawn Willdened941112015-03-11 21:53:59 -0600403
Shawn Willden9d645a02014-06-12 13:48:46 -0600404 KM_ERROR_UNIMPLEMENTED = -100,
405 KM_ERROR_VERSION_MISMATCH = -101,
406
Shawn Willden9d645a02014-06-12 13:48:46 -0600407 KM_ERROR_UNKNOWN_ERROR = -1000,
408} keymaster_error_t;
409
Shawn Willden9d645a02014-06-12 13:48:46 -0600410/* Convenience functions for manipulating keymaster tag types */
411
412static inline keymaster_tag_type_t keymaster_tag_get_type(keymaster_tag_t tag) {
413 return (keymaster_tag_type_t)(tag & (0xF << 28));
414}
415
416static inline uint32_t keymaster_tag_mask_type(keymaster_tag_t tag) {
417 return tag & 0x0FFFFFFF;
418}
419
420static inline bool keymaster_tag_type_repeatable(keymaster_tag_type_t type) {
421 switch (type) {
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +0000422 case KM_UINT_REP:
Shawn Willden9d645a02014-06-12 13:48:46 -0600423 case KM_ENUM_REP:
424 return true;
425 default:
426 return false;
427 }
428}
429
430static inline bool keymaster_tag_repeatable(keymaster_tag_t tag) {
431 return keymaster_tag_type_repeatable(keymaster_tag_get_type(tag));
432}
433
434/* Convenience functions for manipulating keymaster_key_param_t structs */
435
436inline keymaster_key_param_t keymaster_param_enum(keymaster_tag_t tag, uint32_t value) {
437 // assert(keymaster_tag_get_type(tag) == KM_ENUM || keymaster_tag_get_type(tag) == KM_ENUM_REP);
438 keymaster_key_param_t param;
439 memset(&param, 0, sizeof(param));
440 param.tag = tag;
441 param.enumerated = value;
442 return param;
443}
444
445inline keymaster_key_param_t keymaster_param_int(keymaster_tag_t tag, uint32_t value) {
446 // assert(keymaster_tag_get_type(tag) == KM_INT || keymaster_tag_get_type(tag) == KM_INT_REP);
447 keymaster_key_param_t param;
448 memset(&param, 0, sizeof(param));
449 param.tag = tag;
450 param.integer = value;
451 return param;
452}
453
454inline keymaster_key_param_t keymaster_param_long(keymaster_tag_t tag, uint64_t value) {
455 // assert(keymaster_tag_get_type(tag) == KM_LONG);
456 keymaster_key_param_t param;
457 memset(&param, 0, sizeof(param));
458 param.tag = tag;
459 param.long_integer = value;
460 return param;
461}
462
463inline keymaster_key_param_t keymaster_param_blob(keymaster_tag_t tag, const uint8_t* bytes,
464 size_t bytes_len) {
465 // assert(keymaster_tag_get_type(tag) == KM_BYTES || keymaster_tag_get_type(tag) == KM_BIGNUM);
466 keymaster_key_param_t param;
467 memset(&param, 0, sizeof(param));
468 param.tag = tag;
469 param.blob.data = (uint8_t*)bytes;
470 param.blob.data_length = bytes_len;
471 return param;
472}
473
474inline keymaster_key_param_t keymaster_param_bool(keymaster_tag_t tag) {
475 // assert(keymaster_tag_get_type(tag) == KM_BOOL);
476 keymaster_key_param_t param;
477 memset(&param, 0, sizeof(param));
478 param.tag = tag;
479 param.boolean = true;
480 return param;
481}
482
483inline keymaster_key_param_t keymaster_param_date(keymaster_tag_t tag, uint64_t value) {
484 // assert(keymaster_tag_get_type(tag) == KM_DATE);
485 keymaster_key_param_t param;
486 memset(&param, 0, sizeof(param));
487 param.tag = tag;
488 param.date_time = value;
489 return param;
490}
491
Shawn Willden67411d62015-03-04 10:00:38 -0700492#define KEYMASTER_SIMPLE_COMPARE(a, b) (a < b) ? -1 : ((a > b) ? 1 : 0)
493inline int keymaster_param_compare(const keymaster_key_param_t* a, const keymaster_key_param_t* b) {
494 int retval = KEYMASTER_SIMPLE_COMPARE(a->tag, b->tag);
495 if (retval != 0)
496 return retval;
497
498 switch (keymaster_tag_get_type(a->tag)) {
499 case KM_INVALID:
500 case KM_BOOL:
501 return 0;
502 case KM_ENUM:
503 case KM_ENUM_REP:
504 return KEYMASTER_SIMPLE_COMPARE(a->enumerated, b->enumerated);
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +0000505 case KM_UINT:
506 case KM_UINT_REP:
Shawn Willden67411d62015-03-04 10:00:38 -0700507 return KEYMASTER_SIMPLE_COMPARE(a->integer, b->integer);
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +0000508 case KM_ULONG:
509 case KM_ULONG_REP:
Shawn Willden67411d62015-03-04 10:00:38 -0700510 return KEYMASTER_SIMPLE_COMPARE(a->long_integer, b->long_integer);
511 case KM_DATE:
512 return KEYMASTER_SIMPLE_COMPARE(a->date_time, b->date_time);
513 case KM_BIGNUM:
514 case KM_BYTES:
515 // Handle the empty cases.
516 if (a->blob.data_length != 0 && b->blob.data_length == 0)
517 return -1;
518 if (a->blob.data_length == 0 && b->blob.data_length == 0)
519 return 0;
520 if (a->blob.data_length == 0 && b->blob.data_length > 0)
521 return 1;
522
523 retval = memcmp(a->blob.data, b->blob.data, a->blob.data_length < b->blob.data_length
524 ? a->blob.data_length
525 : b->blob.data_length);
526 if (retval != 0)
527 return retval;
528 else if (a->blob.data_length != b->blob.data_length) {
529 // Equal up to the common length; longer one is larger.
530 if (a->blob.data_length < b->blob.data_length)
531 return -1;
532 if (a->blob.data_length > b->blob.data_length)
533 return 1;
534 };
535 }
536
537 return 0;
538}
539#undef KEYMASTER_SIMPLE_COMPARE
540
Shawn Willden9d645a02014-06-12 13:48:46 -0600541inline void keymaster_free_param_values(keymaster_key_param_t* param, size_t param_count) {
542 while (param_count-- > 0) {
543 switch (keymaster_tag_get_type(param->tag)) {
544 case KM_BIGNUM:
545 case KM_BYTES:
546 free((void*)param->blob.data);
547 param->blob.data = NULL;
548 break;
549 default:
550 // NOP
551 break;
552 }
553 ++param;
554 }
555}
556
557inline void keymaster_free_param_set(keymaster_key_param_set_t* set) {
558 if (set) {
559 keymaster_free_param_values(set->params, set->length);
560 free(set->params);
561 set->params = NULL;
562 }
563}
564
565inline void keymaster_free_characteristics(keymaster_key_characteristics_t* characteristics) {
566 if (characteristics) {
567 keymaster_free_param_set(&characteristics->hw_enforced);
568 keymaster_free_param_set(&characteristics->sw_enforced);
569 }
570}
571
Shawn Willdencf30fe12015-12-21 16:29:10 -0700572inline void keymaster_free_cert_chain(keymaster_cert_chain_t* chain) {
573 if (chain) {
574 for (size_t i = 0; i < chain->entry_count; ++i) {
575 free((uint8_t*)chain->entries[i].data);
576 chain->entries[i].data = NULL;
577 chain->entries[i].data_length = 0;
578 }
579 free(chain->entries);
580 chain->entries = NULL;
581 chain->entry_count = 0;
582 }
583}
584
Shawn Willden7eaa15f2015-06-03 09:03:20 -0600585#ifdef __cplusplus
Shawn Willdenc51d01e2015-03-18 18:59:52 -0600586} // extern "C"
587#endif // __cplusplus
Shawn Willden9d645a02014-06-12 13:48:46 -0600588
589#endif // ANDROID_HARDWARE_KEYMASTER_DEFS_H