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 2 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 /** 45 * Flags for keymaster_device::flags 46 */ 47 enum { 48 /* 49 * Indicates this keymaster implementation does not have hardware that 50 * keeps private keys out of user space. 51 * 52 * This should not be implemented on anything other than the default 53 * implementation. 54 */ 55 KEYMASTER_SOFTWARE_ONLY = 0x00000001, 56 }; 57 58 struct keystore_module { 59 hw_module_t common; 60 }; 61 62 /** 63 * Asymmetric key pair types. 64 */ 65 typedef enum { 66 TYPE_RSA = 1, 67 TYPE_DSA = 2, 68 TYPE_EC = 3, 69 } keymaster_keypair_t; 70 71 /** 72 * Parameters needed to generate an RSA key. 73 */ 74 typedef struct { 75 uint32_t modulus_size; 76 uint64_t public_exponent; 77 } keymaster_rsa_keygen_params_t; 78 79 /** 80 * Parameters needed to generate a DSA key. 81 */ 82 typedef struct { 83 uint32_t key_size; 84 uint32_t generator_len; 85 uint32_t prime_p_len; 86 uint32_t prime_q_len; 87 const uint8_t* generator; 88 const uint8_t* prime_p; 89 const uint8_t* prime_q; 90 } keymaster_dsa_keygen_params_t; 91 92 /** 93 * Parameters needed to generate an EC key. 94 * 95 * Field size is the only parameter in version 2. The sizes correspond to these required curves: 96 * 97 * 192 = NIST P-192 98 * 224 = NIST P-224 99 * 256 = NIST P-256 100 * 384 = NIST P-384 101 * 521 = NIST P-521 102 * 103 * The parameters for these curves are available at: http://www.nsa.gov/ia/_files/nist-routines.pdf 104 * in Chapter 4. 105 */ 106 typedef struct { 107 uint32_t field_size; 108 } keymaster_ec_keygen_params_t; 109 110 /** 111 * Digest type. 112 */ 113 typedef enum { 114 DIGEST_NONE, 115 } keymaster_digest_t; 116 117 /** 118 * Type of padding used for RSA operations. 119 */ 120 typedef enum { 121 PADDING_NONE, 122 } keymaster_rsa_padding_t; 123 124 125 typedef struct { 126 keymaster_digest_t digest_type; 127 } keymaster_dsa_sign_params_t; 128 129 typedef struct { 130 keymaster_digest_t digest_type; 131 } keymaster_ec_sign_params_t; 132 133 typedef struct { 134 keymaster_digest_t digest_type; 135 keymaster_rsa_padding_t padding_type; 136 } keymaster_rsa_sign_params_t; 137 138 /** 139 * The parameters that can be set for a given keymaster implementation. 140 */ 141 struct keymaster_device { 142 struct hw_device_t common; 143 144 /** 145 * THIS IS DEPRECATED. Use the new "module_api_version" and "hal_api_version" 146 * fields in the keymaster_module initialization instead. 147 */ 148 uint32_t client_version; 149 150 /** 151 * See flags defined for keymaster_device::flags above. 152 */ 153 uint32_t flags; 154 155 void* context; 156 157 /** 158 * Generates a public and private key. The key-blob returned is opaque 159 * and must subsequently provided for signing and verification. 160 * 161 * Returns: 0 on success or an error code less than 0. 162 */ 163 int (*generate_keypair)(const struct keymaster_device* dev, 164 const keymaster_keypair_t key_type, const void* key_params, 165 uint8_t** key_blob, size_t* key_blob_length); 166 167 /** 168 * Imports a public and private key pair. The imported keys will be in 169 * PKCS#8 format with DER encoding (Java standard). The key-blob 170 * returned is opaque and will be subsequently provided for signing 171 * and verification. 172 * 173 * Returns: 0 on success or an error code less than 0. 174 */ 175 int (*import_keypair)(const struct keymaster_device* dev, 176 const uint8_t* key, const size_t key_length, 177 uint8_t** key_blob, size_t* key_blob_length); 178 179 /** 180 * Gets the public key part of a key pair. The public key must be in 181 * X.509 format (Java standard) encoded byte array. 182 * 183 * Returns: 0 on success or an error code less than 0. 184 * On error, x509_data should not be allocated. 185 */ 186 int (*get_keypair_public)(const struct keymaster_device* dev, 187 const uint8_t* key_blob, const size_t key_blob_length, 188 uint8_t** x509_data, size_t* x509_data_length); 189 190 /** 191 * Deletes the key pair associated with the key blob. 192 * 193 * This function is optional and should be set to NULL if it is not 194 * implemented. 195 * 196 * Returns 0 on success or an error code less than 0. 197 */ 198 int (*delete_keypair)(const struct keymaster_device* dev, 199 const uint8_t* key_blob, const size_t key_blob_length); 200 201 /** 202 * Deletes all keys in the hardware keystore. Used when keystore is 203 * reset completely. 204 * 205 * This function is optional and should be set to NULL if it is not 206 * implemented. 207 * 208 * Returns 0 on success or an error code less than 0. 209 */ 210 int (*delete_all)(const struct keymaster_device* dev); 211 212 /** 213 * Signs data using a key-blob generated before. This can use either 214 * an asymmetric key or a secret key. 215 * 216 * Returns: 0 on success or an error code less than 0. 217 */ 218 int (*sign_data)(const struct keymaster_device* dev, 219 const void* signing_params, 220 const uint8_t* key_blob, const size_t key_blob_length, 221 const uint8_t* data, const size_t data_length, 222 uint8_t** signed_data, size_t* signed_data_length); 223 224 /** 225 * Verifies data signed with a key-blob. This can use either 226 * an asymmetric key or a secret key. 227 * 228 * Returns: 0 on successful verification or an error code less than 0. 229 */ 230 int (*verify_data)(const struct keymaster_device* dev, 231 const void* signing_params, 232 const uint8_t* key_blob, const size_t key_blob_length, 233 const uint8_t* signed_data, const size_t signed_data_length, 234 const uint8_t* signature, const size_t signature_length); 235 }; 236 typedef struct keymaster_device keymaster_device_t; 237 238 239 /* Convenience API for opening and closing keymaster devices */ 240 241 static inline int keymaster_open(const struct hw_module_t* module, 242 keymaster_device_t** device) 243 { 244 int rc = module->methods->open(module, KEYSTORE_KEYMASTER, 245 (struct hw_device_t**) device); 246 247 return rc; 248 } 249 250 static inline int keymaster_close(keymaster_device_t* device) 251 { 252 return device->common.close(&device->common); 253 } 254 255 __END_DECLS 256 257 #endif // ANDROID_HARDWARE_KEYMASTER_H 258 259
