1 /* 2 * Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved. 3 * Copyright (c) 2002, Oracle and/or its affiliates. All rights reserved 4 * 5 * Licensed under the OpenSSL license (the "License"). You may not use 6 * this file except in compliance with the License. You can obtain a copy 7 * in the file LICENSE in the source distribution or at 8 * https://www.openssl.org/source/license.html 9 */ 10 11 #ifndef HEADER_ENGINE_H 12 # define HEADER_ENGINE_H 13 14 # include <openssl/opensslconf.h> 15 16 # ifndef OPENSSL_NO_ENGINE 17 # if OPENSSL_API_COMPAT < 0x10100000L 18 # include <openssl/bn.h> 19 # include <openssl/rsa.h> 20 # include <openssl/dsa.h> 21 # include <openssl/dh.h> 22 # include <openssl/ec.h> 23 # include <openssl/rand.h> 24 # include <openssl/ui.h> 25 # include <openssl/err.h> 26 # endif 27 # include <openssl/ossl_typ.h> 28 # include <openssl/symhacks.h> 29 # include <openssl/x509.h> 30 # include <openssl/engineerr.h> 31 # ifdef __cplusplus 32 extern "C" { 33 # endif 34 35 /* 36 * These flags are used to control combinations of algorithm (methods) by 37 * bitwise "OR"ing. 38 */ 39 # define ENGINE_METHOD_RSA (unsigned int)0x0001 40 # define ENGINE_METHOD_DSA (unsigned int)0x0002 41 # define ENGINE_METHOD_DH (unsigned int)0x0004 42 # define ENGINE_METHOD_RAND (unsigned int)0x0008 43 # define ENGINE_METHOD_CIPHERS (unsigned int)0x0040 44 # define ENGINE_METHOD_DIGESTS (unsigned int)0x0080 45 # define ENGINE_METHOD_PKEY_METHS (unsigned int)0x0200 46 # define ENGINE_METHOD_PKEY_ASN1_METHS (unsigned int)0x0400 47 # define ENGINE_METHOD_EC (unsigned int)0x0800 48 /* Obvious all-or-nothing cases. */ 49 # define ENGINE_METHOD_ALL (unsigned int)0xFFFF 50 # define ENGINE_METHOD_NONE (unsigned int)0x0000 51 52 /* 53 * This(ese) flag(s) controls behaviour of the ENGINE_TABLE mechanism used 54 * internally to control registration of ENGINE implementations, and can be 55 * set by ENGINE_set_table_flags(). The "NOINIT" flag prevents attempts to 56 * initialise registered ENGINEs if they are not already initialised. 57 */ 58 # define ENGINE_TABLE_FLAG_NOINIT (unsigned int)0x0001 59 60 /* ENGINE flags that can be set by ENGINE_set_flags(). */ 61 /* Not used */ 62 /* #define ENGINE_FLAGS_MALLOCED 0x0001 */ 63 64 /* 65 * This flag is for ENGINEs that wish to handle the various 'CMD'-related 66 * control commands on their own. Without this flag, ENGINE_ctrl() handles 67 * these control commands on behalf of the ENGINE using their "cmd_defns" 68 * data. 69 */ 70 # define ENGINE_FLAGS_MANUAL_CMD_CTRL (int)0x0002 71 72 /* 73 * This flag is for ENGINEs who return new duplicate structures when found 74 * via "ENGINE_by_id()". When an ENGINE must store state (eg. if 75 * ENGINE_ctrl() commands are called in sequence as part of some stateful 76 * process like key-generation setup and execution), it can set this flag - 77 * then each attempt to obtain the ENGINE will result in it being copied into 78 * a new structure. Normally, ENGINEs don't declare this flag so 79 * ENGINE_by_id() just increments the existing ENGINE's structural reference 80 * count. 81 */ 82 # define ENGINE_FLAGS_BY_ID_COPY (int)0x0004 83 84 /* 85 * This flag if for an ENGINE that does not want its methods registered as 86 * part of ENGINE_register_all_complete() for example if the methods are not 87 * usable as default methods. 88 */ 89 90 # define ENGINE_FLAGS_NO_REGISTER_ALL (int)0x0008 91 92 /* 93 * ENGINEs can support their own command types, and these flags are used in 94 * ENGINE_CTRL_GET_CMD_FLAGS to indicate to the caller what kind of input 95 * each command expects. Currently only numeric and string input is 96 * supported. If a control command supports none of the _NUMERIC, _STRING, or 97 * _NO_INPUT options, then it is regarded as an "internal" control command - 98 * and not for use in config setting situations. As such, they're not 99 * available to the ENGINE_ctrl_cmd_string() function, only raw ENGINE_ctrl() 100 * access. Changes to this list of 'command types' should be reflected 101 * carefully in ENGINE_cmd_is_executable() and ENGINE_ctrl_cmd_string(). 102 */ 103 104 /* accepts a 'long' input value (3rd parameter to ENGINE_ctrl) */ 105 # define ENGINE_CMD_FLAG_NUMERIC (unsigned int)0x0001 106 /* 107 * accepts string input (cast from 'void*' to 'const char *', 4th parameter 108 * to ENGINE_ctrl) 109 */ 110 # define ENGINE_CMD_FLAG_STRING (unsigned int)0x0002 111 /* 112 * Indicates that the control command takes *no* input. Ie. the control 113 * command is unparameterised. 114 */ 115 # define ENGINE_CMD_FLAG_NO_INPUT (unsigned int)0x0004 116 /* 117 * Indicates that the control command is internal. This control command won't 118 * be shown in any output, and is only usable through the ENGINE_ctrl_cmd() 119 * function. 120 */ 121 # define ENGINE_CMD_FLAG_INTERNAL (unsigned int)0x0008 122 123 /* 124 * NB: These 3 control commands are deprecated and should not be used. 125 * ENGINEs relying on these commands should compile conditional support for 126 * compatibility (eg. if these symbols are defined) but should also migrate 127 * the same functionality to their own ENGINE-specific control functions that 128 * can be "discovered" by calling applications. The fact these control 129 * commands wouldn't be "executable" (ie. usable by text-based config) 130 * doesn't change the fact that application code can find and use them 131 * without requiring per-ENGINE hacking. 132 */ 133 134 /* 135 * These flags are used to tell the ctrl function what should be done. All 136 * command numbers are shared between all engines, even if some don't make 137 * sense to some engines. In such a case, they do nothing but return the 138 * error ENGINE_R_CTRL_COMMAND_NOT_IMPLEMENTED. 139 */ 140 # define ENGINE_CTRL_SET_LOGSTREAM 1 141 # define ENGINE_CTRL_SET_PASSWORD_CALLBACK 2 142 # define ENGINE_CTRL_HUP 3/* Close and reinitialise 143 * any handles/connections 144 * etc. */ 145 # define ENGINE_CTRL_SET_USER_INTERFACE 4/* Alternative to callback */ 146 # define ENGINE_CTRL_SET_CALLBACK_DATA 5/* User-specific data, used 147 * when calling the password 148 * callback and the user 149 * interface */ 150 # define ENGINE_CTRL_LOAD_CONFIGURATION 6/* Load a configuration, 151 * given a string that 152 * represents a file name 153 * or so */ 154 # define ENGINE_CTRL_LOAD_SECTION 7/* Load data from a given 155 * section in the already 156 * loaded configuration */ 157 158 /* 159 * These control commands allow an application to deal with an arbitrary 160 * engine in a dynamic way. Warn: Negative return values indicate errors FOR 161 * THESE COMMANDS because zero is used to indicate 'end-of-list'. Other 162 * commands, including ENGINE-specific command types, return zero for an 163 * error. An ENGINE can choose to implement these ctrl functions, and can 164 * internally manage things however it chooses - it does so by setting the 165 * ENGINE_FLAGS_MANUAL_CMD_CTRL flag (using ENGINE_set_flags()). Otherwise 166 * the ENGINE_ctrl() code handles this on the ENGINE's behalf using the 167 * cmd_defns data (set using ENGINE_set_cmd_defns()). This means an ENGINE's 168 * ctrl() handler need only implement its own commands - the above "meta" 169 * commands will be taken care of. 170 */ 171 172 /* 173 * Returns non-zero if the supplied ENGINE has a ctrl() handler. If "not", 174 * then all the remaining control commands will return failure, so it is 175 * worth checking this first if the caller is trying to "discover" the 176 * engine's capabilities and doesn't want errors generated unnecessarily. 177 */ 178 # define ENGINE_CTRL_HAS_CTRL_FUNCTION 10 179 /* 180 * Returns a positive command number for the first command supported by the 181 * engine. Returns zero if no ctrl commands are supported. 182 */ 183 # define ENGINE_CTRL_GET_FIRST_CMD_TYPE 11 184 /* 185 * The 'long' argument specifies a command implemented by the engine, and the 186 * return value is the next command supported, or zero if there are no more. 187 */ 188 # define ENGINE_CTRL_GET_NEXT_CMD_TYPE 12 189 /* 190 * The 'void*' argument is a command name (cast from 'const char *'), and the 191 * return value is the command that corresponds to it. 192 */ 193 # define ENGINE_CTRL_GET_CMD_FROM_NAME 13 194 /* 195 * The next two allow a command to be converted into its corresponding string 196 * form. In each case, the 'long' argument supplies the command. In the 197 * NAME_LEN case, the return value is the length of the command name (not 198 * counting a trailing EOL). In the NAME case, the 'void*' argument must be a 199 * string buffer large enough, and it will be populated with the name of the 200 * command (WITH a trailing EOL). 201 */ 202 # define ENGINE_CTRL_GET_NAME_LEN_FROM_CMD 14 203 # define ENGINE_CTRL_GET_NAME_FROM_CMD 15 204 /* The next two are similar but give a "short description" of a command. */ 205 # define ENGINE_CTRL_GET_DESC_LEN_FROM_CMD 16 206 # define ENGINE_CTRL_GET_DESC_FROM_CMD 17 207 /* 208 * With this command, the return value is the OR'd combination of 209 * ENGINE_CMD_FLAG_*** values that indicate what kind of input a given 210 * engine-specific ctrl command expects. 211 */ 212 # define ENGINE_CTRL_GET_CMD_FLAGS 18 213 214 /* 215 * ENGINE implementations should start the numbering of their own control 216 * commands from this value. (ie. ENGINE_CMD_BASE, ENGINE_CMD_BASE + 1, etc). 217 */ 218 # define ENGINE_CMD_BASE 200 219 220 /* 221 * NB: These 2 nCipher "chil" control commands are deprecated, and their 222 * functionality is now available through ENGINE-specific control commands 223 * (exposed through the above-mentioned 'CMD'-handling). Code using these 2 224 * commands should be migrated to the more general command handling before 225 * these are removed. 226 */ 227 228 /* Flags specific to the nCipher "chil" engine */ 229 # define ENGINE_CTRL_CHIL_SET_FORKCHECK 100 230 /* 231 * Depending on the value of the (long)i argument, this sets or 232 * unsets the SimpleForkCheck flag in the CHIL API to enable or 233 * disable checking and workarounds for applications that fork(). 234 */ 235 # define ENGINE_CTRL_CHIL_NO_LOCKING 101 236 /* 237 * This prevents the initialisation function from providing mutex 238 * callbacks to the nCipher library. 239 */ 240 241 /* 242 * If an ENGINE supports its own specific control commands and wishes the 243 * framework to handle the above 'ENGINE_CMD_***'-manipulation commands on 244 * its behalf, it should supply a null-terminated array of ENGINE_CMD_DEFN 245 * entries to ENGINE_set_cmd_defns(). It should also implement a ctrl() 246 * handler that supports the stated commands (ie. the "cmd_num" entries as 247 * described by the array). NB: The array must be ordered in increasing order 248 * of cmd_num. "null-terminated" means that the last ENGINE_CMD_DEFN element 249 * has cmd_num set to zero and/or cmd_name set to NULL. 250 */ 251 typedef struct ENGINE_CMD_DEFN_st { 252 unsigned int cmd_num; /* The command number */ 253 const char *cmd_name; /* The command name itself */ 254 const char *cmd_desc; /* A short description of the command */ 255 unsigned int cmd_flags; /* The input the command expects */ 256 } ENGINE_CMD_DEFN; 257 258 /* Generic function pointer */ 259 typedef int (*ENGINE_GEN_FUNC_PTR) (void); 260 /* Generic function pointer taking no arguments */ 261 typedef int (*ENGINE_GEN_INT_FUNC_PTR) (ENGINE *); 262 /* Specific control function pointer */ 263 typedef int (*ENGINE_CTRL_FUNC_PTR) (ENGINE *, int, long, void *, 264 void (*f) (void)); 265 /* Generic load_key function pointer */ 266 typedef EVP_PKEY *(*ENGINE_LOAD_KEY_PTR)(ENGINE *, const char *, 267 UI_METHOD *ui_method, 268 void *callback_data); 269 typedef int (*ENGINE_SSL_CLIENT_CERT_PTR) (ENGINE *, SSL *ssl, 270 STACK_OF(X509_NAME) *ca_dn, 271 X509 **pcert, EVP_PKEY **pkey, 272 STACK_OF(X509) **pother, 273 UI_METHOD *ui_method, 274 void *callback_data); 275 /*- 276 * These callback types are for an ENGINE's handler for cipher and digest logic. 277 * These handlers have these prototypes; 278 * int foo(ENGINE *e, const EVP_CIPHER **cipher, const int **nids, int nid); 279 * int foo(ENGINE *e, const EVP_MD **digest, const int **nids, int nid); 280 * Looking at how to implement these handlers in the case of cipher support, if 281 * the framework wants the EVP_CIPHER for 'nid', it will call; 282 * foo(e, &p_evp_cipher, NULL, nid); (return zero for failure) 283 * If the framework wants a list of supported 'nid's, it will call; 284 * foo(e, NULL, &p_nids, 0); (returns number of 'nids' or -1 for error) 285 */ 286 /* 287 * Returns to a pointer to the array of supported cipher 'nid's. If the 288 * second parameter is non-NULL it is set to the size of the returned array. 289 */ 290 typedef int (*ENGINE_CIPHERS_PTR) (ENGINE *, const EVP_CIPHER **, 291 const int **, int); 292 typedef int (*ENGINE_DIGESTS_PTR) (ENGINE *, const EVP_MD **, const int **, 293 int); 294 typedef int (*ENGINE_PKEY_METHS_PTR) (ENGINE *, EVP_PKEY_METHOD **, 295 const int **, int); 296 typedef int (*ENGINE_PKEY_ASN1_METHS_PTR) (ENGINE *, EVP_PKEY_ASN1_METHOD **, 297 const int **, int); 298 /* 299 * STRUCTURE functions ... all of these functions deal with pointers to 300 * ENGINE structures where the pointers have a "structural reference". This 301 * means that their reference is to allowed access to the structure but it 302 * does not imply that the structure is functional. To simply increment or 303 * decrement the structural reference count, use ENGINE_by_id and 304 * ENGINE_free. NB: This is not required when iterating using ENGINE_get_next 305 * as it will automatically decrement the structural reference count of the 306 * "current" ENGINE and increment the structural reference count of the 307 * ENGINE it returns (unless it is NULL). 308 */ 309 310 /* Get the first/last "ENGINE" type available. */ 311 ENGINE *ENGINE_get_first(void); 312 ENGINE *ENGINE_get_last(void); 313 /* Iterate to the next/previous "ENGINE" type (NULL = end of the list). */ 314 ENGINE *ENGINE_get_next(ENGINE *e); 315 ENGINE *ENGINE_get_prev(ENGINE *e); 316 /* Add another "ENGINE" type into the array. */ 317 int ENGINE_add(ENGINE *e); 318 /* Remove an existing "ENGINE" type from the array. */ 319 int ENGINE_remove(ENGINE *e); 320 /* Retrieve an engine from the list by its unique "id" value. */ 321 ENGINE *ENGINE_by_id(const char *id); 322 323 #if OPENSSL_API_COMPAT < 0x10100000L 324 # define ENGINE_load_openssl() \ 325 OPENSSL_init_crypto(OPENSSL_INIT_ENGINE_OPENSSL, NULL) 326 # define ENGINE_load_dynamic() \ 327 OPENSSL_init_crypto(OPENSSL_INIT_ENGINE_DYNAMIC, NULL) 328 # ifndef OPENSSL_NO_STATIC_ENGINE 329 # define ENGINE_load_padlock() \ 330 OPENSSL_init_crypto(OPENSSL_INIT_ENGINE_PADLOCK, NULL) 331 # define ENGINE_load_capi() \ 332 OPENSSL_init_crypto(OPENSSL_INIT_ENGINE_CAPI, NULL) 333 # define ENGINE_load_afalg() \ 334 OPENSSL_init_crypto(OPENSSL_INIT_ENGINE_AFALG, NULL) 335 # endif 336 # define ENGINE_load_cryptodev() \ 337 OPENSSL_init_crypto(OPENSSL_INIT_ENGINE_CRYPTODEV, NULL) 338 # define ENGINE_load_rdrand() \ 339 OPENSSL_init_crypto(OPENSSL_INIT_ENGINE_RDRAND, NULL) 340 #endif 341 void ENGINE_load_builtin_engines(void); 342 343 /* 344 * Get and set global flags (ENGINE_TABLE_FLAG_***) for the implementation 345 * "registry" handling. 346 */ 347 unsigned int ENGINE_get_table_flags(void); 348 void ENGINE_set_table_flags(unsigned int flags); 349 350 /*- Manage registration of ENGINEs per "table". For each type, there are 3 351 * functions; 352 * ENGINE_register_***(e) - registers the implementation from 'e' (if it has one) 353 * ENGINE_unregister_***(e) - unregister the implementation from 'e' 354 * ENGINE_register_all_***() - call ENGINE_register_***() for each 'e' in the list 355 * Cleanup is automatically registered from each table when required. 356 */ 357 358 int ENGINE_register_RSA(ENGINE *e); 359 void ENGINE_unregister_RSA(ENGINE *e); 360 void ENGINE_register_all_RSA(void); 361 362 int ENGINE_register_DSA(ENGINE *e); 363 void ENGINE_unregister_DSA(ENGINE *e); 364 void ENGINE_register_all_DSA(void); 365 366 int ENGINE_register_EC(ENGINE *e); 367 void ENGINE_unregister_EC(ENGINE *e); 368 void ENGINE_register_all_EC(void); 369 370 int ENGINE_register_DH(ENGINE *e); 371 void ENGINE_unregister_DH(ENGINE *e); 372 void ENGINE_register_all_DH(void); 373 374 int ENGINE_register_RAND(ENGINE *e); 375 void ENGINE_unregister_RAND(ENGINE *e); 376 void ENGINE_register_all_RAND(void); 377 378 int ENGINE_register_ciphers(ENGINE *e); 379 void ENGINE_unregister_ciphers(ENGINE *e); 380 void ENGINE_register_all_ciphers(void); 381 382 int ENGINE_register_digests(ENGINE *e); 383 void ENGINE_unregister_digests(ENGINE *e); 384 void ENGINE_register_all_digests(void); 385 386 int ENGINE_register_pkey_meths(ENGINE *e); 387 void ENGINE_unregister_pkey_meths(ENGINE *e); 388 void ENGINE_register_all_pkey_meths(void); 389 390 int ENGINE_register_pkey_asn1_meths(ENGINE *e); 391 void ENGINE_unregister_pkey_asn1_meths(ENGINE *e); 392 void ENGINE_register_all_pkey_asn1_meths(void); 393 394 /* 395 * These functions register all support from the above categories. Note, use 396 * of these functions can result in static linkage of code your application 397 * may not need. If you only need a subset of functionality, consider using 398 * more selective initialisation. 399 */ 400 int ENGINE_register_complete(ENGINE *e); 401 int ENGINE_register_all_complete(void); 402 403 /* 404 * Send parameterised control commands to the engine. The possibilities to 405 * send down an integer, a pointer to data or a function pointer are 406 * provided. Any of the parameters may or may not be NULL, depending on the 407 * command number. In actuality, this function only requires a structural 408 * (rather than functional) reference to an engine, but many control commands 409 * may require the engine be functional. The caller should be aware of trying 410 * commands that require an operational ENGINE, and only use functional 411 * references in such situations. 412 */ 413 int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f) (void)); 414 415 /* 416 * This function tests if an ENGINE-specific command is usable as a 417 * "setting". Eg. in an application's config file that gets processed through 418 * ENGINE_ctrl_cmd_string(). If this returns zero, it is not available to 419 * ENGINE_ctrl_cmd_string(), only ENGINE_ctrl(). 420 */ 421 int ENGINE_cmd_is_executable(ENGINE *e, int cmd); 422 423 /* 424 * This function works like ENGINE_ctrl() with the exception of taking a 425 * command name instead of a command number, and can handle optional 426 * commands. See the comment on ENGINE_ctrl_cmd_string() for an explanation 427 * on how to use the cmd_name and cmd_optional. 428 */ 429 int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name, 430 long i, void *p, void (*f) (void), int cmd_optional); 431 432 /* 433 * This function passes a command-name and argument to an ENGINE. The 434 * cmd_name is converted to a command number and the control command is 435 * called using 'arg' as an argument (unless the ENGINE doesn't support such 436 * a command, in which case no control command is called). The command is 437 * checked for input flags, and if necessary the argument will be converted 438 * to a numeric value. If cmd_optional is non-zero, then if the ENGINE 439 * doesn't support the given cmd_name the return value will be success 440 * anyway. This function is intended for applications to use so that users 441 * (or config files) can supply engine-specific config data to the ENGINE at 442 * run-time to control behaviour of specific engines. As such, it shouldn't 443 * be used for calling ENGINE_ctrl() functions that return data, deal with 444 * binary data, or that are otherwise supposed to be used directly through 445 * ENGINE_ctrl() in application code. Any "return" data from an ENGINE_ctrl() 446 * operation in this function will be lost - the return value is interpreted 447 * as failure if the return value is zero, success otherwise, and this 448 * function returns a boolean value as a result. In other words, vendors of 449 * 'ENGINE'-enabled devices should write ENGINE implementations with 450 * parameterisations that work in this scheme, so that compliant ENGINE-based 451 * applications can work consistently with the same configuration for the 452 * same ENGINE-enabled devices, across applications. 453 */ 454 int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg, 455 int cmd_optional); 456 457 /* 458 * These functions are useful for manufacturing new ENGINE structures. They 459 * don't address reference counting at all - one uses them to populate an 460 * ENGINE structure with personalised implementations of things prior to 461 * using it directly or adding it to the builtin ENGINE list in OpenSSL. 462 * These are also here so that the ENGINE structure doesn't have to be 463 * exposed and break binary compatibility! 464 */ 465 ENGINE *ENGINE_new(void); 466 int ENGINE_free(ENGINE *e); 467 int ENGINE_up_ref(ENGINE *e); 468 int ENGINE_set_id(ENGINE *e, const char *id); 469 int ENGINE_set_name(ENGINE *e, const char *name); 470 int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth); 471 int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth); 472 int ENGINE_set_EC(ENGINE *e, const EC_KEY_METHOD *ecdsa_meth); 473 int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth); 474 int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth); 475 int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f); 476 int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f); 477 int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f); 478 int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f); 479 int ENGINE_set_load_privkey_function(ENGINE *e, 480 ENGINE_LOAD_KEY_PTR loadpriv_f); 481 int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f); 482 int ENGINE_set_load_ssl_client_cert_function(ENGINE *e, 483 ENGINE_SSL_CLIENT_CERT_PTR 484 loadssl_f); 485 int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f); 486 int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f); 487 int ENGINE_set_pkey_meths(ENGINE *e, ENGINE_PKEY_METHS_PTR f); 488 int ENGINE_set_pkey_asn1_meths(ENGINE *e, ENGINE_PKEY_ASN1_METHS_PTR f); 489 int ENGINE_set_flags(ENGINE *e, int flags); 490 int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns); 491 /* These functions allow control over any per-structure ENGINE data. */ 492 #define ENGINE_get_ex_new_index(l, p, newf, dupf, freef) \ 493 CRYPTO_get_ex_new_index(CRYPTO_EX_INDEX_ENGINE, l, p, newf, dupf, freef) 494 int ENGINE_set_ex_data(ENGINE *e, int idx, void *arg); 495 void *ENGINE_get_ex_data(const ENGINE *e, int idx); 496 497 #if OPENSSL_API_COMPAT < 0x10100000L 498 /* 499 * This function previously cleaned up anything that needs it. Auto-deinit will 500 * now take care of it so it is no longer required to call this function. 501 */ 502 # define ENGINE_cleanup() while(0) continue 503 #endif 504 505 /* 506 * These return values from within the ENGINE structure. These can be useful 507 * with functional references as well as structural references - it depends 508 * which you obtained. Using the result for functional purposes if you only 509 * obtained a structural reference may be problematic! 510 */ 511 const char *ENGINE_get_id(const ENGINE *e); 512 const char *ENGINE_get_name(const ENGINE *e); 513 const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e); 514 const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e); 515 const EC_KEY_METHOD *ENGINE_get_EC(const ENGINE *e); 516 const DH_METHOD *ENGINE_get_DH(const ENGINE *e); 517 const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e); 518 ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e); 519 ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e); 520 ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e); 521 ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e); 522 ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e); 523 ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e); 524 ENGINE_SSL_CLIENT_CERT_PTR ENGINE_get_ssl_client_cert_function(const ENGINE 525 *e); 526 ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e); 527 ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e); 528 ENGINE_PKEY_METHS_PTR ENGINE_get_pkey_meths(const ENGINE *e); 529 ENGINE_PKEY_ASN1_METHS_PTR ENGINE_get_pkey_asn1_meths(const ENGINE *e); 530 const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid); 531 const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid); 532 const EVP_PKEY_METHOD *ENGINE_get_pkey_meth(ENGINE *e, int nid); 533 const EVP_PKEY_ASN1_METHOD *ENGINE_get_pkey_asn1_meth(ENGINE *e, int nid); 534 const EVP_PKEY_ASN1_METHOD *ENGINE_get_pkey_asn1_meth_str(ENGINE *e, 535 const char *str, 536 int len); 537 const EVP_PKEY_ASN1_METHOD *ENGINE_pkey_asn1_find_str(ENGINE **pe, 538 const char *str, 539 int len); 540 const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e); 541 int ENGINE_get_flags(const ENGINE *e); 542 543 /* 544 * FUNCTIONAL functions. These functions deal with ENGINE structures that 545 * have (or will) be initialised for use. Broadly speaking, the structural 546 * functions are useful for iterating the list of available engine types, 547 * creating new engine types, and other "list" operations. These functions 548 * actually deal with ENGINEs that are to be used. As such these functions 549 * can fail (if applicable) when particular engines are unavailable - eg. if 550 * a hardware accelerator is not attached or not functioning correctly. Each 551 * ENGINE has 2 reference counts; structural and functional. Every time a 552 * functional reference is obtained or released, a corresponding structural 553 * reference is automatically obtained or released too. 554 */ 555 556 /* 557 * Initialise a engine type for use (or up its reference count if it's 558 * already in use). This will fail if the engine is not currently operational 559 * and cannot initialise. 560 */ 561 int ENGINE_init(ENGINE *e); 562 /* 563 * Free a functional reference to a engine type. This does not require a 564 * corresponding call to ENGINE_free as it also releases a structural 565 * reference. 566 */ 567 int ENGINE_finish(ENGINE *e); 568 569 /* 570 * The following functions handle keys that are stored in some secondary 571 * location, handled by the engine. The storage may be on a card or 572 * whatever. 573 */ 574 EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id, 575 UI_METHOD *ui_method, void *callback_data); 576 EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id, 577 UI_METHOD *ui_method, void *callback_data); 578 int ENGINE_load_ssl_client_cert(ENGINE *e, SSL *s, 579 STACK_OF(X509_NAME) *ca_dn, X509 **pcert, 580 EVP_PKEY **ppkey, STACK_OF(X509) **pother, 581 UI_METHOD *ui_method, void *callback_data); 582 583 /* 584 * This returns a pointer for the current ENGINE structure that is (by 585 * default) performing any RSA operations. The value returned is an 586 * incremented reference, so it should be free'd (ENGINE_finish) before it is 587 * discarded. 588 */ 589 ENGINE *ENGINE_get_default_RSA(void); 590 /* Same for the other "methods" */ 591 ENGINE *ENGINE_get_default_DSA(void); 592 ENGINE *ENGINE_get_default_EC(void); 593 ENGINE *ENGINE_get_default_DH(void); 594 ENGINE *ENGINE_get_default_RAND(void); 595 /* 596 * These functions can be used to get a functional reference to perform 597 * ciphering or digesting corresponding to "nid". 598 */ 599 ENGINE *ENGINE_get_cipher_engine(int nid); 600 ENGINE *ENGINE_get_digest_engine(int nid); 601 ENGINE *ENGINE_get_pkey_meth_engine(int nid); 602 ENGINE *ENGINE_get_pkey_asn1_meth_engine(int nid); 603 604 /* 605 * This sets a new default ENGINE structure for performing RSA operations. If 606 * the result is non-zero (success) then the ENGINE structure will have had 607 * its reference count up'd so the caller should still free their own 608 * reference 'e'. 609 */ 610 int ENGINE_set_default_RSA(ENGINE *e); 611 int ENGINE_set_default_string(ENGINE *e, const char *def_list); 612 /* Same for the other "methods" */ 613 int ENGINE_set_default_DSA(ENGINE *e); 614 int ENGINE_set_default_EC(ENGINE *e); 615 int ENGINE_set_default_DH(ENGINE *e); 616 int ENGINE_set_default_RAND(ENGINE *e); 617 int ENGINE_set_default_ciphers(ENGINE *e); 618 int ENGINE_set_default_digests(ENGINE *e); 619 int ENGINE_set_default_pkey_meths(ENGINE *e); 620 int ENGINE_set_default_pkey_asn1_meths(ENGINE *e); 621 622 /* 623 * The combination "set" - the flags are bitwise "OR"d from the 624 * ENGINE_METHOD_*** defines above. As with the "ENGINE_register_complete()" 625 * function, this function can result in unnecessary static linkage. If your 626 * application requires only specific functionality, consider using more 627 * selective functions. 628 */ 629 int ENGINE_set_default(ENGINE *e, unsigned int flags); 630 631 void ENGINE_add_conf_module(void); 632 633 /* Deprecated functions ... */ 634 /* int ENGINE_clear_defaults(void); */ 635 636 /**************************/ 637 /* DYNAMIC ENGINE SUPPORT */ 638 /**************************/ 639 640 /* Binary/behaviour compatibility levels */ 641 # define OSSL_DYNAMIC_VERSION (unsigned long)0x00030000 642 /* 643 * Binary versions older than this are too old for us (whether we're a loader 644 * or a loadee) 645 */ 646 # define OSSL_DYNAMIC_OLDEST (unsigned long)0x00030000 647 648 /* 649 * When compiling an ENGINE entirely as an external shared library, loadable 650 * by the "dynamic" ENGINE, these types are needed. The 'dynamic_fns' 651 * structure type provides the calling application's (or library's) error 652 * functionality and memory management function pointers to the loaded 653 * library. These should be used/set in the loaded library code so that the 654 * loading application's 'state' will be used/changed in all operations. The 655 * 'static_state' pointer allows the loaded library to know if it shares the 656 * same static data as the calling application (or library), and thus whether 657 * these callbacks need to be set or not. 658 */ 659 typedef void *(*dyn_MEM_malloc_fn) (size_t, const char *, int); 660 typedef void *(*dyn_MEM_realloc_fn) (void *, size_t, const char *, int); 661 typedef void (*dyn_MEM_free_fn) (void *, const char *, int); 662 typedef struct st_dynamic_MEM_fns { 663 dyn_MEM_malloc_fn malloc_fn; 664 dyn_MEM_realloc_fn realloc_fn; 665 dyn_MEM_free_fn free_fn; 666 } dynamic_MEM_fns; 667 /* 668 * FIXME: Perhaps the memory and locking code (crypto.h) should declare and 669 * use these types so we (and any other dependent code) can simplify a bit?? 670 */ 671 /* The top-level structure */ 672 typedef struct st_dynamic_fns { 673 void *static_state; 674 dynamic_MEM_fns mem_fns; 675 } dynamic_fns; 676 677 /* 678 * The version checking function should be of this prototype. NB: The 679 * ossl_version value passed in is the OSSL_DYNAMIC_VERSION of the loading 680 * code. If this function returns zero, it indicates a (potential) version 681 * incompatibility and the loaded library doesn't believe it can proceed. 682 * Otherwise, the returned value is the (latest) version supported by the 683 * loading library. The loader may still decide that the loaded code's 684 * version is unsatisfactory and could veto the load. The function is 685 * expected to be implemented with the symbol name "v_check", and a default 686 * implementation can be fully instantiated with 687 * IMPLEMENT_DYNAMIC_CHECK_FN(). 688 */ 689 typedef unsigned long (*dynamic_v_check_fn) (unsigned long ossl_version); 690 # define IMPLEMENT_DYNAMIC_CHECK_FN() \ 691 OPENSSL_EXPORT unsigned long v_check(unsigned long v); \ 692 OPENSSL_EXPORT unsigned long v_check(unsigned long v) { \ 693 if (v >= OSSL_DYNAMIC_OLDEST) return OSSL_DYNAMIC_VERSION; \ 694 return 0; } 695 696 /* 697 * This function is passed the ENGINE structure to initialise with its own 698 * function and command settings. It should not adjust the structural or 699 * functional reference counts. If this function returns zero, (a) the load 700 * will be aborted, (b) the previous ENGINE state will be memcpy'd back onto 701 * the structure, and (c) the shared library will be unloaded. So 702 * implementations should do their own internal cleanup in failure 703 * circumstances otherwise they could leak. The 'id' parameter, if non-NULL, 704 * represents the ENGINE id that the loader is looking for. If this is NULL, 705 * the shared library can choose to return failure or to initialise a 706 * 'default' ENGINE. If non-NULL, the shared library must initialise only an 707 * ENGINE matching the passed 'id'. The function is expected to be 708 * implemented with the symbol name "bind_engine". A standard implementation 709 * can be instantiated with IMPLEMENT_DYNAMIC_BIND_FN(fn) where the parameter 710 * 'fn' is a callback function that populates the ENGINE structure and 711 * returns an int value (zero for failure). 'fn' should have prototype; 712 * [static] int fn(ENGINE *e, const char *id); 713 */ 714 typedef int (*dynamic_bind_engine) (ENGINE *e, const char *id, 715 const dynamic_fns *fns); 716 # define IMPLEMENT_DYNAMIC_BIND_FN(fn) \ 717 OPENSSL_EXPORT \ 718 int bind_engine(ENGINE *e, const char *id, const dynamic_fns *fns); \ 719 OPENSSL_EXPORT \ 720 int bind_engine(ENGINE *e, const char *id, const dynamic_fns *fns) { \ 721 if (ENGINE_get_static_state() == fns->static_state) goto skip_cbs; \ 722 CRYPTO_set_mem_functions(fns->mem_fns.malloc_fn, \ 723 fns->mem_fns.realloc_fn, \ 724 fns->mem_fns.free_fn); \ 725 OPENSSL_init_crypto(OPENSSL_INIT_NO_ATEXIT, NULL); \ 726 skip_cbs: \ 727 if (!fn(e, id)) return 0; \ 728 return 1; } 729 730 /* 731 * If the loading application (or library) and the loaded ENGINE library 732 * share the same static data (eg. they're both dynamically linked to the 733 * same libcrypto.so) we need a way to avoid trying to set system callbacks - 734 * this would fail, and for the same reason that it's unnecessary to try. If 735 * the loaded ENGINE has (or gets from through the loader) its own copy of 736 * the libcrypto static data, we will need to set the callbacks. The easiest 737 * way to detect this is to have a function that returns a pointer to some 738 * static data and let the loading application and loaded ENGINE compare 739 * their respective values. 740 */ 741 void *ENGINE_get_static_state(void); 742 743 # if defined(__OpenBSD__) || defined(__FreeBSD__) || defined(__DragonFly__) 744 DEPRECATEDIN_1_1_0(void ENGINE_setup_bsd_cryptodev(void)) 745 # endif 746 747 748 # ifdef __cplusplus 749 } 750 # endif 751 # endif 752 #endif 753