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 * The API level of this version of the header. The allows the implementing 37 * module to recognize which API level of the client it is dealing with in 38 * the case of pre-compiled binary clients. 39 */ 40 #define KEYMASTER_API_VERSION 1 41 42 /** 43 * Flags for keymaster_device::flags 44 */ 45 enum { 46 /* 47 * Indicates this keymaster implementation does not have hardware that 48 * keeps private keys out of user space. 49 * 50 * This should not be implemented on anything other than the default 51 * implementation. 52 */ 53 KEYMASTER_SOFTWARE_ONLY = 0x00000001, 54 }; 55 56 struct keystore_module { 57 hw_module_t common; 58 }; 59 60 /** 61 * Asymmetric key pair types. 62 */ 63 typedef enum { 64 TYPE_RSA = 1, 65 } keymaster_keypair_t; 66 67 /** 68 * Parameters needed to generate an RSA key. 69 */ 70 typedef struct { 71 uint32_t modulus_size; 72 uint64_t public_exponent; 73 } keymaster_rsa_keygen_params_t; 74 75 /** 76 * Digest type used for RSA operations. 77 */ 78 typedef enum { 79 DIGEST_NONE, 80 } keymaster_rsa_digest_t; 81 82 /** 83 * Type of padding used for RSA operations. 84 */ 85 typedef enum { 86 PADDING_NONE, 87 } keymaster_rsa_padding_t; 88 89 typedef struct { 90 keymaster_rsa_digest_t digest_type; 91 keymaster_rsa_padding_t padding_type; 92 } keymaster_rsa_sign_params_t; 93 94 /** 95 * The parameters that can be set for a given keymaster implementation. 96 */ 97 struct keymaster_device { 98 struct hw_device_t common; 99 100 uint32_t client_version; 101 102 /** 103 * See flags defined for keymaster_device::flags above. 104 */ 105 uint32_t flags; 106 107 void* context; 108 109 /** 110 * Generates a public and private key. The key-blob returned is opaque 111 * and must subsequently provided for signing and verification. 112 * 113 * Returns: 0 on success or an error code less than 0. 114 */ 115 int (*generate_keypair)(const struct keymaster_device* dev, 116 const keymaster_keypair_t key_type, const void* key_params, 117 uint8_t** key_blob, size_t* key_blob_length); 118 119 /** 120 * Imports a public and private key pair. The imported keys will be in 121 * PKCS#8 format with DER encoding (Java standard). The key-blob 122 * returned is opaque and will be subsequently provided for signing 123 * and verification. 124 * 125 * Returns: 0 on success or an error code less than 0. 126 */ 127 int (*import_keypair)(const struct keymaster_device* dev, 128 const uint8_t* key, const size_t key_length, 129 uint8_t** key_blob, size_t* key_blob_length); 130 131 /** 132 * Gets the public key part of a key pair. The public key must be in 133 * X.509 format (Java standard) encoded byte array. 134 * 135 * Returns: 0 on success or an error code less than 0. 136 * On error, x509_data should not be allocated. 137 */ 138 int (*get_keypair_public)(const struct keymaster_device* dev, 139 const uint8_t* key_blob, const size_t key_blob_length, 140 uint8_t** x509_data, size_t* x509_data_length); 141 142 /** 143 * Deletes the key pair associated with the key blob. 144 * 145 * This function is optional and should be set to NULL if it is not 146 * implemented. 147 * 148 * Returns 0 on success or an error code less than 0. 149 */ 150 int (*delete_keypair)(const struct keymaster_device* dev, 151 const uint8_t* key_blob, const size_t key_blob_length); 152 153 /** 154 * Deletes all keys in the hardware keystore. Used when keystore is 155 * reset completely. 156 * 157 * This function is optional and should be set to NULL if it is not 158 * implemented. 159 * 160 * Returns 0 on success or an error code less than 0. 161 */ 162 int (*delete_all)(const struct keymaster_device* dev); 163 164 /** 165 * Signs data using a key-blob generated before. This can use either 166 * an asymmetric key or a secret key. 167 * 168 * Returns: 0 on success or an error code less than 0. 169 */ 170 int (*sign_data)(const struct keymaster_device* dev, 171 const void* signing_params, 172 const uint8_t* key_blob, const size_t key_blob_length, 173 const uint8_t* data, const size_t data_length, 174 uint8_t** signed_data, size_t* signed_data_length); 175 176 /** 177 * Verifies data signed with a key-blob. This can use either 178 * an asymmetric key or a secret key. 179 * 180 * Returns: 0 on successful verification or an error code less than 0. 181 */ 182 int (*verify_data)(const struct keymaster_device* dev, 183 const void* signing_params, 184 const uint8_t* key_blob, const size_t key_blob_length, 185 const uint8_t* signed_data, const size_t signed_data_length, 186 const uint8_t* signature, const size_t signature_length); 187 }; 188 typedef struct keymaster_device keymaster_device_t; 189 190 191 /* Convenience API for opening and closing keymaster devices */ 192 193 static inline int keymaster_open(const struct hw_module_t* module, 194 keymaster_device_t** device) 195 { 196 int rc = module->methods->open(module, KEYSTORE_KEYMASTER, 197 (struct hw_device_t**) device); 198 199 if (!rc) { 200 (*device)->client_version = KEYMASTER_API_VERSION; 201 } 202 203 return rc; 204 } 205 206 static inline int keymaster_close(keymaster_device_t* device) 207 { 208 return device->common.close(&device->common); 209 } 210 211 __END_DECLS 212 213 #endif // ANDROID_HARDWARE_KEYMASTER_H 214 215