1 /* 2 * Copyright (C) 2011 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_H 18 #define ANDROID_HARDWARE_KEYMASTER_H 19 20 #include <stdint.h> 21 #include <sys/cdefs.h> 22 #include <sys/types.h> 23 24 #include <hardware/hardware.h> 25 26 __BEGIN_DECLS 27 28 /** 29 * The id of this module 30 */ 31 #define KEYSTORE_HARDWARE_MODULE_ID "keystore" 32 33 #define KEYSTORE_KEYMASTER "keymaster" 34 35 /** 36 * Settings for "module_api_version" and "hal_api_version" 37 * fields in the keymaster_module initialization. 38 */ 39 #define KEYMASTER_HEADER_VERSION 3 40 41 #define KEYMASTER_MODULE_API_VERSION_0_2 HARDWARE_MODULE_API_VERSION(0, 2) 42 #define KEYMASTER_DEVICE_API_VERSION_0_2 HARDWARE_DEVICE_API_VERSION_2(0, 2, KEYMASTER_HEADER_VERSION) 43 44 #define KEYMASTER_MODULE_API_VERSION_0_3 HARDWARE_MODULE_API_VERSION(0, 3) 45 #define KEYMASTER_DEVICE_API_VERSION_0_3 HARDWARE_DEVICE_API_VERSION_2(0, 3, KEYMASTER_HEADER_VERSION) 46 47 /** 48 * Flags for keymaster_device::flags 49 */ 50 enum { 51 /* 52 * Indicates this keymaster implementation does not have hardware that 53 * keeps private keys out of user space. 54 * 55 * This should not be implemented on anything other than the default 56 * implementation. 57 */ 58 KEYMASTER_SOFTWARE_ONLY = 1 << 0, 59 60 /* 61 * This indicates that the key blobs returned via all the primitives 62 * are sufficient to operate on their own without the trusted OS 63 * querying userspace to retrieve some other data. Key blobs of 64 * this type are normally returned encrypted with a 65 * Key Encryption Key (KEK). 66 * 67 * This is currently used by "vold" to know whether the whole disk 68 * encryption secret can be unwrapped without having some external 69 * service started up beforehand since the "/data" partition will 70 * be unavailable at that point. 71 */ 72 KEYMASTER_BLOBS_ARE_STANDALONE = 1 << 1, 73 74 /* 75 * Indicates that the keymaster module supports DSA keys. 76 */ 77 KEYMASTER_SUPPORTS_DSA = 1 << 2, 78 79 /* 80 * Indicates that the keymaster module supports EC keys. 81 */ 82 KEYMASTER_SUPPORTS_EC = 1 << 3, 83 }; 84 85 struct keystore_module { 86 /** 87 * Common methods of the keystore module. This *must* be the first member of 88 * keystore_module as users of this structure will cast a hw_module_t to 89 * keystore_module pointer in contexts where it's known the hw_module_t references a 90 * keystore_module. 91 */ 92 hw_module_t common; 93 }; 94 95 /** 96 * Asymmetric key pair types. 97 */ 98 typedef enum { 99 TYPE_RSA = 1, 100 TYPE_DSA = 2, 101 TYPE_EC = 3, 102 } keymaster_keypair_t; 103 104 /** 105 * Parameters needed to generate an RSA key. 106 */ 107 typedef struct { 108 uint32_t modulus_size; 109 uint64_t public_exponent; 110 } keymaster_rsa_keygen_params_t; 111 112 /** 113 * Parameters needed to generate a DSA key. 114 */ 115 typedef struct { 116 uint32_t key_size; 117 uint32_t generator_len; 118 uint32_t prime_p_len; 119 uint32_t prime_q_len; 120 const uint8_t* generator; 121 const uint8_t* prime_p; 122 const uint8_t* prime_q; 123 } keymaster_dsa_keygen_params_t; 124 125 /** 126 * Parameters needed to generate an EC key. 127 * 128 * Field size is the only parameter in version 2. The sizes correspond to these required curves: 129 * 130 * 192 = NIST P-192 131 * 224 = NIST P-224 132 * 256 = NIST P-256 133 * 384 = NIST P-384 134 * 521 = NIST P-521 135 * 136 * The parameters for these curves are available at: http://www.nsa.gov/ia/_files/nist-routines.pdf 137 * in Chapter 4. 138 */ 139 typedef struct { 140 uint32_t field_size; 141 } keymaster_ec_keygen_params_t; 142 143 /** 144 * Digest type. 145 */ 146 typedef enum { 147 DIGEST_NONE, 148 } keymaster_digest_t; 149 150 /** 151 * Type of padding used for RSA operations. 152 */ 153 typedef enum { 154 PADDING_NONE, 155 } keymaster_rsa_padding_t; 156 157 158 typedef struct { 159 keymaster_digest_t digest_type; 160 } keymaster_dsa_sign_params_t; 161 162 typedef struct { 163 keymaster_digest_t digest_type; 164 } keymaster_ec_sign_params_t; 165 166 typedef struct { 167 keymaster_digest_t digest_type; 168 keymaster_rsa_padding_t padding_type; 169 } keymaster_rsa_sign_params_t; 170 171 /** 172 * The parameters that can be set for a given keymaster implementation. 173 */ 174 struct keymaster_device { 175 /** 176 * Common methods of the keymaster device. This *must* be the first member of 177 * keymaster_device as users of this structure will cast a hw_device_t to 178 * keymaster_device pointer in contexts where it's known the hw_device_t references a 179 * keymaster_device. 180 */ 181 struct hw_device_t common; 182 183 /** 184 * THIS IS DEPRECATED. Use the new "module_api_version" and "hal_api_version" 185 * fields in the keymaster_module initialization instead. 186 */ 187 uint32_t client_version; 188 189 /** 190 * See flags defined for keymaster_device::flags above. 191 */ 192 uint32_t flags; 193 194 void* context; 195 196 /** 197 * Generates a public and private key. The key-blob returned is opaque 198 * and must subsequently provided for signing and verification. 199 * 200 * Returns: 0 on success or an error code less than 0. 201 */ 202 int (*generate_keypair)(const struct keymaster_device* dev, 203 const keymaster_keypair_t key_type, const void* key_params, 204 uint8_t** key_blob, size_t* key_blob_length); 205 206 /** 207 * Imports a public and private key pair. The imported keys will be in 208 * PKCS#8 format with DER encoding (Java standard). The key-blob 209 * returned is opaque and will be subsequently provided for signing 210 * and verification. 211 * 212 * Returns: 0 on success or an error code less than 0. 213 */ 214 int (*import_keypair)(const struct keymaster_device* dev, 215 const uint8_t* key, const size_t key_length, 216 uint8_t** key_blob, size_t* key_blob_length); 217 218 /** 219 * Gets the public key part of a key pair. The public key must be in 220 * X.509 format (Java standard) encoded byte array. 221 * 222 * Returns: 0 on success or an error code less than 0. 223 * On error, x509_data should not be allocated. 224 */ 225 int (*get_keypair_public)(const struct keymaster_device* dev, 226 const uint8_t* key_blob, const size_t key_blob_length, 227 uint8_t** x509_data, size_t* x509_data_length); 228 229 /** 230 * Deletes the key pair associated with the key blob. 231 * 232 * This function is optional and should be set to NULL if it is not 233 * implemented. 234 * 235 * Returns 0 on success or an error code less than 0. 236 */ 237 int (*delete_keypair)(const struct keymaster_device* dev, 238 const uint8_t* key_blob, const size_t key_blob_length); 239 240 /** 241 * Deletes all keys in the hardware keystore. Used when keystore is 242 * reset completely. 243 * 244 * This function is optional and should be set to NULL if it is not 245 * implemented. 246 * 247 * Returns 0 on success or an error code less than 0. 248 */ 249 int (*delete_all)(const struct keymaster_device* dev); 250 251 /** 252 * Signs data using a key-blob generated before. This can use either 253 * an asymmetric key or a secret key. 254 * 255 * Returns: 0 on success or an error code less than 0. 256 */ 257 int (*sign_data)(const struct keymaster_device* dev, 258 const void* signing_params, 259 const uint8_t* key_blob, const size_t key_blob_length, 260 const uint8_t* data, const size_t data_length, 261 uint8_t** signed_data, size_t* signed_data_length); 262 263 /** 264 * Verifies data signed with a key-blob. This can use either 265 * an asymmetric key or a secret key. 266 * 267 * Returns: 0 on successful verification or an error code less than 0. 268 */ 269 int (*verify_data)(const struct keymaster_device* dev, 270 const void* signing_params, 271 const uint8_t* key_blob, const size_t key_blob_length, 272 const uint8_t* signed_data, const size_t signed_data_length, 273 const uint8_t* signature, const size_t signature_length); 274 }; 275 typedef struct keymaster_device keymaster_device_t; 276 277 278 /* Convenience API for opening and closing keymaster devices */ 279 280 static inline int keymaster_open(const struct hw_module_t* module, 281 keymaster_device_t** device) 282 { 283 int rc = module->methods->open(module, KEYSTORE_KEYMASTER, 284 (struct hw_device_t**) device); 285 286 return rc; 287 } 288 289 static inline int keymaster_close(keymaster_device_t* device) 290 { 291 return device->common.close(&device->common); 292 } 293 294 __END_DECLS 295 296 #endif // ANDROID_HARDWARE_KEYMASTER_H 297
