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 is 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() \ 543 while (0) \ 544 continue 545 #endif 546 547 /* 548 * These return values from within the ENGINE structure. These can be useful 549 * with functional references as well as structural references - it depends 550 * which you obtained. Using the result for functional purposes if you only 551 * obtained a structural reference may be problematic! 552 */ 553 #ifndef OPENSSL_NO_DEPRECATED_3_0 554 OSSL_DEPRECATEDIN_3_0 const char *ENGINE_get_id(const ENGINE *e); 555 OSSL_DEPRECATEDIN_3_0 const char *ENGINE_get_name(const ENGINE *e); 556 OSSL_DEPRECATEDIN_3_0 const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e); 557 OSSL_DEPRECATEDIN_3_0 const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e); 558 OSSL_DEPRECATEDIN_3_0 const EC_KEY_METHOD *ENGINE_get_EC(const ENGINE *e); 559 OSSL_DEPRECATEDIN_3_0 const DH_METHOD *ENGINE_get_DH(const ENGINE *e); 560 OSSL_DEPRECATEDIN_3_0 const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e); 561 OSSL_DEPRECATEDIN_3_0 562 ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e); 563 OSSL_DEPRECATEDIN_3_0 564 ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e); 565 OSSL_DEPRECATEDIN_3_0 566 ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e); 567 OSSL_DEPRECATEDIN_3_0 568 ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e); 569 OSSL_DEPRECATEDIN_3_0 570 ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e); 571 OSSL_DEPRECATEDIN_3_0 572 ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e); 573 OSSL_DEPRECATEDIN_3_0 574 ENGINE_SSL_CLIENT_CERT_PTR ENGINE_get_ssl_client_cert_function(const ENGINE *e); 575 OSSL_DEPRECATEDIN_3_0 576 ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e); 577 OSSL_DEPRECATEDIN_3_0 578 ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e); 579 OSSL_DEPRECATEDIN_3_0 580 ENGINE_PKEY_METHS_PTR ENGINE_get_pkey_meths(const ENGINE *e); 581 OSSL_DEPRECATEDIN_3_0 582 ENGINE_PKEY_ASN1_METHS_PTR ENGINE_get_pkey_asn1_meths(const ENGINE *e); 583 OSSL_DEPRECATEDIN_3_0 584 const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid); 585 OSSL_DEPRECATEDIN_3_0 586 const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid); 587 OSSL_DEPRECATEDIN_3_0 588 const EVP_PKEY_METHOD *ENGINE_get_pkey_meth(ENGINE *e, int nid); 589 OSSL_DEPRECATEDIN_3_0 590 const EVP_PKEY_ASN1_METHOD *ENGINE_get_pkey_asn1_meth(ENGINE *e, int nid); 591 OSSL_DEPRECATEDIN_3_0 592 const EVP_PKEY_ASN1_METHOD *ENGINE_get_pkey_asn1_meth_str(ENGINE *e, 593 const char *str, 594 int len); 595 OSSL_DEPRECATEDIN_3_0 596 const EVP_PKEY_ASN1_METHOD *ENGINE_pkey_asn1_find_str(ENGINE **pe, 597 const char *str, int len); 598 OSSL_DEPRECATEDIN_3_0 599 const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e); 600 OSSL_DEPRECATEDIN_3_0 int ENGINE_get_flags(const ENGINE *e); 601 #endif 602 603 /* 604 * FUNCTIONAL functions. These functions deal with ENGINE structures that 605 * have (or will) be initialised for use. Broadly speaking, the structural 606 * functions are useful for iterating the list of available engine types, 607 * creating new engine types, and other "list" operations. These functions 608 * actually deal with ENGINEs that are to be used. As such these functions 609 * can fail (if applicable) when particular engines are unavailable - eg. if 610 * a hardware accelerator is not attached or not functioning correctly. Each 611 * ENGINE has 2 reference counts; structural and functional. Every time a 612 * functional reference is obtained or released, a corresponding structural 613 * reference is automatically obtained or released too. 614 */ 615 616 /* 617 * Initialise an engine type for use (or up its reference count if it's 618 * already in use). This will fail if the engine is not currently operational 619 * and cannot initialise. 620 */ 621 #ifndef OPENSSL_NO_DEPRECATED_3_0 622 OSSL_DEPRECATEDIN_3_0 int ENGINE_init(ENGINE *e); 623 #endif 624 /* 625 * Free a functional reference to an engine type. This does not require a 626 * corresponding call to ENGINE_free as it also releases a structural 627 * reference. 628 */ 629 #ifndef OPENSSL_NO_DEPRECATED_3_0 630 OSSL_DEPRECATEDIN_3_0 int ENGINE_finish(ENGINE *e); 631 #endif 632 633 /* 634 * The following functions handle keys that are stored in some secondary 635 * location, handled by the engine. The storage may be on a card or 636 * whatever. 637 */ 638 #ifndef OPENSSL_NO_DEPRECATED_3_0 639 OSSL_DEPRECATEDIN_3_0 640 EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id, 641 UI_METHOD *ui_method, void *callback_data); 642 OSSL_DEPRECATEDIN_3_0 643 EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id, 644 UI_METHOD *ui_method, void *callback_data); 645 OSSL_DEPRECATEDIN_3_0 646 int ENGINE_load_ssl_client_cert(ENGINE *e, SSL *s, STACK_OF(X509_NAME) *ca_dn, 647 X509 **pcert, EVP_PKEY **ppkey, 648 STACK_OF(X509) **pother, 649 UI_METHOD *ui_method, void *callback_data); 650 #endif 651 652 /* 653 * This returns a pointer for the current ENGINE structure that is (by 654 * default) performing any RSA operations. The value returned is an 655 * incremented reference, so it should be free'd (ENGINE_finish) before it is 656 * discarded. 657 */ 658 #ifndef OPENSSL_NO_DEPRECATED_3_0 659 OSSL_DEPRECATEDIN_3_0 ENGINE *ENGINE_get_default_RSA(void); 660 #endif 661 /* Same for the other "methods" */ 662 #ifndef OPENSSL_NO_DEPRECATED_3_0 663 OSSL_DEPRECATEDIN_3_0 ENGINE *ENGINE_get_default_DSA(void); 664 OSSL_DEPRECATEDIN_3_0 ENGINE *ENGINE_get_default_EC(void); 665 OSSL_DEPRECATEDIN_3_0 ENGINE *ENGINE_get_default_DH(void); 666 OSSL_DEPRECATEDIN_3_0 ENGINE *ENGINE_get_default_RAND(void); 667 #endif 668 /* 669 * These functions can be used to get a functional reference to perform 670 * ciphering or digesting corresponding to "nid". 671 */ 672 #ifndef OPENSSL_NO_DEPRECATED_3_0 673 OSSL_DEPRECATEDIN_3_0 ENGINE *ENGINE_get_cipher_engine(int nid); 674 OSSL_DEPRECATEDIN_3_0 ENGINE *ENGINE_get_digest_engine(int nid); 675 OSSL_DEPRECATEDIN_3_0 ENGINE *ENGINE_get_pkey_meth_engine(int nid); 676 OSSL_DEPRECATEDIN_3_0 ENGINE *ENGINE_get_pkey_asn1_meth_engine(int nid); 677 #endif 678 679 /* 680 * This sets a new default ENGINE structure for performing RSA operations. If 681 * the result is non-zero (success) then the ENGINE structure will have had 682 * its reference count up'd so the caller should still free their own 683 * reference 'e'. 684 */ 685 #ifndef OPENSSL_NO_DEPRECATED_3_0 686 OSSL_DEPRECATEDIN_3_0 int ENGINE_set_default_RSA(ENGINE *e); 687 OSSL_DEPRECATEDIN_3_0 int ENGINE_set_default_string(ENGINE *e, 688 const char *def_list); 689 #endif 690 /* Same for the other "methods" */ 691 #ifndef OPENSSL_NO_DEPRECATED_3_0 692 OSSL_DEPRECATEDIN_3_0 int ENGINE_set_default_DSA(ENGINE *e); 693 OSSL_DEPRECATEDIN_3_0 int ENGINE_set_default_EC(ENGINE *e); 694 OSSL_DEPRECATEDIN_3_0 int ENGINE_set_default_DH(ENGINE *e); 695 OSSL_DEPRECATEDIN_3_0 int ENGINE_set_default_RAND(ENGINE *e); 696 OSSL_DEPRECATEDIN_3_0 int ENGINE_set_default_ciphers(ENGINE *e); 697 OSSL_DEPRECATEDIN_3_0 int ENGINE_set_default_digests(ENGINE *e); 698 OSSL_DEPRECATEDIN_3_0 int ENGINE_set_default_pkey_meths(ENGINE *e); 699 OSSL_DEPRECATEDIN_3_0 int ENGINE_set_default_pkey_asn1_meths(ENGINE *e); 700 #endif 701 702 /* 703 * The combination "set" - the flags are bitwise "OR"d from the 704 * ENGINE_METHOD_*** defines above. As with the "ENGINE_register_complete()" 705 * function, this function can result in unnecessary static linkage. If your 706 * application requires only specific functionality, consider using more 707 * selective functions. 708 */ 709 #ifndef OPENSSL_NO_DEPRECATED_3_0 710 OSSL_DEPRECATEDIN_3_0 int ENGINE_set_default(ENGINE *e, unsigned int flags); 711 OSSL_DEPRECATEDIN_3_0 void ENGINE_add_conf_module(void); 712 #endif 713 714 /* Deprecated functions ... */ 715 /* int ENGINE_clear_defaults(void); */ 716 717 /**************************/ 718 /* DYNAMIC ENGINE SUPPORT */ 719 /**************************/ 720 721 /* Binary/behaviour compatibility levels */ 722 #define OSSL_DYNAMIC_VERSION (unsigned long)0x00030000 723 /* 724 * Binary versions older than this are too old for us (whether we're a loader 725 * or a loadee) 726 */ 727 #define OSSL_DYNAMIC_OLDEST (unsigned long)0x00030000 728 729 /* 730 * When compiling an ENGINE entirely as an external shared library, loadable 731 * by the "dynamic" ENGINE, these types are needed. The 'dynamic_fns' 732 * structure type provides the calling application's (or library's) error 733 * functionality and memory management function pointers to the loaded 734 * library. These should be used/set in the loaded library code so that the 735 * loading application's 'state' will be used/changed in all operations. The 736 * 'static_state' pointer allows the loaded library to know if it shares the 737 * same static data as the calling application (or library), and thus whether 738 * these callbacks need to be set or not. 739 */ 740 typedef void *(*dyn_MEM_malloc_fn)(size_t, const char *, int); 741 typedef void *(*dyn_MEM_realloc_fn)(void *, size_t, const char *, int); 742 typedef void (*dyn_MEM_free_fn)(void *, const char *, int); 743 typedef struct st_dynamic_MEM_fns { 744 dyn_MEM_malloc_fn malloc_fn; 745 dyn_MEM_realloc_fn realloc_fn; 746 dyn_MEM_free_fn free_fn; 747 } dynamic_MEM_fns; 748 /* 749 * FIXME: Perhaps the memory and locking code (crypto.h) should declare and 750 * use these types so we (and any other dependent code) can simplify a bit?? 751 */ 752 /* The top-level structure */ 753 typedef struct st_dynamic_fns { 754 void *static_state; 755 dynamic_MEM_fns mem_fns; 756 } dynamic_fns; 757 758 /* 759 * The version checking function should be of this prototype. NB: The 760 * ossl_version value passed in is the OSSL_DYNAMIC_VERSION of the loading 761 * code. If this function returns zero, it indicates a (potential) version 762 * incompatibility and the loaded library doesn't believe it can proceed. 763 * Otherwise, the returned value is the (latest) version supported by the 764 * loading library. The loader may still decide that the loaded code's 765 * version is unsatisfactory and could veto the load. The function is 766 * expected to be implemented with the symbol name "v_check", and a default 767 * implementation can be fully instantiated with 768 * IMPLEMENT_DYNAMIC_CHECK_FN(). 769 */ 770 typedef unsigned long (*dynamic_v_check_fn)(unsigned long ossl_version); 771 #define IMPLEMENT_DYNAMIC_CHECK_FN() \ 772 OPENSSL_EXPORT unsigned long v_check(unsigned long v); \ 773 OPENSSL_EXPORT unsigned long v_check(unsigned long v) \ 774 { \ 775 if (v >= OSSL_DYNAMIC_OLDEST) \ 776 return OSSL_DYNAMIC_VERSION; \ 777 return 0; \ 778 } 779 780 /* 781 * This function is passed the ENGINE structure to initialise with its own 782 * function and command settings. It should not adjust the structural or 783 * functional reference counts. If this function returns zero, (a) the load 784 * will be aborted, (b) the previous ENGINE state will be memcpy'd back onto 785 * the structure, and (c) the shared library will be unloaded. So 786 * implementations should do their own internal cleanup in failure 787 * circumstances otherwise they could leak. The 'id' parameter, if non-NULL, 788 * represents the ENGINE id that the loader is looking for. If this is NULL, 789 * the shared library can choose to return failure or to initialise a 790 * 'default' ENGINE. If non-NULL, the shared library must initialise only an 791 * ENGINE matching the passed 'id'. The function is expected to be 792 * implemented with the symbol name "bind_engine". A standard implementation 793 * can be instantiated with IMPLEMENT_DYNAMIC_BIND_FN(fn) where the parameter 794 * 'fn' is a callback function that populates the ENGINE structure and 795 * returns an int value (zero for failure). 'fn' should have prototype; 796 * [static] int fn(ENGINE *e, const char *id); 797 */ 798 typedef int (*dynamic_bind_engine)(ENGINE *e, const char *id, 799 const dynamic_fns *fns); 800 #define IMPLEMENT_DYNAMIC_BIND_FN(fn) \ 801 OPENSSL_EXPORT \ 802 int bind_engine(ENGINE *e, const char *id, const dynamic_fns *fns); \ 803 OPENSSL_EXPORT \ 804 int bind_engine(ENGINE *e, const char *id, const dynamic_fns *fns) \ 805 { \ 806 if (ENGINE_get_static_state() == fns->static_state) \ 807 goto skip_cbs; \ 808 CRYPTO_set_mem_functions(fns->mem_fns.malloc_fn, \ 809 fns->mem_fns.realloc_fn, \ 810 fns->mem_fns.free_fn); \ 811 OPENSSL_init_crypto(OPENSSL_INIT_NO_ATEXIT, NULL); \ 812 skip_cbs: \ 813 if (!fn(e, id)) \ 814 return 0; \ 815 return 1; \ 816 } 817 818 /* 819 * If the loading application (or library) and the loaded ENGINE library 820 * share the same static data (eg. they're both dynamically linked to the 821 * same libcrypto.so) we need a way to avoid trying to set system callbacks - 822 * this would fail, and for the same reason that it's unnecessary to try. If 823 * the loaded ENGINE has (or gets from through the loader) its own copy of 824 * the libcrypto static data, we will need to set the callbacks. The easiest 825 * way to detect this is to have a function that returns a pointer to some 826 * static data and let the loading application and loaded ENGINE compare 827 * their respective values. 828 */ 829 void *ENGINE_get_static_state(void); 830 831 #if defined(__OpenBSD__) || defined(__FreeBSD__) || defined(__DragonFly__) 832 #ifndef OPENSSL_NO_DEPRECATED_1_1_0 833 OSSL_DEPRECATEDIN_1_1_0 void ENGINE_setup_bsd_cryptodev(void); 834 #endif 835 #endif 836 837 #ifdef __cplusplus 838 } 839 #endif 840 #endif /* OPENSSL_NO_ENGINE */ 841 #endif /* OPENSSL_ENGINE_H */ 842