1 /* openssl/engine.h */ 2 /* Written by Geoff Thorpe (geoff@geoffthorpe.net) for the OpenSSL 3 * project 2000. 4 */ 5 /* ==================================================================== 6 * Copyright (c) 1999 The OpenSSL Project. All rights reserved. 7 * 8 * Redistribution and use in source and binary forms, with or without 9 * modification, are permitted provided that the following conditions 10 * are met: 11 * 12 * 1. Redistributions of source code must retain the above copyright 13 * notice, this list of conditions and the following disclaimer. 14 * 15 * 2. Redistributions in binary form must reproduce the above copyright 16 * notice, this list of conditions and the following disclaimer in 17 * the documentation and/or other materials provided with the 18 * distribution. 19 * 20 * 3. All advertising materials mentioning features or use of this 21 * software must display the following acknowledgment: 22 * "This product includes software developed by the OpenSSL Project 23 * for use in the OpenSSL Toolkit. (http://www.OpenSSL.org/)" 24 * 25 * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26 * endorse or promote products derived from this software without 27 * prior written permission. For written permission, please contact 28 * licensing@OpenSSL.org. 29 * 30 * 5. Products derived from this software may not be called "OpenSSL" 31 * nor may "OpenSSL" appear in their names without prior written 32 * permission of the OpenSSL Project. 33 * 34 * 6. Redistributions of any form whatsoever must retain the following 35 * acknowledgment: 36 * "This product includes software developed by the OpenSSL Project 37 * for use in the OpenSSL Toolkit (http://www.OpenSSL.org/)" 38 * 39 * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40 * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50 * OF THE POSSIBILITY OF SUCH DAMAGE. 51 * ==================================================================== 52 * 53 * This product includes cryptographic software written by Eric Young 54 * (eay@cryptsoft.com). This product includes software written by Tim 55 * Hudson (tjh@cryptsoft.com). 56 * 57 */ 58 59 #ifndef HEADER_ENGINE_H 60 #define HEADER_ENGINE_H 61 62 #include <openssl/bn.h> 63 #include <openssl/rsa.h> 64 #include <openssl/dsa.h> 65 #include <openssl/dh.h> 66 #include <openssl/rand.h> 67 #include <openssl/evp.h> 68 #include <openssl/symhacks.h> 69 70 #ifdef __cplusplus 71 extern "C" { 72 #endif 73 74 /* These flags are used to control combinations of algorithm (methods) 75 * by bitwise "OR"ing. */ 76 #define ENGINE_METHOD_RSA (unsigned int)0x0001 77 #define ENGINE_METHOD_DSA (unsigned int)0x0002 78 #define ENGINE_METHOD_DH (unsigned int)0x0004 79 #define ENGINE_METHOD_RAND (unsigned int)0x0008 80 #define ENGINE_METHOD_BN_MOD_EXP (unsigned int)0x0010 81 #define ENGINE_METHOD_BN_MOD_EXP_CRT (unsigned int)0x0020 82 /* Obvious all-or-nothing cases. */ 83 #define ENGINE_METHOD_ALL (unsigned int)0xFFFF 84 #define ENGINE_METHOD_NONE (unsigned int)0x0000 85 86 /* These flags are used to tell the ctrl function what should be done. 87 * All command numbers are shared between all engines, even if some don't 88 * make sense to some engines. In such a case, they do nothing but return 89 * the error ENGINE_R_CTRL_COMMAND_NOT_IMPLEMENTED. */ 90 #define ENGINE_CTRL_SET_LOGSTREAM 1 91 #define ENGINE_CTRL_SET_PASSWORD_CALLBACK 2 92 /* Flags specific to the nCipher "chil" engine */ 93 #define ENGINE_CTRL_CHIL_SET_FORKCHECK 100 94 /* Depending on the value of the (long)i argument, this sets or 95 * unsets the SimpleForkCheck flag in the CHIL API to enable or 96 * disable checking and workarounds for applications that fork(). 97 */ 98 #define ENGINE_CTRL_CHIL_NO_LOCKING 101 99 /* This prevents the initialisation function from providing mutex 100 * callbacks to the nCipher library. */ 101 102 /* As we're missing a BIGNUM_METHOD, we need a couple of locally 103 * defined function types that engines can implement. */ 104 105 #ifndef HEADER_ENGINE_INT_H 106 /* mod_exp operation, calculates; r = a ^ p mod m 107 * NB: ctx can be NULL, but if supplied, the implementation may use 108 * it if it wishes. */ 109 typedef int (*BN_MOD_EXP)(BIGNUM *r, BIGNUM *a, const BIGNUM *p, 110 const BIGNUM *m, BN_CTX *ctx); 111 112 /* private key operation for RSA, provided seperately in case other 113 * RSA implementations wish to use it. */ 114 typedef int (*BN_MOD_EXP_CRT)(BIGNUM *r, BIGNUM *a, const BIGNUM *p, 115 const BIGNUM *q, const BIGNUM *dmp1, const BIGNUM *dmq1, 116 const BIGNUM *iqmp, BN_CTX *ctx); 117 118 /* Generic function pointer */ 119 typedef void (*ENGINE_GEN_FUNC_PTR)(); 120 /* Generic function pointer taking no arguments */ 121 typedef void (*ENGINE_GEN_INT_FUNC_PTR)(void); 122 /* Specific control function pointer */ 123 typedef int (*ENGINE_CTRL_FUNC_PTR)(int cmd, long i, void *p, void (*f)()); 124 125 /* The list of "engine" types is a static array of (const ENGINE*) 126 * pointers (not dynamic because static is fine for now and we otherwise 127 * have to hook an appropriate load/unload function in to initialise and 128 * cleanup). */ 129 typedef struct engine_st ENGINE; 130 #endif 131 132 /* STRUCTURE functions ... all of these functions deal with pointers to 133 * ENGINE structures where the pointers have a "structural reference". 134 * This means that their reference is to allow access to the structure 135 * but it does not imply that the structure is functional. To simply 136 * increment or decrement the structural reference count, use ENGINE_new 137 * and ENGINE_free. NB: This is not required when iterating using 138 * ENGINE_get_next as it will automatically decrement the structural 139 * reference count of the "current" ENGINE and increment the structural 140 * reference count of the ENGINE it returns (unless it is NULL). */ 141 142 /* Get the first/last "ENGINE" type available. */ 143 ENGINE *ENGINE_get_first(void); 144 ENGINE *ENGINE_get_last(void); 145 /* Iterate to the next/previous "ENGINE" type (NULL = end of the list). */ 146 ENGINE *ENGINE_get_next(ENGINE *e); 147 ENGINE *ENGINE_get_prev(ENGINE *e); 148 /* Add another "ENGINE" type into the array. */ 149 int ENGINE_add(ENGINE *e); 150 /* Remove an existing "ENGINE" type from the array. */ 151 int ENGINE_remove(ENGINE *e); 152 /* Retrieve an engine from the list by its unique "id" value. */ 153 ENGINE *ENGINE_by_id(const char *id); 154 155 /* These functions are useful for manufacturing new ENGINE 156 * structures. They don't address reference counting at all - 157 * one uses them to populate an ENGINE structure with personalised 158 * implementations of things prior to using it directly or adding 159 * it to the builtin ENGINE list in OpenSSL. These are also here 160 * so that the ENGINE structure doesn't have to be exposed and 161 * break binary compatibility! 162 * 163 * NB: I'm changing ENGINE_new to force the ENGINE structure to 164 * be allocated from within OpenSSL. See the comment for 165 * ENGINE_get_struct_size(). 166 */ 167 #if 0 168 ENGINE *ENGINE_new(ENGINE *e); 169 #else 170 ENGINE *ENGINE_new(void); 171 #endif 172 int ENGINE_free(ENGINE *e); 173 int ENGINE_set_id(ENGINE *e, const char *id); 174 int ENGINE_set_name(ENGINE *e, const char *name); 175 int ENGINE_set_RSA(ENGINE *e, RSA_METHOD *rsa_meth); 176 int ENGINE_set_DSA(ENGINE *e, DSA_METHOD *dsa_meth); 177 int ENGINE_set_DH(ENGINE *e, DH_METHOD *dh_meth); 178 int ENGINE_set_RAND(ENGINE *e, RAND_METHOD *rand_meth); 179 int ENGINE_set_BN_mod_exp(ENGINE *e, BN_MOD_EXP bn_mod_exp); 180 int ENGINE_set_BN_mod_exp_crt(ENGINE *e, BN_MOD_EXP_CRT bn_mod_exp_crt); 181 int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f); 182 int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f); 183 int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f); 184 185 /* These return values from within the ENGINE structure. These can 186 * be useful with functional references as well as structural 187 * references - it depends which you obtained. Using the result 188 * for functional purposes if you only obtained a structural 189 * reference may be problematic! */ 190 const char *ENGINE_get_id(ENGINE *e); 191 const char *ENGINE_get_name(ENGINE *e); 192 RSA_METHOD *ENGINE_get_RSA(ENGINE *e); 193 DSA_METHOD *ENGINE_get_DSA(ENGINE *e); 194 DH_METHOD *ENGINE_get_DH(ENGINE *e); 195 RAND_METHOD *ENGINE_get_RAND(ENGINE *e); 196 BN_MOD_EXP ENGINE_get_BN_mod_exp(ENGINE *e); 197 BN_MOD_EXP_CRT ENGINE_get_BN_mod_exp_crt(ENGINE *e); 198 ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(ENGINE *e); 199 ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(ENGINE *e); 200 ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(ENGINE *e); 201 202 /* ENGINE_new is normally passed a NULL in the first parameter because 203 * the calling code doesn't have access to the definition of the ENGINE 204 * structure (for good reason). However, if the caller wishes to use 205 * its own memory allocation or use a static array, the following call 206 * should be used to check the amount of memory the ENGINE structure 207 * will occupy. This will make the code more future-proof. 208 * 209 * NB: I'm "#if 0"-ing this out because it's better to force the use of 210 * internally allocated memory. See similar change in ENGINE_new(). 211 */ 212 #if 0 213 int ENGINE_get_struct_size(void); 214 #endif 215 216 /* FUNCTIONAL functions. These functions deal with ENGINE structures 217 * that have (or will) be initialised for use. Broadly speaking, the 218 * structural functions are useful for iterating the list of available 219 * engine types, creating new engine types, and other "list" operations. 220 * These functions actually deal with ENGINEs that are to be used. As 221 * such these functions can fail (if applicable) when particular 222 * engines are unavailable - eg. if a hardware accelerator is not 223 * attached or not functioning correctly. Each ENGINE has 2 reference 224 * counts; structural and functional. Every time a functional reference 225 * is obtained or released, a corresponding structural reference is 226 * automatically obtained or released too. */ 227 228 /* Initialise a engine type for use (or up its reference count if it's 229 * already in use). This will fail if the engine is not currently 230 * operational and cannot initialise. */ 231 int ENGINE_init(ENGINE *e); 232 /* Free a functional reference to a engine type. This does not require 233 * a corresponding call to ENGINE_free as it also releases a structural 234 * reference. */ 235 int ENGINE_finish(ENGINE *e); 236 /* Send control parametrised commands to the engine. The possibilities 237 * to send down an integer, a pointer to data or a function pointer are 238 * provided. Any of the parameters may or may not be NULL, depending 239 * on the command number */ 240 /* WARNING: This is currently experimental and may change radically! */ 241 int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)()); 242 243 /* The following functions handle keys that are stored in some secondary 244 * location, handled by the engine. The storage may be on a card or 245 * whatever. */ 246 EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id, 247 const char *passphrase); 248 EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id, 249 const char *passphrase); 250 251 /* This returns a pointer for the current ENGINE structure that 252 * is (by default) performing any RSA operations. The value returned 253 * is an incremented reference, so it should be free'd (ENGINE_finish) 254 * before it is discarded. */ 255 ENGINE *ENGINE_get_default_RSA(void); 256 /* Same for the other "methods" */ 257 ENGINE *ENGINE_get_default_DSA(void); 258 ENGINE *ENGINE_get_default_DH(void); 259 ENGINE *ENGINE_get_default_RAND(void); 260 ENGINE *ENGINE_get_default_BN_mod_exp(void); 261 ENGINE *ENGINE_get_default_BN_mod_exp_crt(void); 262 263 /* This sets a new default ENGINE structure for performing RSA 264 * operations. If the result is non-zero (success) then the ENGINE 265 * structure will have had its reference count up'd so the caller 266 * should still free their own reference 'e'. */ 267 int ENGINE_set_default_RSA(ENGINE *e); 268 /* Same for the other "methods" */ 269 int ENGINE_set_default_DSA(ENGINE *e); 270 int ENGINE_set_default_DH(ENGINE *e); 271 int ENGINE_set_default_RAND(ENGINE *e); 272 int ENGINE_set_default_BN_mod_exp(ENGINE *e); 273 int ENGINE_set_default_BN_mod_exp_crt(ENGINE *e); 274 275 /* The combination "set" - the flags are bitwise "OR"d from the 276 * ENGINE_METHOD_*** defines above. */ 277 int ENGINE_set_default(ENGINE *e, unsigned int flags); 278 279 /* Obligatory error function. */ 280 void ERR_load_ENGINE_strings(void); 281 282 /* 283 * Error codes for all engine functions. NB: We use "generic" 284 * function names instead of per-implementation ones because this 285 * levels the playing field for externally implemented bootstrapped 286 * support code. As the filename and line number is included, it's 287 * more important to indicate the type of function, so that 288 * bootstrapped code (that can't easily add its own errors in) can 289 * use the same error codes too. 290 */ 291 292 /* BEGIN ERROR CODES */ 293 /* The following lines are auto generated by the script mkerr.pl. Any changes 294 * made after this point may be overwritten when the script is next run. 295 */ 296 297 /* Error codes for the ENGINE functions. */ 298 299 /* Function codes. */ 300 #define ENGINE_F_ATALLA_FINISH 135 301 #define ENGINE_F_ATALLA_INIT 136 302 #define ENGINE_F_ATALLA_MOD_EXP 137 303 #define ENGINE_F_ATALLA_RSA_MOD_EXP 138 304 #define ENGINE_F_CSWIFT_DSA_SIGN 133 305 #define ENGINE_F_CSWIFT_DSA_VERIFY 134 306 #define ENGINE_F_CSWIFT_FINISH 100 307 #define ENGINE_F_CSWIFT_INIT 101 308 #define ENGINE_F_CSWIFT_MOD_EXP 102 309 #define ENGINE_F_CSWIFT_MOD_EXP_CRT 103 310 #define ENGINE_F_CSWIFT_RSA_MOD_EXP 104 311 #define ENGINE_F_ENGINE_ADD 105 312 #define ENGINE_F_ENGINE_BY_ID 106 313 #define ENGINE_F_ENGINE_CTRL 142 314 #define ENGINE_F_ENGINE_FINISH 107 315 #define ENGINE_F_ENGINE_FREE 108 316 #define ENGINE_F_ENGINE_GET_BN_MOD_EXP 109 317 #define ENGINE_F_ENGINE_GET_BN_MOD_EXP_CRT 110 318 #define ENGINE_F_ENGINE_GET_CTRL_FUNCTION 144 319 #define ENGINE_F_ENGINE_GET_DH 111 320 #define ENGINE_F_ENGINE_GET_DSA 112 321 #define ENGINE_F_ENGINE_GET_FINISH_FUNCTION 145 322 #define ENGINE_F_ENGINE_GET_ID 113 323 #define ENGINE_F_ENGINE_GET_INIT_FUNCTION 146 324 #define ENGINE_F_ENGINE_GET_NAME 114 325 #define ENGINE_F_ENGINE_GET_NEXT 115 326 #define ENGINE_F_ENGINE_GET_PREV 116 327 #define ENGINE_F_ENGINE_GET_RAND 117 328 #define ENGINE_F_ENGINE_GET_RSA 118 329 #define ENGINE_F_ENGINE_INIT 119 330 #define ENGINE_F_ENGINE_LIST_ADD 120 331 #define ENGINE_F_ENGINE_LIST_REMOVE 121 332 #define ENGINE_F_ENGINE_LOAD_PRIVATE_KEY 150 333 #define ENGINE_F_ENGINE_LOAD_PUBLIC_KEY 151 334 #define ENGINE_F_ENGINE_NEW 122 335 #define ENGINE_F_ENGINE_REMOVE 123 336 #define ENGINE_F_ENGINE_SET_BN_MOD_EXP 124 337 #define ENGINE_F_ENGINE_SET_BN_MOD_EXP_CRT 125 338 #define ENGINE_F_ENGINE_SET_CTRL_FUNCTION 147 339 #define ENGINE_F_ENGINE_SET_DEFAULT_TYPE 126 340 #define ENGINE_F_ENGINE_SET_DH 127 341 #define ENGINE_F_ENGINE_SET_DSA 128 342 #define ENGINE_F_ENGINE_SET_FINISH_FUNCTION 148 343 #define ENGINE_F_ENGINE_SET_ID 129 344 #define ENGINE_F_ENGINE_SET_INIT_FUNCTION 149 345 #define ENGINE_F_ENGINE_SET_NAME 130 346 #define ENGINE_F_ENGINE_SET_RAND 131 347 #define ENGINE_F_ENGINE_SET_RSA 132 348 #define ENGINE_F_ENGINE_UNLOAD_KEY 152 349 #define ENGINE_F_HWCRHK_CTRL 143 350 #define ENGINE_F_HWCRHK_FINISH 135 351 #define ENGINE_F_HWCRHK_GET_PASS 155 352 #define ENGINE_F_HWCRHK_INIT 136 353 #define ENGINE_F_HWCRHK_LOAD_PRIVKEY 153 354 #define ENGINE_F_HWCRHK_LOAD_PUBKEY 154 355 #define ENGINE_F_HWCRHK_MOD_EXP 137 356 #define ENGINE_F_HWCRHK_MOD_EXP_CRT 138 357 #define ENGINE_F_HWCRHK_RAND_BYTES 139 358 #define ENGINE_F_HWCRHK_RSA_MOD_EXP 140 359 #define ENGINE_F_LOG_MESSAGE 141 360 361 /* Reason codes. */ 362 #define ENGINE_R_ALREADY_LOADED 100 363 #define ENGINE_R_BIO_WAS_FREED 121 364 #define ENGINE_R_BN_CTX_FULL 101 365 #define ENGINE_R_BN_EXPAND_FAIL 102 366 #define ENGINE_R_CHIL_ERROR 123 367 #define ENGINE_R_CONFLICTING_ENGINE_ID 103 368 #define ENGINE_R_CTRL_COMMAND_NOT_IMPLEMENTED 119 369 #define ENGINE_R_DSO_FAILURE 104 370 #define ENGINE_R_ENGINE_IS_NOT_IN_LIST 105 371 #define ENGINE_R_FAILED_LOADING_PRIVATE_KEY 128 372 #define ENGINE_R_FAILED_LOADING_PUBLIC_KEY 129 373 #define ENGINE_R_FINISH_FAILED 106 374 #define ENGINE_R_GET_HANDLE_FAILED 107 375 #define ENGINE_R_ID_OR_NAME_MISSING 108 376 #define ENGINE_R_INIT_FAILED 109 377 #define ENGINE_R_INTERNAL_LIST_ERROR 110 378 #define ENGINE_R_MISSING_KEY_COMPONENTS 111 379 #define ENGINE_R_NOT_INITIALISED 117 380 #define ENGINE_R_NOT_LOADED 112 381 #define ENGINE_R_NO_CALLBACK 127 382 #define ENGINE_R_NO_CONTROL_FUNCTION 120 383 #define ENGINE_R_NO_KEY 124 384 #define ENGINE_R_NO_LOAD_FUNCTION 125 385 #define ENGINE_R_NO_REFERENCE 130 386 #define ENGINE_R_NO_SUCH_ENGINE 116 387 #define ENGINE_R_NO_UNLOAD_FUNCTION 126 388 #define ENGINE_R_PROVIDE_PARAMETERS 113 389 #define ENGINE_R_REQUEST_FAILED 114 390 #define ENGINE_R_REQUEST_FALLBACK 118 391 #define ENGINE_R_SIZE_TOO_LARGE_OR_TOO_SMALL 122 392 #define ENGINE_R_UNIT_FAILURE 115 393 394 #ifdef __cplusplus 395 } 396 #endif 397 #endif 398 399