blob: bf09e23c3903f05e24f0ca3aa57dbf950d74c996 [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 */
Thai Duong40d59c82015-04-02 21:41:37 -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 | 9, /* keymaster_kdf_t */
65 KM_TAG_EC_CURVE = KM_ENUM | 10, /* keymaster_ec_curve_t */
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
70 * the KDF, see 10.2 in http://goo.gl/WbmSSO */
Shawn Willden9d645a02014-06-12 13:48:46 -060071
Shawn Willdenfb769fc2015-05-11 09:24:48 -060072 /* Other hardware-enforced. */
73 KM_TAG_BLOB_USAGE_REQUIREMENTS = KM_ENUM | 301, /* keymaster_key_blob_usage_requirements_t */
74 KM_TAG_BOOTLOADER_ONLY = KM_BOOL | 302, /* Usable only by bootloader */
75
Shawn Willden9d645a02014-06-12 13:48:46 -060076 /*
77 * Tags that should be semantically enforced by hardware if possible and will otherwise be
78 * enforced by software (keystore).
79 */
80
81 /* Key validity period */
82 KM_TAG_ACTIVE_DATETIME = KM_DATE | 400, /* Start of validity */
83 KM_TAG_ORIGINATION_EXPIRE_DATETIME = KM_DATE | 401, /* Date when new "messages" should no
84 longer be created. */
85 KM_TAG_USAGE_EXPIRE_DATETIME = KM_DATE | 402, /* Date when existing "messages" should no
86 longer be trusted. */
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +000087 KM_TAG_MIN_SECONDS_BETWEEN_OPS = KM_UINT | 403, /* Minimum elapsed time between
Shawn Willden9d645a02014-06-12 13:48:46 -060088 cryptographic operations with the key. */
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +000089 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 -070090 boot. */
Shawn Willden9d645a02014-06-12 13:48:46 -060091
92 /* User authentication */
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +000093 KM_TAG_ALL_USERS = KM_BOOL | 500, /* Reserved for future use -- ignore */
94 KM_TAG_USER_ID = KM_UINT | 501, /* Reserved for future use -- ignore */
95 KM_TAG_USER_SECURE_ID = KM_ULONG_REP | 502, /* Secure ID of authorized user or authenticator(s).
96 Disallowed if KM_TAG_ALL_USERS or
97 KM_TAG_NO_AUTH_REQUIRED is present. */
98 KM_TAG_NO_AUTH_REQUIRED = KM_BOOL | 503, /* If key is usable without authentication. */
99 KM_TAG_USER_AUTH_TYPE = KM_ENUM | 504, /* Bitmask of authenticator types allowed when
100 * KM_TAG_USER_SECURE_ID contains a secure user ID,
101 * rather than a secure authenticator ID. Defined in
102 * hw_authenticator_type_t in hw_auth_token.h. */
103 KM_TAG_AUTH_TIMEOUT = KM_UINT | 505, /* Required freshness of user authentication for
104 private/secret key operations, in seconds.
105 Public key operations require no authentication.
106 If absent, authentication is required for every
107 use. Authentication state is lost when the
108 device is powered off. */
Shawn Willden9d645a02014-06-12 13:48:46 -0600109
110 /* Application access control */
Shawn Willden7ac0c0f2015-06-18 12:15:09 -0600111 KM_TAG_ALL_APPLICATIONS = KM_BOOL | 600, /* Reserved for future use -- ignore */
112 KM_TAG_APPLICATION_ID = KM_BYTES | 601, /* Reserved for fugure use -- ignore */
Shawn Willden9d645a02014-06-12 13:48:46 -0600113
114 /*
115 * Semantically unenforceable tags, either because they have no specific meaning or because
116 * they're informational only.
117 */
118 KM_TAG_APPLICATION_DATA = KM_BYTES | 700, /* Data provided by authorized application. */
119 KM_TAG_CREATION_DATETIME = KM_DATE | 701, /* Key creation time */
120 KM_TAG_ORIGIN = KM_ENUM | 702, /* keymaster_key_origin_t. */
121 KM_TAG_ROLLBACK_RESISTANT = KM_BOOL | 703, /* Whether key is rollback-resistant. */
Shawn Willden70335f32015-07-08 09:57:16 -0600122 KM_TAG_ROOT_OF_TRUST = KM_BYTES | 704, /* Root of trust ID. */
Shawn Willden9d645a02014-06-12 13:48:46 -0600123
Shawn Willden67ba9e82015-02-06 17:04:53 -0700124 /* Tags used only to provide data to or receive data from operations */
125 KM_TAG_ASSOCIATED_DATA = KM_BYTES | 1000, /* Used to provide associated data for AEAD modes. */
Shawn Willden41e91e92015-01-30 06:23:26 -0700126 KM_TAG_NONCE = KM_BYTES | 1001, /* Nonce or Initialization Vector */
Shawn Willdenda89dde2015-06-18 12:09:20 -0600127 KM_TAG_AUTH_TOKEN = KM_BYTES | 1002, /* Authentication token that proves secure user
Shawn Willdenc3ab05c2015-03-14 08:23:41 -0600128 authentication has been performed. Structure
129 defined in hw_auth_token_t in hw_auth_token.h. */
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +0000130 KM_TAG_MAC_LENGTH = KM_UINT | 1003, /* MAC or AEAD authentication tag length in bits. */
Shawn Willden9d645a02014-06-12 13:48:46 -0600131} keymaster_tag_t;
132
133/**
134 * Algorithms that may be provided by keymaster implementations. Those that must be provided by all
Shawn Willdenfd4b4d52015-02-24 09:17:38 -0700135 * implementations are tagged as "required".
Shawn Willden9d645a02014-06-12 13:48:46 -0600136 */
137typedef enum {
138 /* Asymmetric algorithms. */
Shawn Willdene9797a72015-04-07 13:39:12 -0600139 KM_ALGORITHM_RSA = 1,
140 // KM_ALGORITHM_DSA = 2, -- Removed, do not re-use value 2.
141 KM_ALGORITHM_EC = 3,
142
143 /* Block ciphers algorithms */
144 KM_ALGORITHM_AES = 32,
145
Shawn Willden9d645a02014-06-12 13:48:46 -0600146 /* MAC algorithms */
Shawn Willdene9797a72015-04-07 13:39:12 -0600147 KM_ALGORITHM_HMAC = 128,
Shawn Willden9d645a02014-06-12 13:48:46 -0600148} keymaster_algorithm_t;
149
150/**
Shawn Willdenc7deeda2015-04-07 13:40:00 -0600151 * Symmetric block cipher modes provided by keymaster implementations.
Shawn Willden9d645a02014-06-12 13:48:46 -0600152 */
153typedef enum {
154 /* Unauthenticated modes, usable only for encryption/decryption and not generally recommended
155 * except for compatibility with existing other protocols. */
Shawn Willden4c19a3a2015-06-01 11:40:24 -0600156 KM_MODE_ECB = 1,
Shawn Willdenc7deeda2015-04-07 13:40:00 -0600157 KM_MODE_CBC = 2,
Shawn Willden4c19a3a2015-06-01 11:40:24 -0600158 KM_MODE_CTR = 3,
Shawn Willdenc7deeda2015-04-07 13:40:00 -0600159
Shawn Willden9d645a02014-06-12 13:48:46 -0600160 /* Authenticated modes, usable for encryption/decryption and signing/verification. Recommended
Shawn Willdenc7deeda2015-04-07 13:40:00 -0600161 * over unauthenticated modes for all purposes. */
Shawn Willden4c19a3a2015-06-01 11:40:24 -0600162 KM_MODE_GCM = 32,
Shawn Willden9d645a02014-06-12 13:48:46 -0600163} keymaster_block_mode_t;
164
165/**
166 * Padding modes that may be applied to plaintext for encryption operations. This list includes
167 * padding modes for both symmetric and asymmetric algorithms. Note that implementations should not
168 * provide all possible combinations of algorithm and padding, only the
169 * cryptographically-appropriate pairs.
170 */
171typedef enum {
Shawn Willden8412fdc2015-04-07 13:41:30 -0600172 KM_PAD_NONE = 1, /* deprecated */
173 KM_PAD_RSA_OAEP = 2,
174 KM_PAD_RSA_PSS = 3,
Shawn Willden9d645a02014-06-12 13:48:46 -0600175 KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4,
176 KM_PAD_RSA_PKCS1_1_5_SIGN = 5,
Shawn Willden8412fdc2015-04-07 13:41:30 -0600177 KM_PAD_PKCS7 = 64,
Shawn Willden9d645a02014-06-12 13:48:46 -0600178} keymaster_padding_t;
179
180/**
Shawn Willdenfe6c4f02015-04-07 14:02:28 -0600181 * Digests provided by keymaster implementations.
Shawn Willden9d645a02014-06-12 13:48:46 -0600182 */
183typedef enum {
Shawn Willdenfe6c4f02015-04-07 14:02:28 -0600184 KM_DIGEST_NONE = 0,
185 KM_DIGEST_MD5 = 1, /* Optional, may not be implemented in hardware, will be handled in software
186 * if needed. */
187 KM_DIGEST_SHA1 = 2,
188 KM_DIGEST_SHA_2_224 = 3,
189 KM_DIGEST_SHA_2_256 = 4,
190 KM_DIGEST_SHA_2_384 = 5,
191 KM_DIGEST_SHA_2_512 = 6,
Shawn Willden9d645a02014-06-12 13:48:46 -0600192} keymaster_digest_t;
193
Thai Duong40d59c82015-04-02 21:41:37 -0700194/*
195 * Key derivation functions, mostly used in ECIES.
196 */
197typedef enum {
198 /* HKDF defined in RFC 5869 with SHA256 */
199 KM_KDF_RFC5869_SHA256 = 0,
200 /* KDF1 defined in ISO 18033-2 with SHA1 */
201 KM_KDF_ISO18033_1_KDF2_SHA1 = 1,
202 /* KDF1 defined in ISO 18033-2 with SHA256 */
203 KM_KDF_ISO18033_1_KDF1_SHA256 = 2,
204 /* KDF2 defined in ISO 18033-2 with SHA1 */
205 KM_KDF_ISO18033_2_KDF2_SHA1 = 3,
206 /* KDF2 defined in ISO 18033-2 with SHA256 */
207 KM_KDF_ISO18033_2_KDF2_SHA256 = 4,
208} keymaster_kdf_t;
209
210/**
211 * Supported EC curves, used in ECDSA/ECIES.
212 */
213typedef enum {
214 KM_EC_CURVE_P_224 = 0,
215 KM_EC_CURVE_P_256 = 1,
216 KM_EC_CURVE_P_384 = 2,
217 KM_EC_CURVE_P_521 = 3,
218} keymaster_ec_curve_t;
219
Shawn Willden9d645a02014-06-12 13:48:46 -0600220/**
Shawn Willden8d6cf252015-04-07 13:56:30 -0600221 * The origin of a key (or pair), i.e. where it was generated. Note that KM_TAG_ORIGIN can be found
222 * in either the hardware-enforced or software-enforced list for a key, indicating whether the key
223 * is hardware or software-based. Specifically, a key with KM_ORIGIN_GENERATED in the
224 * hardware-enforced list is guaranteed never to have existed outide the secure hardware.
Shawn Willden9d645a02014-06-12 13:48:46 -0600225 */
226typedef enum {
Shawn Willden8d6cf252015-04-07 13:56:30 -0600227 KM_ORIGIN_GENERATED = 0, /* Generated in keymaster */
Shawn Willdend359b042015-04-13 11:07:24 -0600228 KM_ORIGIN_IMPORTED = 2, /* Imported, origin unknown */
229 KM_ORIGIN_UNKNOWN = 3, /* Keymaster did not record origin. This value can only be seen on
230 * keys in a keymaster0 implementation. The keymaster0 adapter uses
231 * this value to document the fact that it is unkown whether the key
232 * was generated inside or imported into keymaster. */
Shawn Willden9d645a02014-06-12 13:48:46 -0600233} keymaster_key_origin_t;
234
235/**
236 * Usability requirements of key blobs. This defines what system functionality must be available
237 * for the key to function. For example, key "blobs" which are actually handles referencing
238 * encrypted key material stored in the file system cannot be used until the file system is
239 * available, and should have BLOB_REQUIRES_FILE_SYSTEM. Other requirements entries will be added
240 * as needed for implementations. This type is new in 0_4.
241 */
242typedef enum {
243 KM_BLOB_STANDALONE = 0,
244 KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
245} keymaster_key_blob_usage_requirements_t;
246
247/**
248 * Possible purposes of a key (or pair). This type is new in 0_4.
249 */
250typedef enum {
251 KM_PURPOSE_ENCRYPT = 0,
252 KM_PURPOSE_DECRYPT = 1,
253 KM_PURPOSE_SIGN = 2,
254 KM_PURPOSE_VERIFY = 3,
255} keymaster_purpose_t;
256
257typedef struct {
258 const uint8_t* data;
259 size_t data_length;
260} keymaster_blob_t;
261
262typedef struct {
263 keymaster_tag_t tag;
264 union {
265 uint32_t enumerated; /* KM_ENUM and KM_ENUM_REP */
266 bool boolean; /* KM_BOOL */
267 uint32_t integer; /* KM_INT and KM_INT_REP */
268 uint64_t long_integer; /* KM_LONG */
269 uint64_t date_time; /* KM_DATE */
270 keymaster_blob_t blob; /* KM_BIGNUM and KM_BYTES*/
271 };
272} keymaster_key_param_t;
273
274typedef struct {
275 keymaster_key_param_t* params; /* may be NULL if length == 0 */
276 size_t length;
277} keymaster_key_param_set_t;
278
279/**
280 * Parameters that define a key's characteristics, including authorized modes of usage and access
281 * control restrictions. The parameters are divided into two categories, those that are enforced by
282 * secure hardware, and those that are not. For a software-only keymaster implementation the
283 * enforced array must NULL. Hardware implementations must enforce everything in the enforced
284 * array.
285 */
286typedef struct {
287 keymaster_key_param_set_t hw_enforced;
288 keymaster_key_param_set_t sw_enforced;
289} keymaster_key_characteristics_t;
290
291typedef struct {
292 const uint8_t* key_material;
293 size_t key_material_size;
294} keymaster_key_blob_t;
295
296/**
297 * Formats for key import and export. At present, only asymmetric key import/export is supported.
298 * In the future this list will expand greatly to accommodate asymmetric key import/export.
299 */
300typedef enum {
Shawn Willdenfb769fc2015-05-11 09:24:48 -0600301 KM_KEY_FORMAT_X509 = 0, /* for public key export */
302 KM_KEY_FORMAT_PKCS8 = 1, /* for asymmetric key pair import */
303 KM_KEY_FORMAT_RAW = 3, /* for symmetric key import */
Shawn Willden9d645a02014-06-12 13:48:46 -0600304} keymaster_key_format_t;
305
306/**
307 * The keymaster operation API consists of begin, update, finish and abort. This is the type of the
308 * handle used to tie the sequence of calls together. A 64-bit value is used because it's important
309 * that handles not be predictable. Implementations must use strong random numbers for handle
310 * values.
311 */
312typedef uint64_t keymaster_operation_handle_t;
313
314typedef enum {
315 KM_ERROR_OK = 0,
316 KM_ERROR_ROOT_OF_TRUST_ALREADY_SET = -1,
317 KM_ERROR_UNSUPPORTED_PURPOSE = -2,
318 KM_ERROR_INCOMPATIBLE_PURPOSE = -3,
319 KM_ERROR_UNSUPPORTED_ALGORITHM = -4,
320 KM_ERROR_INCOMPATIBLE_ALGORITHM = -5,
321 KM_ERROR_UNSUPPORTED_KEY_SIZE = -6,
322 KM_ERROR_UNSUPPORTED_BLOCK_MODE = -7,
323 KM_ERROR_INCOMPATIBLE_BLOCK_MODE = -8,
Shawn Willden6b424be2015-01-26 13:04:28 -0700324 KM_ERROR_UNSUPPORTED_MAC_LENGTH = -9,
Shawn Willden9d645a02014-06-12 13:48:46 -0600325 KM_ERROR_UNSUPPORTED_PADDING_MODE = -10,
326 KM_ERROR_INCOMPATIBLE_PADDING_MODE = -11,
327 KM_ERROR_UNSUPPORTED_DIGEST = -12,
328 KM_ERROR_INCOMPATIBLE_DIGEST = -13,
329 KM_ERROR_INVALID_EXPIRATION_TIME = -14,
330 KM_ERROR_INVALID_USER_ID = -15,
331 KM_ERROR_INVALID_AUTHORIZATION_TIMEOUT = -16,
332 KM_ERROR_UNSUPPORTED_KEY_FORMAT = -17,
333 KM_ERROR_INCOMPATIBLE_KEY_FORMAT = -18,
334 KM_ERROR_UNSUPPORTED_KEY_ENCRYPTION_ALGORITHM = -19, /* For PKCS8 & PKCS12 */
335 KM_ERROR_UNSUPPORTED_KEY_VERIFICATION_ALGORITHM = -20, /* For PKCS8 & PKCS12 */
336 KM_ERROR_INVALID_INPUT_LENGTH = -21,
337 KM_ERROR_KEY_EXPORT_OPTIONS_INVALID = -22,
338 KM_ERROR_DELEGATION_NOT_ALLOWED = -23,
339 KM_ERROR_KEY_NOT_YET_VALID = -24,
340 KM_ERROR_KEY_EXPIRED = -25,
341 KM_ERROR_KEY_USER_NOT_AUTHENTICATED = -26,
342 KM_ERROR_OUTPUT_PARAMETER_NULL = -27,
343 KM_ERROR_INVALID_OPERATION_HANDLE = -28,
344 KM_ERROR_INSUFFICIENT_BUFFER_SPACE = -29,
345 KM_ERROR_VERIFICATION_FAILED = -30,
346 KM_ERROR_TOO_MANY_OPERATIONS = -31,
347 KM_ERROR_UNEXPECTED_NULL_POINTER = -32,
348 KM_ERROR_INVALID_KEY_BLOB = -33,
349 KM_ERROR_IMPORTED_KEY_NOT_ENCRYPTED = -34,
350 KM_ERROR_IMPORTED_KEY_DECRYPTION_FAILED = -35,
351 KM_ERROR_IMPORTED_KEY_NOT_SIGNED = -36,
352 KM_ERROR_IMPORTED_KEY_VERIFICATION_FAILED = -37,
353 KM_ERROR_INVALID_ARGUMENT = -38,
354 KM_ERROR_UNSUPPORTED_TAG = -39,
355 KM_ERROR_INVALID_TAG = -40,
356 KM_ERROR_MEMORY_ALLOCATION_FAILED = -41,
Shawn Willden9d645a02014-06-12 13:48:46 -0600357 KM_ERROR_IMPORT_PARAMETER_MISMATCH = -44,
358 KM_ERROR_SECURE_HW_ACCESS_DENIED = -45,
359 KM_ERROR_OPERATION_CANCELLED = -46,
360 KM_ERROR_CONCURRENT_ACCESS_CONFLICT = -47,
361 KM_ERROR_SECURE_HW_BUSY = -48,
362 KM_ERROR_SECURE_HW_COMMUNICATION_FAILED = -49,
363 KM_ERROR_UNSUPPORTED_EC_FIELD = -50,
Shawn Willdened941112015-03-11 21:53:59 -0600364 KM_ERROR_MISSING_NONCE = -51,
365 KM_ERROR_INVALID_NONCE = -52,
Shawn Willden4144c642015-06-01 11:40:34 -0600366 KM_ERROR_MISSING_MAC_LENGTH = -53,
Shawn Willden396d6cb2015-06-18 12:16:17 -0600367 KM_ERROR_KEY_RATE_LIMIT_EXCEEDED = -54,
Shawn Willden4bdd7cb2015-04-28 00:00:27 -0600368 KM_ERROR_CALLER_NONCE_PROHIBITED = -55,
Shawn Willden396d6cb2015-06-18 12:16:17 -0600369 KM_ERROR_KEY_MAX_OPS_EXCEEDED = -56,
Shawn Willdena3f0ab52015-07-08 06:04:52 -0600370 KM_ERROR_INVALID_MAC_LENGTH = -57,
371 KM_ERROR_MISSING_MIN_MAC_LENGTH = -58,
372 KM_ERROR_UNSUPPORTED_MIN_MAC_LENGTH = -59,
Thai Duong40d59c82015-04-02 21:41:37 -0700373 KM_ERROR_UNSUPPORTED_KDF = -60,
374 KM_ERROR_UNSUPPORTED_EC_CURVE = -61,
Shawn Willdened941112015-03-11 21:53:59 -0600375
Shawn Willden9d645a02014-06-12 13:48:46 -0600376 KM_ERROR_UNIMPLEMENTED = -100,
377 KM_ERROR_VERSION_MISMATCH = -101,
378
Shawn Willden9d645a02014-06-12 13:48:46 -0600379 KM_ERROR_UNKNOWN_ERROR = -1000,
380} keymaster_error_t;
381
Shawn Willden9d645a02014-06-12 13:48:46 -0600382/* Convenience functions for manipulating keymaster tag types */
383
384static inline keymaster_tag_type_t keymaster_tag_get_type(keymaster_tag_t tag) {
385 return (keymaster_tag_type_t)(tag & (0xF << 28));
386}
387
388static inline uint32_t keymaster_tag_mask_type(keymaster_tag_t tag) {
389 return tag & 0x0FFFFFFF;
390}
391
392static inline bool keymaster_tag_type_repeatable(keymaster_tag_type_t type) {
393 switch (type) {
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +0000394 case KM_UINT_REP:
Shawn Willden9d645a02014-06-12 13:48:46 -0600395 case KM_ENUM_REP:
396 return true;
397 default:
398 return false;
399 }
400}
401
402static inline bool keymaster_tag_repeatable(keymaster_tag_t tag) {
403 return keymaster_tag_type_repeatable(keymaster_tag_get_type(tag));
404}
405
406/* Convenience functions for manipulating keymaster_key_param_t structs */
407
408inline keymaster_key_param_t keymaster_param_enum(keymaster_tag_t tag, uint32_t value) {
409 // assert(keymaster_tag_get_type(tag) == KM_ENUM || keymaster_tag_get_type(tag) == KM_ENUM_REP);
410 keymaster_key_param_t param;
411 memset(&param, 0, sizeof(param));
412 param.tag = tag;
413 param.enumerated = value;
414 return param;
415}
416
417inline keymaster_key_param_t keymaster_param_int(keymaster_tag_t tag, uint32_t value) {
418 // assert(keymaster_tag_get_type(tag) == KM_INT || keymaster_tag_get_type(tag) == KM_INT_REP);
419 keymaster_key_param_t param;
420 memset(&param, 0, sizeof(param));
421 param.tag = tag;
422 param.integer = value;
423 return param;
424}
425
426inline keymaster_key_param_t keymaster_param_long(keymaster_tag_t tag, uint64_t value) {
427 // assert(keymaster_tag_get_type(tag) == KM_LONG);
428 keymaster_key_param_t param;
429 memset(&param, 0, sizeof(param));
430 param.tag = tag;
431 param.long_integer = value;
432 return param;
433}
434
435inline keymaster_key_param_t keymaster_param_blob(keymaster_tag_t tag, const uint8_t* bytes,
436 size_t bytes_len) {
437 // assert(keymaster_tag_get_type(tag) == KM_BYTES || keymaster_tag_get_type(tag) == KM_BIGNUM);
438 keymaster_key_param_t param;
439 memset(&param, 0, sizeof(param));
440 param.tag = tag;
441 param.blob.data = (uint8_t*)bytes;
442 param.blob.data_length = bytes_len;
443 return param;
444}
445
446inline keymaster_key_param_t keymaster_param_bool(keymaster_tag_t tag) {
447 // assert(keymaster_tag_get_type(tag) == KM_BOOL);
448 keymaster_key_param_t param;
449 memset(&param, 0, sizeof(param));
450 param.tag = tag;
451 param.boolean = true;
452 return param;
453}
454
455inline keymaster_key_param_t keymaster_param_date(keymaster_tag_t tag, uint64_t value) {
456 // assert(keymaster_tag_get_type(tag) == KM_DATE);
457 keymaster_key_param_t param;
458 memset(&param, 0, sizeof(param));
459 param.tag = tag;
460 param.date_time = value;
461 return param;
462}
463
Shawn Willden67411d62015-03-04 10:00:38 -0700464#define KEYMASTER_SIMPLE_COMPARE(a, b) (a < b) ? -1 : ((a > b) ? 1 : 0)
465inline int keymaster_param_compare(const keymaster_key_param_t* a, const keymaster_key_param_t* b) {
466 int retval = KEYMASTER_SIMPLE_COMPARE(a->tag, b->tag);
467 if (retval != 0)
468 return retval;
469
470 switch (keymaster_tag_get_type(a->tag)) {
471 case KM_INVALID:
472 case KM_BOOL:
473 return 0;
474 case KM_ENUM:
475 case KM_ENUM_REP:
476 return KEYMASTER_SIMPLE_COMPARE(a->enumerated, b->enumerated);
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +0000477 case KM_UINT:
478 case KM_UINT_REP:
Shawn Willden67411d62015-03-04 10:00:38 -0700479 return KEYMASTER_SIMPLE_COMPARE(a->integer, b->integer);
Shawn Willdenfe6bcfa2015-06-24 20:59:14 +0000480 case KM_ULONG:
481 case KM_ULONG_REP:
Shawn Willden67411d62015-03-04 10:00:38 -0700482 return KEYMASTER_SIMPLE_COMPARE(a->long_integer, b->long_integer);
483 case KM_DATE:
484 return KEYMASTER_SIMPLE_COMPARE(a->date_time, b->date_time);
485 case KM_BIGNUM:
486 case KM_BYTES:
487 // Handle the empty cases.
488 if (a->blob.data_length != 0 && b->blob.data_length == 0)
489 return -1;
490 if (a->blob.data_length == 0 && b->blob.data_length == 0)
491 return 0;
492 if (a->blob.data_length == 0 && b->blob.data_length > 0)
493 return 1;
494
495 retval = memcmp(a->blob.data, b->blob.data, a->blob.data_length < b->blob.data_length
496 ? a->blob.data_length
497 : b->blob.data_length);
498 if (retval != 0)
499 return retval;
500 else if (a->blob.data_length != b->blob.data_length) {
501 // Equal up to the common length; longer one is larger.
502 if (a->blob.data_length < b->blob.data_length)
503 return -1;
504 if (a->blob.data_length > b->blob.data_length)
505 return 1;
506 };
507 }
508
509 return 0;
510}
511#undef KEYMASTER_SIMPLE_COMPARE
512
Shawn Willden9d645a02014-06-12 13:48:46 -0600513inline void keymaster_free_param_values(keymaster_key_param_t* param, size_t param_count) {
514 while (param_count-- > 0) {
515 switch (keymaster_tag_get_type(param->tag)) {
516 case KM_BIGNUM:
517 case KM_BYTES:
518 free((void*)param->blob.data);
519 param->blob.data = NULL;
520 break;
521 default:
522 // NOP
523 break;
524 }
525 ++param;
526 }
527}
528
529inline void keymaster_free_param_set(keymaster_key_param_set_t* set) {
530 if (set) {
531 keymaster_free_param_values(set->params, set->length);
532 free(set->params);
533 set->params = NULL;
534 }
535}
536
537inline void keymaster_free_characteristics(keymaster_key_characteristics_t* characteristics) {
538 if (characteristics) {
539 keymaster_free_param_set(&characteristics->hw_enforced);
540 keymaster_free_param_set(&characteristics->sw_enforced);
541 }
542}
543
Shawn Willden7eaa15f2015-06-03 09:03:20 -0600544#ifdef __cplusplus
Shawn Willdenc51d01e2015-03-18 18:59:52 -0600545} // extern "C"
546#endif // __cplusplus
Shawn Willden9d645a02014-06-12 13:48:46 -0600547
548#endif // ANDROID_HARDWARE_KEYMASTER_DEFS_H