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#ifdef __cplusplus 25extern "C" { 26#endif // __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 */ 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. */ 37 KM_UINT = 3 << 28, 38 KM_UINT_REP = 4 << 28, /* Repeatable integer value */ 39 KM_ULONG = 5 << 28, 40 KM_DATE = 6 << 28, 41 KM_BOOL = 7 << 28, 42 KM_BIGNUM = 8 << 28, 43 KM_BYTES = 9 << 28, 44 KM_ULONG_REP = 10 << 28, /* Repeatable long value */ 45} 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 */ 55 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) */ 66 67 /* Algorithm-specific. */ 68 KM_TAG_RSA_PUBLIC_EXPONENT = KM_ULONG | 200, 69 KM_TAG_ECIES_SINGLE_HASH_MODE = KM_BOOL | 201, /* Whether the ephemeral public key is fed into 70 * 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) */ 74 75 /* 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 79 /* 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. */ 90 KM_TAG_MIN_SECONDS_BETWEEN_OPS = KM_UINT | 403, /* Minimum elapsed time between 91 cryptographic operations with the key. */ 92 KM_TAG_MAX_USES_PER_BOOT = KM_UINT | 404, /* Number of times the key can be used per 93 boot. */ 94 95 /* User authentication */ 96 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. */ 112 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. */ 115 KM_TAG_UNLOCKED_DEVICE_REQUIRED = KM_BOOL | 508, /* Require the device screen to be unlocked if the 116 * key is used. */ 117 118 /* Application access control */ 119 KM_TAG_ALL_APPLICATIONS = KM_BOOL | 600, /* Specified to indicate key is usable by all 120 * applications. */ 121 KM_TAG_APPLICATION_ID = KM_BYTES | 601, /* Byte string identifying the authorized 122 * application. */ 123 KM_TAG_EXPORTABLE = KM_BOOL | 602, /* If true, private/secret key can be exported, but 124 * only if all access control requirements for use are 125 * met. (keymaster2) */ 126 127 /* 128 * Semantically unenforceable tags, either because they have no specific meaning or because 129 * they're informational only. 130 */ 131 KM_TAG_APPLICATION_DATA = KM_BYTES | 700, /* Data provided by authorized application. */ 132 KM_TAG_CREATION_DATETIME = KM_DATE | 701, /* Key creation time */ 133 KM_TAG_ORIGIN = KM_ENUM | 702, /* keymaster_key_origin_t. */ 134 KM_TAG_ROLLBACK_RESISTANT = KM_BOOL | 703, /* Whether key is rollback-resistant. */ 135 KM_TAG_ROOT_OF_TRUST = KM_BYTES | 704, /* Root of trust ID. */ 136 KM_TAG_OS_VERSION = KM_UINT | 705, /* Version of system (keymaster2) */ 137 KM_TAG_OS_PATCHLEVEL = KM_UINT | 706, /* Patch level of system (keymaster2) */ 138 KM_TAG_UNIQUE_ID = KM_BYTES | 707, /* Used to provide unique ID in attestation */ 139 KM_TAG_ATTESTATION_CHALLENGE = KM_BYTES | 708, /* Used to provide challenge in attestation */ 140 KM_TAG_ATTESTATION_APPLICATION_ID = KM_BYTES | 709, /* Used to identify the set of possible 141 * applications of which one has initiated 142 * a key attestation */ 143 KM_TAG_ATTESTATION_ID_BRAND = KM_BYTES | 710, /* Used to provide the device's brand name to be 144 included in attestation */ 145 KM_TAG_ATTESTATION_ID_DEVICE = KM_BYTES | 711, /* Used to provide the device's device name to be 146 included in attestation */ 147 KM_TAG_ATTESTATION_ID_PRODUCT = KM_BYTES | 712, /* Used to provide the device's product name to 148 be included in attestation */ 149 KM_TAG_ATTESTATION_ID_SERIAL = KM_BYTES | 713, /* Used to provide the device's serial number to 150 be included in attestation */ 151 KM_TAG_ATTESTATION_ID_IMEI = KM_BYTES | 714, /* Used to provide the device's IMEI to be 152 included in attestation */ 153 KM_TAG_ATTESTATION_ID_MEID = KM_BYTES | 715, /* Used to provide the device's MEID to be 154 included in attestation */ 155 KM_TAG_ATTESTATION_ID_MANUFACTURER = KM_BYTES | 716, /* Used to provide the device's 156 manufacturer name to be included in 157 attestation */ 158 KM_TAG_ATTESTATION_ID_MODEL = KM_BYTES | 717, /* Used to provide the device's model name to be 159 included in attestation */ 160 161 /* Tags used only to provide data to or receive data from operations */ 162 KM_TAG_ASSOCIATED_DATA = KM_BYTES | 1000, /* Used to provide associated data for AEAD modes. */ 163 KM_TAG_NONCE = KM_BYTES | 1001, /* Nonce or Initialization Vector */ 164 KM_TAG_AUTH_TOKEN = KM_BYTES | 1002, /* Authentication token that proves secure user 165 authentication has been performed. Structure 166 defined in hw_auth_token_t in hw_auth_token.h. */ 167 KM_TAG_MAC_LENGTH = KM_UINT | 1003, /* MAC or AEAD authentication tag length in 168 * bits. */ 169 170 KM_TAG_RESET_SINCE_ID_ROTATION = KM_BOOL | 1004, /* Whether the device has beeen factory reset 171 since the last unique ID rotation. Used for 172 key attestation. */ 173} keymaster_tag_t; 174 175/** 176 * Algorithms that may be provided by keymaster implementations. Those that must be provided by all 177 * implementations are tagged as "required". 178 */ 179typedef enum { 180 /* Asymmetric algorithms. */ 181 KM_ALGORITHM_RSA = 1, 182 // KM_ALGORITHM_DSA = 2, -- Removed, do not re-use value 2. 183 KM_ALGORITHM_EC = 3, 184 185 /* Block ciphers algorithms */ 186 KM_ALGORITHM_AES = 32, 187 KM_ALGORITHM_TRIPLE_DES = 33, 188 189 /* MAC algorithms */ 190 KM_ALGORITHM_HMAC = 128, 191} keymaster_algorithm_t; 192 193/** 194 * Symmetric block cipher modes provided by keymaster implementations. 195 */ 196typedef enum { 197 /* Unauthenticated modes, usable only for encryption/decryption and not generally recommended 198 * except for compatibility with existing other protocols. */ 199 KM_MODE_ECB = 1, 200 KM_MODE_CBC = 2, 201 KM_MODE_CTR = 3, 202 203 /* Authenticated modes, usable for encryption/decryption and signing/verification. Recommended 204 * over unauthenticated modes for all purposes. */ 205 KM_MODE_GCM = 32, 206} keymaster_block_mode_t; 207 208/** 209 * Padding modes that may be applied to plaintext for encryption operations. This list includes 210 * padding modes for both symmetric and asymmetric algorithms. Note that implementations should not 211 * provide all possible combinations of algorithm and padding, only the 212 * cryptographically-appropriate pairs. 213 */ 214typedef enum { 215 KM_PAD_NONE = 1, /* deprecated */ 216 KM_PAD_RSA_OAEP = 2, 217 KM_PAD_RSA_PSS = 3, 218 KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4, 219 KM_PAD_RSA_PKCS1_1_5_SIGN = 5, 220 KM_PAD_PKCS7 = 64, 221} keymaster_padding_t; 222 223/** 224 * Digests provided by keymaster implementations. 225 */ 226typedef enum { 227 KM_DIGEST_NONE = 0, 228 KM_DIGEST_MD5 = 1, /* Optional, may not be implemented in hardware, will be handled in software 229 * if needed. */ 230 KM_DIGEST_SHA1 = 2, 231 KM_DIGEST_SHA_2_224 = 3, 232 KM_DIGEST_SHA_2_256 = 4, 233 KM_DIGEST_SHA_2_384 = 5, 234 KM_DIGEST_SHA_2_512 = 6, 235} keymaster_digest_t; 236 237/* 238 * Key derivation functions, mostly used in ECIES. 239 */ 240typedef enum { 241 /* Do not apply a key derivation function; use the raw agreed key */ 242 KM_KDF_NONE = 0, 243 /* HKDF defined in RFC 5869 with SHA256 */ 244 KM_KDF_RFC5869_SHA256 = 1, 245 /* KDF1 defined in ISO 18033-2 with SHA1 */ 246 KM_KDF_ISO18033_2_KDF1_SHA1 = 2, 247 /* KDF1 defined in ISO 18033-2 with SHA256 */ 248 KM_KDF_ISO18033_2_KDF1_SHA256 = 3, 249 /* KDF2 defined in ISO 18033-2 with SHA1 */ 250 KM_KDF_ISO18033_2_KDF2_SHA1 = 4, 251 /* KDF2 defined in ISO 18033-2 with SHA256 */ 252 KM_KDF_ISO18033_2_KDF2_SHA256 = 5, 253} keymaster_kdf_t; 254 255/** 256 * Supported EC curves, used in ECDSA/ECIES. 257 */ 258typedef enum { 259 KM_EC_CURVE_P_224 = 0, 260 KM_EC_CURVE_P_256 = 1, 261 KM_EC_CURVE_P_384 = 2, 262 KM_EC_CURVE_P_521 = 3, 263} keymaster_ec_curve_t; 264 265/** 266 * The origin of a key (or pair), i.e. where it was generated. Note that KM_TAG_ORIGIN can be found 267 * in either the hardware-enforced or software-enforced list for a key, indicating whether the key 268 * is hardware or software-based. Specifically, a key with KM_ORIGIN_GENERATED in the 269 * hardware-enforced list is guaranteed never to have existed outide the secure hardware. 270 */ 271typedef enum { 272 KM_ORIGIN_GENERATED = 0, /* Generated in keymaster. Should not exist outside the TEE. */ 273 KM_ORIGIN_DERIVED = 1, /* Derived inside keymaster. Likely exists off-device. */ 274 KM_ORIGIN_IMPORTED = 2, /* Imported into keymaster. Existed as cleartext in Android. */ 275 KM_ORIGIN_UNKNOWN = 3, /* Keymaster did not record origin. This value can only be seen on 276 * keys in a keymaster0 implementation. The keymaster0 adapter uses 277 * this value to document the fact that it is unkown whether the key 278 * was generated inside or imported into keymaster. */ 279} keymaster_key_origin_t; 280 281/** 282 * Usability requirements of key blobs. This defines what system functionality must be available 283 * for the key to function. For example, key "blobs" which are actually handles referencing 284 * encrypted key material stored in the file system cannot be used until the file system is 285 * available, and should have BLOB_REQUIRES_FILE_SYSTEM. Other requirements entries will be added 286 * as needed for implementations. 287 */ 288typedef enum { 289 KM_BLOB_STANDALONE = 0, 290 KM_BLOB_REQUIRES_FILE_SYSTEM = 1, 291} keymaster_key_blob_usage_requirements_t; 292 293/** 294 * Possible purposes of a key (or pair). 295 */ 296typedef enum { 297 KM_PURPOSE_ENCRYPT = 0, /* Usable with RSA, EC and AES keys. */ 298 KM_PURPOSE_DECRYPT = 1, /* Usable with RSA, EC and AES keys. */ 299 KM_PURPOSE_SIGN = 2, /* Usable with RSA, EC and HMAC keys. */ 300 KM_PURPOSE_VERIFY = 3, /* Usable with RSA, EC and HMAC keys. */ 301 KM_PURPOSE_DERIVE_KEY = 4, /* Usable with EC keys. */ 302 KM_PURPOSE_WRAP = 5, /* Usable with wrapped keys. */ 303 304} keymaster_purpose_t; 305 306typedef struct { 307 const uint8_t* data; 308 size_t data_length; 309} keymaster_blob_t; 310 311typedef struct { 312 keymaster_tag_t tag; 313 union { 314 uint32_t enumerated; /* KM_ENUM and KM_ENUM_REP */ 315 bool boolean; /* KM_BOOL */ 316 uint32_t integer; /* KM_INT and KM_INT_REP */ 317 uint64_t long_integer; /* KM_LONG */ 318 uint64_t date_time; /* KM_DATE */ 319 keymaster_blob_t blob; /* KM_BIGNUM and KM_BYTES*/ 320 }; 321} keymaster_key_param_t; 322 323typedef struct { 324 keymaster_key_param_t* params; /* may be NULL if length == 0 */ 325 size_t length; 326} keymaster_key_param_set_t; 327 328/** 329 * Parameters that define a key's characteristics, including authorized modes of usage and access 330 * control restrictions. The parameters are divided into two categories, those that are enforced by 331 * secure hardware, and those that are not. For a software-only keymaster implementation the 332 * enforced array must NULL. Hardware implementations must enforce everything in the enforced 333 * array. 334 */ 335typedef struct { 336 keymaster_key_param_set_t hw_enforced; 337 keymaster_key_param_set_t sw_enforced; 338} keymaster_key_characteristics_t; 339 340typedef struct { 341 const uint8_t* key_material; 342 size_t key_material_size; 343} keymaster_key_blob_t; 344 345typedef struct { 346 keymaster_blob_t* entries; 347 size_t entry_count; 348} keymaster_cert_chain_t; 349 350typedef enum { 351 KM_VERIFIED_BOOT_VERIFIED = 0, /* Full chain of trust extending from the bootloader to 352 * verified partitions, including the bootloader, boot 353 * partition, and all verified partitions*/ 354 KM_VERIFIED_BOOT_SELF_SIGNED = 1, /* The boot partition has been verified using the embedded 355 * certificate, and the signature is valid. The bootloader 356 * displays a warning and the fingerprint of the public 357 * key before allowing the boot process to continue.*/ 358 KM_VERIFIED_BOOT_UNVERIFIED = 2, /* The device may be freely modified. Device integrity is left 359 * to the user to verify out-of-band. The bootloader 360 * displays a warning to the user before allowing the boot 361 * process to continue */ 362 KM_VERIFIED_BOOT_FAILED = 3, /* The device failed verification. The bootloader displays a 363 * warning and stops the boot process, so no keymaster 364 * implementation should ever actually return this value, 365 * since it should not run. Included here only for 366 * completeness. */ 367} keymaster_verified_boot_t; 368 369typedef enum { 370 KM_SECURITY_LEVEL_SOFTWARE = 0, 371 KM_SECURITY_LEVEL_TRUSTED_ENVIRONMENT = 1, 372} keymaster_security_level_t; 373 374/** 375 * Formats for key import and export. 376 */ 377typedef enum { 378 KM_KEY_FORMAT_X509 = 0, /* for public key export */ 379 KM_KEY_FORMAT_PKCS8 = 1, /* for asymmetric key pair import */ 380 KM_KEY_FORMAT_RAW = 3, /* for symmetric key import and export*/ 381} keymaster_key_format_t; 382 383/** 384 * The keymaster operation API consists of begin, update, finish and abort. This is the type of the 385 * handle used to tie the sequence of calls together. A 64-bit value is used because it's important 386 * that handles not be predictable. Implementations must use strong random numbers for handle 387 * values. 388 */ 389typedef uint64_t keymaster_operation_handle_t; 390 391typedef enum { 392 KM_ERROR_OK = 0, 393 KM_ERROR_ROOT_OF_TRUST_ALREADY_SET = -1, 394 KM_ERROR_UNSUPPORTED_PURPOSE = -2, 395 KM_ERROR_INCOMPATIBLE_PURPOSE = -3, 396 KM_ERROR_UNSUPPORTED_ALGORITHM = -4, 397 KM_ERROR_INCOMPATIBLE_ALGORITHM = -5, 398 KM_ERROR_UNSUPPORTED_KEY_SIZE = -6, 399 KM_ERROR_UNSUPPORTED_BLOCK_MODE = -7, 400 KM_ERROR_INCOMPATIBLE_BLOCK_MODE = -8, 401 KM_ERROR_UNSUPPORTED_MAC_LENGTH = -9, 402 KM_ERROR_UNSUPPORTED_PADDING_MODE = -10, 403 KM_ERROR_INCOMPATIBLE_PADDING_MODE = -11, 404 KM_ERROR_UNSUPPORTED_DIGEST = -12, 405 KM_ERROR_INCOMPATIBLE_DIGEST = -13, 406 KM_ERROR_INVALID_EXPIRATION_TIME = -14, 407 KM_ERROR_INVALID_USER_ID = -15, 408 KM_ERROR_INVALID_AUTHORIZATION_TIMEOUT = -16, 409 KM_ERROR_UNSUPPORTED_KEY_FORMAT = -17, 410 KM_ERROR_INCOMPATIBLE_KEY_FORMAT = -18, 411 KM_ERROR_UNSUPPORTED_KEY_ENCRYPTION_ALGORITHM = -19, /* For PKCS8 & PKCS12 */ 412 KM_ERROR_UNSUPPORTED_KEY_VERIFICATION_ALGORITHM = -20, /* For PKCS8 & PKCS12 */ 413 KM_ERROR_INVALID_INPUT_LENGTH = -21, 414 KM_ERROR_KEY_EXPORT_OPTIONS_INVALID = -22, 415 KM_ERROR_DELEGATION_NOT_ALLOWED = -23, 416 KM_ERROR_KEY_NOT_YET_VALID = -24, 417 KM_ERROR_KEY_EXPIRED = -25, 418 KM_ERROR_KEY_USER_NOT_AUTHENTICATED = -26, 419 KM_ERROR_OUTPUT_PARAMETER_NULL = -27, 420 KM_ERROR_INVALID_OPERATION_HANDLE = -28, 421 KM_ERROR_INSUFFICIENT_BUFFER_SPACE = -29, 422 KM_ERROR_VERIFICATION_FAILED = -30, 423 KM_ERROR_TOO_MANY_OPERATIONS = -31, 424 KM_ERROR_UNEXPECTED_NULL_POINTER = -32, 425 KM_ERROR_INVALID_KEY_BLOB = -33, 426 KM_ERROR_IMPORTED_KEY_NOT_ENCRYPTED = -34, 427 KM_ERROR_IMPORTED_KEY_DECRYPTION_FAILED = -35, 428 KM_ERROR_IMPORTED_KEY_NOT_SIGNED = -36, 429 KM_ERROR_IMPORTED_KEY_VERIFICATION_FAILED = -37, 430 KM_ERROR_INVALID_ARGUMENT = -38, 431 KM_ERROR_UNSUPPORTED_TAG = -39, 432 KM_ERROR_INVALID_TAG = -40, 433 KM_ERROR_MEMORY_ALLOCATION_FAILED = -41, 434 KM_ERROR_IMPORT_PARAMETER_MISMATCH = -44, 435 KM_ERROR_SECURE_HW_ACCESS_DENIED = -45, 436 KM_ERROR_OPERATION_CANCELLED = -46, 437 KM_ERROR_CONCURRENT_ACCESS_CONFLICT = -47, 438 KM_ERROR_SECURE_HW_BUSY = -48, 439 KM_ERROR_SECURE_HW_COMMUNICATION_FAILED = -49, 440 KM_ERROR_UNSUPPORTED_EC_FIELD = -50, 441 KM_ERROR_MISSING_NONCE = -51, 442 KM_ERROR_INVALID_NONCE = -52, 443 KM_ERROR_MISSING_MAC_LENGTH = -53, 444 KM_ERROR_KEY_RATE_LIMIT_EXCEEDED = -54, 445 KM_ERROR_CALLER_NONCE_PROHIBITED = -55, 446 KM_ERROR_KEY_MAX_OPS_EXCEEDED = -56, 447 KM_ERROR_INVALID_MAC_LENGTH = -57, 448 KM_ERROR_MISSING_MIN_MAC_LENGTH = -58, 449 KM_ERROR_UNSUPPORTED_MIN_MAC_LENGTH = -59, 450 KM_ERROR_UNSUPPORTED_KDF = -60, 451 KM_ERROR_UNSUPPORTED_EC_CURVE = -61, 452 KM_ERROR_KEY_REQUIRES_UPGRADE = -62, 453 KM_ERROR_ATTESTATION_CHALLENGE_MISSING = -63, 454 KM_ERROR_KEYMASTER_NOT_CONFIGURED = -64, 455 KM_ERROR_ATTESTATION_APPLICATION_ID_MISSING = -65, 456 KM_ERROR_CANNOT_ATTEST_IDS = -66, 457 KM_ERROR_DEVICE_LOCKED = -72, 458 459 KM_ERROR_UNIMPLEMENTED = -100, 460 KM_ERROR_VERSION_MISMATCH = -101, 461 462 KM_ERROR_UNKNOWN_ERROR = -1000, 463} keymaster_error_t; 464 465/* Convenience functions for manipulating keymaster tag types */ 466 467static inline keymaster_tag_type_t keymaster_tag_get_type(keymaster_tag_t tag) { 468 return (keymaster_tag_type_t)(tag & (0xF << 28)); 469} 470 471static inline uint32_t keymaster_tag_mask_type(keymaster_tag_t tag) { 472 return tag & 0x0FFFFFFF; 473} 474 475static inline bool keymaster_tag_type_repeatable(keymaster_tag_type_t type) { 476 switch (type) { 477 case KM_UINT_REP: 478 case KM_ENUM_REP: 479 return true; 480 default: 481 return false; 482 } 483} 484 485static inline bool keymaster_tag_repeatable(keymaster_tag_t tag) { 486 return keymaster_tag_type_repeatable(keymaster_tag_get_type(tag)); 487} 488 489/* Convenience functions for manipulating keymaster_key_param_t structs */ 490 491inline keymaster_key_param_t keymaster_param_enum(keymaster_tag_t tag, uint32_t value) { 492 // assert(keymaster_tag_get_type(tag) == KM_ENUM || keymaster_tag_get_type(tag) == KM_ENUM_REP); 493 keymaster_key_param_t param; 494 memset(¶m, 0, sizeof(param)); 495 param.tag = tag; 496 param.enumerated = value; 497 return param; 498} 499 500inline keymaster_key_param_t keymaster_param_int(keymaster_tag_t tag, uint32_t value) { 501 // assert(keymaster_tag_get_type(tag) == KM_INT || keymaster_tag_get_type(tag) == KM_INT_REP); 502 keymaster_key_param_t param; 503 memset(¶m, 0, sizeof(param)); 504 param.tag = tag; 505 param.integer = value; 506 return param; 507} 508 509inline keymaster_key_param_t keymaster_param_long(keymaster_tag_t tag, uint64_t value) { 510 // assert(keymaster_tag_get_type(tag) == KM_LONG); 511 keymaster_key_param_t param; 512 memset(¶m, 0, sizeof(param)); 513 param.tag = tag; 514 param.long_integer = value; 515 return param; 516} 517 518inline keymaster_key_param_t keymaster_param_blob(keymaster_tag_t tag, const uint8_t* bytes, 519 size_t bytes_len) { 520 // assert(keymaster_tag_get_type(tag) == KM_BYTES || keymaster_tag_get_type(tag) == KM_BIGNUM); 521 keymaster_key_param_t param; 522 memset(¶m, 0, sizeof(param)); 523 param.tag = tag; 524 param.blob.data = (uint8_t*)bytes; 525 param.blob.data_length = bytes_len; 526 return param; 527} 528 529inline keymaster_key_param_t keymaster_param_bool(keymaster_tag_t tag) { 530 // assert(keymaster_tag_get_type(tag) == KM_BOOL); 531 keymaster_key_param_t param; 532 memset(¶m, 0, sizeof(param)); 533 param.tag = tag; 534 param.boolean = true; 535 return param; 536} 537 538inline keymaster_key_param_t keymaster_param_date(keymaster_tag_t tag, uint64_t value) { 539 // assert(keymaster_tag_get_type(tag) == KM_DATE); 540 keymaster_key_param_t param; 541 memset(¶m, 0, sizeof(param)); 542 param.tag = tag; 543 param.date_time = value; 544 return param; 545} 546 547#define KEYMASTER_SIMPLE_COMPARE(a, b) (a < b) ? -1 : ((a > b) ? 1 : 0) 548inline int keymaster_param_compare(const keymaster_key_param_t* a, const keymaster_key_param_t* b) { 549 int retval = KEYMASTER_SIMPLE_COMPARE((uint32_t)a->tag, (uint32_t)b->tag); 550 if (retval != 0) 551 return retval; 552 553 switch (keymaster_tag_get_type(a->tag)) { 554 case KM_INVALID: 555 case KM_BOOL: 556 return 0; 557 case KM_ENUM: 558 case KM_ENUM_REP: 559 return KEYMASTER_SIMPLE_COMPARE(a->enumerated, b->enumerated); 560 case KM_UINT: 561 case KM_UINT_REP: 562 return KEYMASTER_SIMPLE_COMPARE(a->integer, b->integer); 563 case KM_ULONG: 564 case KM_ULONG_REP: 565 return KEYMASTER_SIMPLE_COMPARE(a->long_integer, b->long_integer); 566 case KM_DATE: 567 return KEYMASTER_SIMPLE_COMPARE(a->date_time, b->date_time); 568 case KM_BIGNUM: 569 case KM_BYTES: 570 // Handle the empty cases. 571 if (a->blob.data_length != 0 && b->blob.data_length == 0) 572 return -1; 573 if (a->blob.data_length == 0 && b->blob.data_length == 0) 574 return 0; 575 if (a->blob.data_length == 0 && b->blob.data_length > 0) 576 return 1; 577 578 retval = memcmp(a->blob.data, b->blob.data, a->blob.data_length < b->blob.data_length 579 ? a->blob.data_length 580 : b->blob.data_length); 581 if (retval != 0) 582 return retval; 583 else if (a->blob.data_length != b->blob.data_length) { 584 // Equal up to the common length; longer one is larger. 585 if (a->blob.data_length < b->blob.data_length) 586 return -1; 587 if (a->blob.data_length > b->blob.data_length) 588 return 1; 589 }; 590 } 591 592 return 0; 593} 594#undef KEYMASTER_SIMPLE_COMPARE 595 596inline void keymaster_free_param_values(keymaster_key_param_t* param, size_t param_count) { 597 while (param_count > 0) { 598 param_count--; 599 switch (keymaster_tag_get_type(param->tag)) { 600 case KM_BIGNUM: 601 case KM_BYTES: 602 free((void*)param->blob.data); 603 param->blob.data = NULL; 604 break; 605 default: 606 // NOP 607 break; 608 } 609 ++param; 610 } 611} 612 613inline void keymaster_free_param_set(keymaster_key_param_set_t* set) { 614 if (set) { 615 keymaster_free_param_values(set->params, set->length); 616 free(set->params); 617 set->params = NULL; 618 set->length = 0; 619 } 620} 621 622inline void keymaster_free_characteristics(keymaster_key_characteristics_t* characteristics) { 623 if (characteristics) { 624 keymaster_free_param_set(&characteristics->hw_enforced); 625 keymaster_free_param_set(&characteristics->sw_enforced); 626 } 627} 628 629inline void keymaster_free_cert_chain(keymaster_cert_chain_t* chain) { 630 if (chain) { 631 for (size_t i = 0; i < chain->entry_count; ++i) { 632 free((uint8_t*)chain->entries[i].data); 633 chain->entries[i].data = NULL; 634 chain->entries[i].data_length = 0; 635 } 636 free(chain->entries); 637 chain->entries = NULL; 638 chain->entry_count = 0; 639 } 640} 641 642#ifdef __cplusplus 643} // extern "C" 644#endif // __cplusplus 645 646#endif // ANDROID_HARDWARE_KEYMASTER_DEFS_H 647