1 /* 2 * Copyright (C) 2017 The Android Open Source Project 3 * 4 * Permission is hereby granted, free of charge, to any person 5 * obtaining a copy of this software and associated documentation 6 * files (the "Software"), to deal in the Software without 7 * restriction, including without limitation the rights to use, copy, 8 * modify, merge, publish, distribute, sublicense, and/or sell copies 9 * of the Software, and to permit persons to whom the Software is 10 * furnished to do so, subject to the following conditions: 11 * 12 * The above copyright notice and this permission notice shall be 13 * included in all copies or substantial portions of the Software. 14 * 15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 16 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 18 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 19 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 20 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 21 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 22 * SOFTWARE. 23 */ 24 25 #ifndef TRUSTY_INTERFACE_KEYMASTER_H_ 26 #define TRUSTY_INTERFACE_KEYMASTER_H_ 27 28 #include <trusty/sysdeps.h> 29 30 #define KEYMASTER_PORT "com.android.trusty.keymaster" 31 #define KEYMASTER_MAX_BUFFER_LENGTH 4096 32 33 enum keymaster_command { 34 KEYMASTER_RESP_BIT = 1, 35 KEYMASTER_STOP_BIT = 2, 36 KEYMASTER_REQ_SHIFT = 2, 37 38 KM_GENERATE_KEY = (0 << KEYMASTER_REQ_SHIFT), 39 KM_BEGIN_OPERATION = (1 << KEYMASTER_REQ_SHIFT), 40 KM_UPDATE_OPERATION = (2 << KEYMASTER_REQ_SHIFT), 41 KM_FINISH_OPERATION = (3 << KEYMASTER_REQ_SHIFT), 42 KM_ABORT_OPERATION = (4 << KEYMASTER_REQ_SHIFT), 43 KM_IMPORT_KEY = (5 << KEYMASTER_REQ_SHIFT), 44 45 KM_EXPORT_KEY = (6 << KEYMASTER_REQ_SHIFT), 46 KM_GET_VERSION = (7 << KEYMASTER_REQ_SHIFT), 47 KM_ADD_RNG_ENTROPY = (8 << KEYMASTER_REQ_SHIFT), 48 KM_GET_SUPPORTED_ALGORITHMS = (9 << KEYMASTER_REQ_SHIFT), 49 KM_GET_SUPPORTED_BLOCK_MODES = (10 << KEYMASTER_REQ_SHIFT), 50 KM_GET_SUPPORTED_PADDING_MODES = (11 << KEYMASTER_REQ_SHIFT), 51 KM_GET_SUPPORTED_DIGESTS = (12 << KEYMASTER_REQ_SHIFT), 52 KM_GET_SUPPORTED_IMPORT_FORMATS = (13 << KEYMASTER_REQ_SHIFT), 53 KM_GET_SUPPORTED_EXPORT_FORMATS = (14 << KEYMASTER_REQ_SHIFT), 54 KM_GET_KEY_CHARACTERISTICS = (15 << KEYMASTER_REQ_SHIFT), 55 56 // Bootloader calls. 57 KM_SET_BOOT_PARAMS = (0x1000 << KEYMASTER_REQ_SHIFT), 58 KM_SET_ATTESTATION_KEY = (0x2000 << KEYMASTER_REQ_SHIFT), 59 KM_APPEND_ATTESTATION_CERT_CHAIN = (0x3000 << KEYMASTER_REQ_SHIFT), 60 KM_ATAP_GET_CA_REQUEST = (0x4000 << KEYMASTER_REQ_SHIFT), 61 KM_ATAP_SET_CA_RESPONSE_BEGIN = (0x5000 << KEYMASTER_REQ_SHIFT), 62 KM_ATAP_SET_CA_RESPONSE_UPDATE = (0x6000 << KEYMASTER_REQ_SHIFT), 63 KM_ATAP_SET_CA_RESPONSE_FINISH = (0x7000 << KEYMASTER_REQ_SHIFT), 64 KM_ATAP_READ_UUID = (0x8000 << KEYMASTER_REQ_SHIFT), 65 KM_SET_PRODUCT_ID = (0x9000 << KEYMASTER_REQ_SHIFT) 66 }; 67 68 typedef enum { 69 /* 70 * Full chain of trust extending from the bootloader to verified partitions, 71 * including the bootloader, boot partition, and all verified partitions. 72 */ 73 KM_VERIFIED_BOOT_VERIFIED = 0, 74 /* 75 * The boot partition has been verified using the embedded certificate, and 76 * the signature is valid. The bootloader displays a warning and the 77 * fingerprint of the public key before allowing the boot process to 78 * continue. 79 */ 80 KM_VERIFIED_BOOT_SELF_SIGNED = 1, 81 /* 82 * The device may be freely modified. Device integrity is left to the user 83 * to verify out-of-band. The bootloader displays a warning to the user 84 * before allowing the boot process to continue 85 */ 86 KM_VERIFIED_BOOT_UNVERIFIED = 2, 87 /* 88 * The device failed verification. The bootloader displays a warning and 89 * stops the boot process, so no keymaster implementation should ever 90 * actually return this value, since it should not run. Included here only 91 * for completeness. 92 */ 93 KM_VERIFIED_BOOT_FAILED = 3, 94 } keymaster_verified_boot_t; 95 96 /** 97 * Algorithms that may be provided by keymaster implementations. 98 */ 99 typedef enum { 100 /* Asymmetric algorithms. */ 101 KM_ALGORITHM_RSA = 1, 102 // KM_ALGORITHM_DSA = 2, -- Removed, do not re-use value 2. 103 KM_ALGORITHM_EC = 3, 104 105 /* Block ciphers algorithms */ 106 KM_ALGORITHM_AES = 32, 107 108 /* MAC algorithms */ 109 KM_ALGORITHM_HMAC = 128, 110 } keymaster_algorithm_t; 111 112 typedef enum { 113 KM_ERROR_OK = 0, 114 KM_ERROR_ROOT_OF_TRUST_ALREADY_SET = -1, 115 KM_ERROR_UNSUPPORTED_PURPOSE = -2, 116 KM_ERROR_INCOMPATIBLE_PURPOSE = -3, 117 KM_ERROR_UNSUPPORTED_ALGORITHM = -4, 118 KM_ERROR_INCOMPATIBLE_ALGORITHM = -5, 119 KM_ERROR_UNSUPPORTED_KEY_SIZE = -6, 120 KM_ERROR_UNSUPPORTED_BLOCK_MODE = -7, 121 KM_ERROR_INCOMPATIBLE_BLOCK_MODE = -8, 122 KM_ERROR_UNSUPPORTED_MAC_LENGTH = -9, 123 KM_ERROR_UNSUPPORTED_PADDING_MODE = -10, 124 KM_ERROR_INCOMPATIBLE_PADDING_MODE = -11, 125 KM_ERROR_UNSUPPORTED_DIGEST = -12, 126 KM_ERROR_INCOMPATIBLE_DIGEST = -13, 127 KM_ERROR_INVALID_EXPIRATION_TIME = -14, 128 KM_ERROR_INVALID_USER_ID = -15, 129 KM_ERROR_INVALID_AUTHORIZATION_TIMEOUT = -16, 130 KM_ERROR_UNSUPPORTED_KEY_FORMAT = -17, 131 KM_ERROR_INCOMPATIBLE_KEY_FORMAT = -18, 132 /* For PKCS8 & PKCS12 */ 133 KM_ERROR_UNSUPPORTED_KEY_ENCRYPTION_ALGORITHM = -19, 134 /* For PKCS8 & PKCS12 */ 135 KM_ERROR_UNSUPPORTED_KEY_VERIFICATION_ALGORITHM = -20, 136 KM_ERROR_INVALID_INPUT_LENGTH = -21, 137 KM_ERROR_KEY_EXPORT_OPTIONS_INVALID = -22, 138 KM_ERROR_DELEGATION_NOT_ALLOWED = -23, 139 KM_ERROR_KEY_NOT_YET_VALID = -24, 140 KM_ERROR_KEY_EXPIRED = -25, 141 KM_ERROR_KEY_USER_NOT_AUTHENTICATED = -26, 142 KM_ERROR_OUTPUT_PARAMETER_NULL = -27, 143 KM_ERROR_INVALID_OPERATION_HANDLE = -28, 144 KM_ERROR_INSUFFICIENT_BUFFER_SPACE = -29, 145 KM_ERROR_VERIFICATION_FAILED = -30, 146 KM_ERROR_TOO_MANY_OPERATIONS = -31, 147 KM_ERROR_UNEXPECTED_NULL_POINTER = -32, 148 KM_ERROR_INVALID_KEY_BLOB = -33, 149 KM_ERROR_IMPORTED_KEY_NOT_ENCRYPTED = -34, 150 KM_ERROR_IMPORTED_KEY_DECRYPTION_FAILED = -35, 151 KM_ERROR_IMPORTED_KEY_NOT_SIGNED = -36, 152 KM_ERROR_IMPORTED_KEY_VERIFICATION_FAILED = -37, 153 KM_ERROR_INVALID_ARGUMENT = -38, 154 KM_ERROR_UNSUPPORTED_TAG = -39, 155 KM_ERROR_INVALID_TAG = -40, 156 KM_ERROR_MEMORY_ALLOCATION_FAILED = -41, 157 KM_ERROR_IMPORT_PARAMETER_MISMATCH = -44, 158 KM_ERROR_SECURE_HW_ACCESS_DENIED = -45, 159 KM_ERROR_OPERATION_CANCELLED = -46, 160 KM_ERROR_CONCURRENT_ACCESS_CONFLICT = -47, 161 KM_ERROR_SECURE_HW_BUSY = -48, 162 KM_ERROR_SECURE_HW_COMMUNICATION_FAILED = -49, 163 KM_ERROR_UNSUPPORTED_EC_FIELD = -50, 164 KM_ERROR_MISSING_NONCE = -51, 165 KM_ERROR_INVALID_NONCE = -52, 166 KM_ERROR_MISSING_MAC_LENGTH = -53, 167 KM_ERROR_KEY_RATE_LIMIT_EXCEEDED = -54, 168 KM_ERROR_CALLER_NONCE_PROHIBITED = -55, 169 KM_ERROR_KEY_MAX_OPS_EXCEEDED = -56, 170 KM_ERROR_INVALID_MAC_LENGTH = -57, 171 KM_ERROR_MISSING_MIN_MAC_LENGTH = -58, 172 KM_ERROR_UNSUPPORTED_MIN_MAC_LENGTH = -59, 173 KM_ERROR_UNSUPPORTED_KDF = -60, 174 KM_ERROR_UNSUPPORTED_EC_CURVE = -61, 175 KM_ERROR_KEY_REQUIRES_UPGRADE = -62, 176 KM_ERROR_ATTESTATION_CHALLENGE_MISSING = -63, 177 KM_ERROR_KEYMASTER_NOT_CONFIGURED = -64, 178 179 KM_ERROR_UNIMPLEMENTED = -100, 180 KM_ERROR_VERSION_MISMATCH = -101, 181 182 KM_ERROR_UNKNOWN_ERROR = -1000, 183 } keymaster_error_t; 184 185 /** 186 * keymaster_message - Serial header for communicating with KM server 187 * 188 * @cmd: the command, one of keymaster_command. 189 * @payload: start of the serialized command specific payload 190 */ 191 struct keymaster_message { 192 uint32_t cmd; 193 uint8_t payload[0]; 194 }; 195 196 /** 197 * km_no_response - Generic keymaster response for commands with no special 198 * response data 199 * 200 * @error: error code from command 201 */ 202 struct km_no_response { 203 int32_t error; 204 }; 205 206 /** 207 * km_get_version_resp - response format for KM_GET_VERSION. 208 */ 209 struct km_get_version_resp { 210 int32_t error; 211 uint8_t major_ver; 212 uint8_t minor_ver; 213 uint8_t subminor_ver; 214 } TRUSTY_ATTR_PACKED; 215 216 /** 217 * km_raw_buffer_resp - response format for a raw buffer 218 */ 219 struct km_raw_buffer_resp { 220 int32_t error; 221 uint32_t data_size; 222 int8_t data[0]; 223 } TRUSTY_ATTR_PACKED; 224 225 /** 226 * km_set_ca_response_begin_req - starts the process to set the ATAP CA Response 227 * 228 * @ca_response_size: total size of the CA Response message 229 */ 230 struct km_set_ca_response_begin_req { 231 uint32_t ca_response_size; 232 } TRUSTY_ATTR_PACKED; 233 234 /** 235 * km_boot_params - Parameters sent from the bootloader to the Keymaster TA 236 * 237 * Since verified_boot_key_hash and verified_boot_hash have variable sizes, this 238 * structure must be serialized before sending to the secure side 239 * using km_boot_params_serialize(). 240 * 241 * @os_version: OS version from Android image header 242 * @os_patchlevel: OS patch level from Android image header 243 * @device_locked: nonzero if device is locked 244 * @verified_boot_state: one of keymaster_verified_boot_t 245 * @verified_boot_key_hash_size: size of verified_boot_key_hash 246 * @verified_boot_key_hash: hash of key used to verify Android image 247 * @verified_boot_hash_size: size of verified_boot_hash 248 * @verified_boot_hash: cumulative hash of all images verified thus far 249 */ 250 struct km_boot_params { 251 uint32_t os_version; 252 uint32_t os_patchlevel; 253 uint32_t device_locked; 254 uint32_t verified_boot_state; 255 uint32_t verified_boot_key_hash_size; 256 const uint8_t* verified_boot_key_hash; 257 uint32_t verified_boot_hash_size; 258 const uint8_t* verified_boot_hash; 259 } TRUSTY_ATTR_PACKED; 260 261 /** 262 * km_attestation_data - represents a DER encoded key or certificate 263 * 264 * @algorithm: one of KM_ALGORITHM_RSA or KM_ALGORITHM_EC 265 * @data_size: size of |data| 266 * @data: DER encoded key or certificate (depending on operation) 267 */ 268 struct km_attestation_data { 269 uint32_t algorithm; 270 uint32_t data_size; 271 const uint8_t* data; 272 } TRUSTY_ATTR_PACKED; 273 274 /** 275 * km_raw_buffer - represents a single raw buffer 276 * 277 * @data_size: size of |data| 278 * @data: pointer to the buffer 279 */ 280 struct km_raw_buffer { 281 uint32_t data_size; 282 const uint8_t* data; 283 } TRUSTY_ATTR_PACKED; 284 285 #endif /* TRUSTY_INTERFACE_KEYMASTER_H_ */ 286