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