1 /* 2 * Copyright (C) 2014 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef ANDROID_HARDWARE_KEYMASTER_DEFS_H 18 #define ANDROID_HARDWARE_KEYMASTER_DEFS_H 19 20 #include <stdint.h> 21 #include <stdlib.h> 22 #include <string.h> 23 24 #if defined(__cplusplus) 25 extern "C" { 26 #endif // defined(__cplusplus) 27 28 /** 29 * Authorization tags each have an associated type. This enumeration facilitates tagging each with 30 * a type, by using the high four bits (of an implied 32-bit unsigned enum value) to specify up to 31 * 16 data types. These values are ORed with tag IDs to generate the final tag ID values. 32 */ 33 typedef enum { 34 KM_INVALID = 0 << 28, /* Invalid type, used to designate a tag as uninitialized */ 35 KM_ENUM = 1 << 28, 36 KM_ENUM_REP = 2 << 28, /* Repeatable enumeration value. */ 37 KM_INT = 3 << 28, 38 KM_INT_REP = 4 << 28, /* Repeatable integer value */ 39 KM_LONG = 5 << 28, 40 KM_DATE = 6 << 28, 41 KM_BOOL = 7 << 28, 42 KM_BIGNUM = 8 << 28, 43 KM_BYTES = 9 << 28, 44 } keymaster_tag_type_t; 45 46 typedef enum { 47 KM_TAG_INVALID = KM_INVALID | 0, 48 49 /* 50 * Tags that must be semantically enforced by hardware and software implementations. 51 */ 52 53 /* Crypto parameters */ 54 KM_TAG_PURPOSE = KM_ENUM_REP | 1, /* keymaster_purpose_t. */ 55 KM_TAG_ALGORITHM = KM_ENUM | 2, /* keymaster_algorithm_t. */ 56 KM_TAG_KEY_SIZE = KM_INT | 3, /* Key size in bits. */ 57 KM_TAG_BLOCK_MODE = KM_ENUM | 4, /* keymaster_block_mode_t. */ 58 KM_TAG_DIGEST = KM_ENUM | 5, /* keymaster_digest_t. */ 59 KM_TAG_MAC_LENGTH = KM_INT | 6, /* MAC length in bits. */ 60 KM_TAG_PADDING = KM_ENUM | 7, /* keymaster_padding_t. */ 61 KM_TAG_CHUNK_LENGTH = KM_INT | 8, /* AEAD mode minimum decryption chunk size, in bytes. */ 62 63 /* Other hardware-enforced. */ 64 KM_TAG_RESCOPING_ADD = KM_ENUM_REP | 101, /* Tags authorized for addition via rescoping. */ 65 KM_TAG_RESCOPING_DEL = KM_ENUM_REP | 102, /* Tags authorized for removal via rescoping. */ 66 KM_TAG_BLOB_USAGE_REQUIREMENTS = KM_ENUM | 705, /* keymaster_key_blob_usage_requirements_t */ 67 68 /* Algorithm-specific. */ 69 KM_TAG_RSA_PUBLIC_EXPONENT = KM_LONG | 200, /* Defaults to 2^16+1 */ 70 KM_TAG_DSA_GENERATOR = KM_BIGNUM | 201, 71 KM_TAG_DSA_P = KM_BIGNUM | 202, 72 KM_TAG_DSA_Q = KM_BIGNUM | 203, 73 /* Note there are no EC-specific params. Field size is defined by KM_TAG_KEY_SIZE, and the 74 curve is chosen from NIST recommendations for field size */ 75 76 /* 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. */ 87 KM_TAG_MIN_SECONDS_BETWEEN_OPS = KM_INT | 403, /* Minimum elapsed time between 88 cryptographic operations with the key. */ 89 KM_TAG_SINGLE_USE_PER_BOOT = KM_BOOL | 404, /* If true, the key can only be used once 90 per boot. */ 91 92 /* User authentication */ 93 KM_TAG_ALL_USERS = KM_BOOL | 500, /* If key is usable by all users. */ 94 KM_TAG_USER_ID = KM_INT | 501, /* ID of authorized user. Disallowed if KM_TAG_ALL_USERS is 95 present. */ 96 KM_TAG_NO_AUTH_REQUIRED = KM_BOOL | 502, /* If key is usable without authentication. */ 97 KM_TAG_USER_AUTH_ID = KM_INT_REP | 503, /* ID of the authenticator to use (e.g. password, 98 fingerprint, etc.). Repeatable to support 99 multi-factor auth. Disallowed if 100 KM_TAG_NO_AUTH_REQUIRED is present. */ 101 KM_TAG_AUTH_TIMEOUT = KM_INT | 504, /* Required freshness of user authentication for 102 private/secret key operations, in seconds. 103 Public key operations require no authentication. 104 If absent, authentication is required for every 105 use. Authentication state is lost when the 106 device is powered off. */ 107 KM_TAG_RESCOPE_AUTH_TIMEOUT = KM_INT | 505, /* Required freshness of user authentication for key 108 rescoping operations, in seconds. Public key 109 operations require no authentication. If absent, 110 authentication required for every rescoping. */ 111 112 /* Application access control */ 113 KM_TAG_ALL_APPLICATIONS = KM_BOOL | 600, /* If key is usable by all applications. */ 114 KM_TAG_APPLICATION_ID = KM_BYTES | 601, /* ID of authorized application. Disallowed if 115 KM_TAG_ALL_APPLICATIONS is present. */ 116 117 /* 118 * Semantically unenforceable tags, either because they have no specific meaning or because 119 * they're informational only. 120 */ 121 KM_TAG_APPLICATION_DATA = KM_BYTES | 700, /* Data provided by authorized application. */ 122 KM_TAG_CREATION_DATETIME = KM_DATE | 701, /* Key creation time */ 123 KM_TAG_ORIGIN = KM_ENUM | 702, /* keymaster_key_origin_t. */ 124 KM_TAG_ROLLBACK_RESISTANT = KM_BOOL | 703, /* Whether key is rollback-resistant. */ 125 KM_TAG_ROOT_OF_TRUST = KM_BYTES | 704, /* Root of trust ID. Empty array means usable by all 126 roots. */ 127 128 /* Tags used only to provide data to operations */ 129 KM_TAG_ADDITIONAL_DATA = KM_BYTES | 1000, /* Used to provide additional data for AEAD modes. */ 130 } keymaster_tag_t; 131 132 /** 133 * Algorithms that may be provided by keymaster implementations. Those that must be provided by all 134 * implementations are tagged as "required". Note that where the values in this enumeration overlap 135 * with the values for the deprecated keymaster_keypair_t, the same algorithm must be 136 * specified. This type is new in 0_4 and replaces the deprecated keymaster_keypair_t. 137 */ 138 typedef enum { 139 /* Asymmetric algorithms. */ 140 KM_ALGORITHM_RSA = 1, /* required */ 141 KM_ALGORITHM_DSA = 2, /* required */ 142 KM_ALGORITHM_ECDSA = 3, /* required */ 143 KM_ALGORITHM_ECIES = 4, 144 /* FIPS Approved Ciphers */ 145 KM_ALGORITHM_AES = 32, /* required */ 146 KM_ALGORITHM_3DES = 33, 147 KM_ALGORITHM_SKIPJACK = 34, 148 /* AES Finalists */ 149 KM_ALGORITHM_MARS = 48, 150 KM_ALGORITHM_RC6 = 49, 151 KM_ALGORITHM_SERPENT = 50, 152 KM_ALGORITHM_TWOFISH = 51, 153 /* Other common block ciphers */ 154 KM_ALGORITHM_IDEA = 52, 155 KM_ALGORITHM_RC5 = 53, 156 KM_ALGORITHM_CAST5 = 54, 157 KM_ALGORITHM_BLOWFISH = 55, 158 /* Common stream ciphers */ 159 KM_ALGORITHM_RC4 = 64, 160 KM_ALGORITHM_CHACHA20 = 65, 161 /* MAC algorithms */ 162 KM_ALGORITHM_HMAC = 128, /* required */ 163 } keymaster_algorithm_t; 164 165 /** 166 * Symmetric block cipher modes that may be provided by keymaster implementations. Those that must 167 * be provided by all implementations are tagged as "required". This type is new in 0_4. 168 */ 169 typedef enum { 170 /* Unauthenticated modes, usable only for encryption/decryption and not generally recommended 171 * except for compatibility with existing other protocols. */ 172 KM_MODE_ECB = 1, /* required */ 173 KM_MODE_CBC = 2, /* required */ 174 KM_MODE_CBC_CTS = 3, /* recommended */ 175 KM_MODE_CTR = 4, /* recommended */ 176 KM_MODE_OFB = 5, 177 KM_MODE_CFB = 6, 178 KM_MODE_XTS = 7, /* Note: requires double-length keys */ 179 /* Authenticated modes, usable for encryption/decryption and signing/verification. Recommended 180 * over unauthenticated modes for all purposes. One of KM_MODE_GCM and KM_MODE_OCB is 181 * required. */ 182 KM_MODE_GCM = 32, 183 KM_MODE_OCB = 33, 184 KM_MODE_CCM = 34, 185 /* MAC modes -- only for signing/verification */ 186 KM_MODE_CMAC = 128, 187 KM_MODE_POLY1305 = 129, 188 } keymaster_block_mode_t; 189 190 /** 191 * Padding modes that may be applied to plaintext for encryption operations. This list includes 192 * padding modes for both symmetric and asymmetric algorithms. Note that implementations should not 193 * provide all possible combinations of algorithm and padding, only the 194 * cryptographically-appropriate pairs. 195 */ 196 typedef enum { 197 KM_PAD_NONE = 1, /* required, deprecated */ 198 KM_PAD_RSA_OAEP = 2, /* required */ 199 KM_PAD_RSA_PSS = 3, /* required */ 200 KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4, 201 KM_PAD_RSA_PKCS1_1_5_SIGN = 5, 202 KM_PAD_ANSI_X923 = 32, 203 KM_PAD_ISO_10126 = 33, 204 KM_PAD_ZERO = 64, /* required */ 205 KM_PAD_PKCS7 = 65, /* required */ 206 KM_PAD_ISO_7816_4 = 66, 207 } keymaster_padding_t; 208 209 #ifndef ANDROID_HARDWARE_KEYMASTER_H 210 211 /** 212 * Digests that may be provided by keymaster implementations. Those that must be provided by all 213 * implementations are tagged as "required". Those that have been added since version 0_2 of the 214 * API are tagged as "new". 215 */ 216 typedef enum { 217 KM_DIGEST_NONE = 0, /* new, required */ 218 DIGEST_NONE = KM_DIGEST_NONE, /* For 0_2 compatibility */ 219 KM_DIGEST_MD5 = 1, /* new, for compatibility with old protocols only */ 220 KM_DIGEST_SHA1 = 2, /* new */ 221 KM_DIGEST_SHA_2_224 = 3, /* new */ 222 KM_DIGEST_SHA_2_256 = 4, /* new, required */ 223 KM_DIGEST_SHA_2_384 = 5, /* new, recommended */ 224 KM_DIGEST_SHA_2_512 = 6, /* new, recommended */ 225 KM_DIGEST_SHA_3_256 = 7, /* new */ 226 KM_DIGEST_SHA_3_384 = 8, /* new */ 227 KM_DIGEST_SHA_3_512 = 9, /* new */ 228 } keymaster_digest_t; 229 230 #endif // ANDROID_HARDWARE_KEYMASTER_H 231 232 /** 233 * The origin of a key (or pair), i.e. where it was generated. Origin and can be used together to 234 * determine whether a key may have existed outside of secure hardware. This type is new in 0_4. 235 */ 236 typedef enum { 237 KM_ORIGIN_HARDWARE = 0, /* Generated in secure hardware */ 238 KM_ORIGIN_SOFTWARE = 1, /* Generated in non-secure software */ 239 KM_ORIGIN_IMPORTED = 2, /* Imported, origin unknown */ 240 } keymaster_key_origin_t; 241 242 /** 243 * Usability requirements of key blobs. This defines what system functionality must be available 244 * for the key to function. For example, key "blobs" which are actually handles referencing 245 * encrypted key material stored in the file system cannot be used until the file system is 246 * available, and should have BLOB_REQUIRES_FILE_SYSTEM. Other requirements entries will be added 247 * as needed for implementations. This type is new in 0_4. 248 */ 249 typedef enum { 250 KM_BLOB_STANDALONE = 0, 251 KM_BLOB_REQUIRES_FILE_SYSTEM = 1, 252 } keymaster_key_blob_usage_requirements_t; 253 254 /** 255 * Possible purposes of a key (or pair). This type is new in 0_4. 256 */ 257 typedef enum { 258 KM_PURPOSE_ENCRYPT = 0, 259 KM_PURPOSE_DECRYPT = 1, 260 KM_PURPOSE_SIGN = 2, 261 KM_PURPOSE_VERIFY = 3, 262 } keymaster_purpose_t; 263 264 typedef struct { 265 const uint8_t* data; 266 size_t data_length; 267 } keymaster_blob_t; 268 269 typedef struct { 270 keymaster_tag_t tag; 271 union { 272 uint32_t enumerated; /* KM_ENUM and KM_ENUM_REP */ 273 bool boolean; /* KM_BOOL */ 274 uint32_t integer; /* KM_INT and KM_INT_REP */ 275 uint64_t long_integer; /* KM_LONG */ 276 uint64_t date_time; /* KM_DATE */ 277 keymaster_blob_t blob; /* KM_BIGNUM and KM_BYTES*/ 278 }; 279 } keymaster_key_param_t; 280 281 /** 282 * Parameters that define a key's characteristics, including authorized modes of usage and access 283 * control restrictions. The parameters are divided into two categories, those that are enforced by 284 * secure hardware, and those that are not. For a software-only keymaster implementation the 285 * enforced array must NULL. Hardware implementations must enforce everything in the enforced 286 * array. 287 */ 288 typedef struct { 289 keymaster_key_param_t* enforced; /* NULL if enforced_length == 0 */ 290 size_t enforced_length; 291 keymaster_key_param_t* unenforced; /* NULL if unenforced_length == 0 */ 292 size_t unenforced_length; 293 } keymaster_key_characteristics_t; 294 295 typedef struct { 296 const uint8_t* key_material; 297 size_t key_material_size; 298 } keymaster_key_blob_t; 299 300 /** 301 * Formats for key import and export. At present, only asymmetric key import/export is supported. 302 * In the future this list will expand greatly to accommodate asymmetric key import/export. 303 */ 304 typedef enum { 305 KM_KEY_FORMAT_X509, /* for public key export, required */ 306 KM_KEY_FORMAT_PKCS8, /* for asymmetric key pair import, required */ 307 KM_KEY_FORMAT_PKCS12, /* for asymmetric key pair import, not required */ 308 } keymaster_key_format_t; 309 310 /** 311 * The keymaster operation API consists of begin, update, finish and abort. This is the type of the 312 * handle used to tie the sequence of calls together. A 64-bit value is used because it's important 313 * that handles not be predictable. Implementations must use strong random numbers for handle 314 * values. 315 */ 316 typedef uint64_t keymaster_operation_handle_t; 317 318 typedef enum { 319 KM_ERROR_OK = 0, 320 KM_ERROR_ROOT_OF_TRUST_ALREADY_SET = -1, 321 KM_ERROR_UNSUPPORTED_PURPOSE = -2, 322 KM_ERROR_INCOMPATIBLE_PURPOSE = -3, 323 KM_ERROR_UNSUPPORTED_ALGORITHM = -4, 324 KM_ERROR_INCOMPATIBLE_ALGORITHM = -5, 325 KM_ERROR_UNSUPPORTED_KEY_SIZE = -6, 326 KM_ERROR_UNSUPPORTED_BLOCK_MODE = -7, 327 KM_ERROR_INCOMPATIBLE_BLOCK_MODE = -8, 328 KM_ERROR_UNSUPPORTED_TAG_LENGTH = -9, 329 KM_ERROR_UNSUPPORTED_PADDING_MODE = -10, 330 KM_ERROR_INCOMPATIBLE_PADDING_MODE = -11, 331 KM_ERROR_UNSUPPORTED_DIGEST = -12, 332 KM_ERROR_INCOMPATIBLE_DIGEST = -13, 333 KM_ERROR_INVALID_EXPIRATION_TIME = -14, 334 KM_ERROR_INVALID_USER_ID = -15, 335 KM_ERROR_INVALID_AUTHORIZATION_TIMEOUT = -16, 336 KM_ERROR_UNSUPPORTED_KEY_FORMAT = -17, 337 KM_ERROR_INCOMPATIBLE_KEY_FORMAT = -18, 338 KM_ERROR_UNSUPPORTED_KEY_ENCRYPTION_ALGORITHM = -19, /* For PKCS8 & PKCS12 */ 339 KM_ERROR_UNSUPPORTED_KEY_VERIFICATION_ALGORITHM = -20, /* For PKCS8 & PKCS12 */ 340 KM_ERROR_INVALID_INPUT_LENGTH = -21, 341 KM_ERROR_KEY_EXPORT_OPTIONS_INVALID = -22, 342 KM_ERROR_DELEGATION_NOT_ALLOWED = -23, 343 KM_ERROR_KEY_NOT_YET_VALID = -24, 344 KM_ERROR_KEY_EXPIRED = -25, 345 KM_ERROR_KEY_USER_NOT_AUTHENTICATED = -26, 346 KM_ERROR_OUTPUT_PARAMETER_NULL = -27, 347 KM_ERROR_INVALID_OPERATION_HANDLE = -28, 348 KM_ERROR_INSUFFICIENT_BUFFER_SPACE = -29, 349 KM_ERROR_VERIFICATION_FAILED = -30, 350 KM_ERROR_TOO_MANY_OPERATIONS = -31, 351 KM_ERROR_UNEXPECTED_NULL_POINTER = -32, 352 KM_ERROR_INVALID_KEY_BLOB = -33, 353 KM_ERROR_IMPORTED_KEY_NOT_ENCRYPTED = -34, 354 KM_ERROR_IMPORTED_KEY_DECRYPTION_FAILED = -35, 355 KM_ERROR_IMPORTED_KEY_NOT_SIGNED = -36, 356 KM_ERROR_IMPORTED_KEY_VERIFICATION_FAILED = -37, 357 KM_ERROR_INVALID_ARGUMENT = -38, 358 KM_ERROR_UNSUPPORTED_TAG = -39, 359 KM_ERROR_INVALID_TAG = -40, 360 KM_ERROR_MEMORY_ALLOCATION_FAILED = -41, 361 KM_ERROR_INVALID_RESCOPING = -42, 362 KM_ERROR_INVALID_DSA_PARAMS = -43, 363 KM_ERROR_IMPORT_PARAMETER_MISMATCH =-44, 364 KM_ERROR_SECURE_HW_ACCESS_DENIED = -45, 365 KM_ERROR_OPERATION_CANCELLED =-46, 366 KM_ERROR_CONCURRENT_ACCESS_CONFLICT = -47, 367 KM_ERROR_SECURE_HW_BUSY =-48, 368 KM_ERROR_SECURE_HW_COMMUNICATION_FAILED = -49, 369 KM_ERROR_UNSUPPORTED_EC_FIELD = -50, 370 KM_ERROR_UNIMPLEMENTED = -100, 371 372 /* Additional error codes may be added by implementations, but implementers should coordinate 373 * with Google to avoid code collision. */ 374 KM_ERROR_UNKNOWN_ERROR = -1000, 375 } keymaster_error_t; 376 377 /* Convenience functions for manipulating keymaster tag types */ 378 379 static inline keymaster_tag_type_t keymaster_tag_get_type(keymaster_tag_t tag) { 380 return (keymaster_tag_type_t)(tag & (0xF << 28)); 381 } 382 383 static inline uint32_t keymaster_tag_mask_type(keymaster_tag_t tag) { 384 return tag & 0x0FFFFFFF; 385 } 386 387 static inline bool keymaster_tag_type_repeatable(keymaster_tag_type_t type) { 388 switch (type) { 389 case KM_INT_REP: 390 case KM_ENUM_REP: 391 return true; 392 default: 393 return false; 394 } 395 } 396 397 static inline bool keymaster_tag_repeatable(keymaster_tag_t tag) { 398 return keymaster_tag_type_repeatable(keymaster_tag_get_type(tag)); 399 } 400 401 /* Convenience functions for manipulating keymaster_key_param_t structs */ 402 403 inline keymaster_key_param_t keymaster_param_enum(keymaster_tag_t tag, uint32_t value) { 404 // assert(keymaster_tag_get_type(tag) == KM_ENUM || keymaster_tag_get_type(tag) == KM_ENUM_REP); 405 keymaster_key_param_t param; 406 memset(¶m, 0, sizeof(param)); 407 param.tag = tag; 408 param.enumerated = value; 409 return param; 410 } 411 412 inline keymaster_key_param_t keymaster_param_int(keymaster_tag_t tag, uint32_t value) { 413 // assert(keymaster_tag_get_type(tag) == KM_INT || keymaster_tag_get_type(tag) == KM_INT_REP); 414 keymaster_key_param_t param; 415 memset(¶m, 0, sizeof(param)); 416 param.tag = tag; 417 param.integer = value; 418 return param; 419 } 420 421 inline keymaster_key_param_t keymaster_param_long(keymaster_tag_t tag, uint64_t value) { 422 // assert(keymaster_tag_get_type(tag) == KM_LONG); 423 keymaster_key_param_t param; 424 memset(¶m, 0, sizeof(param)); 425 param.tag = tag; 426 param.long_integer = value; 427 return param; 428 } 429 430 inline keymaster_key_param_t keymaster_param_blob(keymaster_tag_t tag, const uint8_t* bytes, 431 size_t bytes_len) { 432 // assert(keymaster_tag_get_type(tag) == KM_BYTES || keymaster_tag_get_type(tag) == KM_BIGNUM); 433 keymaster_key_param_t param; 434 memset(¶m, 0, sizeof(param)); 435 param.tag = tag; 436 param.blob.data = bytes; 437 param.blob.data_length = bytes_len; 438 return param; 439 } 440 441 inline keymaster_key_param_t keymaster_param_bool(keymaster_tag_t tag) { 442 // assert(keymaster_tag_get_type(tag) == KM_BOOL); 443 keymaster_key_param_t param; 444 memset(¶m, 0, sizeof(param)); 445 param.tag = tag; 446 param.boolean = true; 447 return param; 448 } 449 450 inline keymaster_key_param_t keymaster_param_date(keymaster_tag_t tag, uint64_t value) { 451 // assert(keymaster_tag_get_type(tag) == KM_DATE); 452 keymaster_key_param_t param; 453 memset(¶m, 0, sizeof(param)); 454 param.tag = tag; 455 param.date_time = value; 456 return param; 457 } 458 459 static inline void keymaster_free_param_values(keymaster_key_param_t* param, size_t param_count) { 460 while (param_count-- > 0) { 461 switch (keymaster_tag_get_type(param->tag)) { 462 case KM_BIGNUM: 463 case KM_BYTES: 464 free((void*)param->blob.data); 465 break; 466 default: 467 // NOP 468 break; 469 } 470 ++param; 471 } 472 } 473 474 #if defined(__cplusplus) 475 } // extern "C" 476 #endif // defined(__cplusplus) 477 478 #endif // ANDROID_HARDWARE_KEYMASTER_DEFS_H 479
