1=pod 2 3=head1 NAME 4 5ENGINE_get_DH, ENGINE_get_DSA, 6ENGINE_by_id, ENGINE_get_cipher_engine, ENGINE_get_default_DH, 7ENGINE_get_default_DSA, 8ENGINE_get_default_RAND, 9ENGINE_get_default_RSA, ENGINE_get_digest_engine, ENGINE_get_first, 10ENGINE_get_last, ENGINE_get_next, ENGINE_get_prev, ENGINE_new, 11ENGINE_get_ciphers, ENGINE_get_ctrl_function, ENGINE_get_digests, 12ENGINE_get_destroy_function, ENGINE_get_finish_function, 13ENGINE_get_init_function, ENGINE_get_load_privkey_function, 14ENGINE_get_load_pubkey_function, ENGINE_load_private_key, 15ENGINE_load_public_key, ENGINE_get_RAND, ENGINE_get_RSA, ENGINE_get_id, 16ENGINE_get_name, ENGINE_get_cmd_defns, ENGINE_get_cipher, 17ENGINE_get_digest, ENGINE_add, ENGINE_cmd_is_executable, 18ENGINE_ctrl, ENGINE_ctrl_cmd, ENGINE_ctrl_cmd_string, 19ENGINE_finish, ENGINE_free, ENGINE_get_flags, ENGINE_init, 20ENGINE_register_DH, ENGINE_register_DSA, 21ENGINE_register_RAND, ENGINE_register_RSA, 22ENGINE_register_all_complete, ENGINE_register_ciphers, 23ENGINE_register_complete, ENGINE_register_digests, ENGINE_remove, 24ENGINE_set_DH, ENGINE_set_DSA, 25ENGINE_set_RAND, ENGINE_set_RSA, ENGINE_set_ciphers, 26ENGINE_set_cmd_defns, ENGINE_set_ctrl_function, ENGINE_set_default, 27ENGINE_set_default_DH, ENGINE_set_default_DSA, 28ENGINE_set_default_RAND, ENGINE_set_default_RSA, 29ENGINE_set_default_ciphers, ENGINE_set_default_digests, 30ENGINE_set_default_string, ENGINE_set_destroy_function, 31ENGINE_set_digests, ENGINE_set_finish_function, ENGINE_set_flags, 32ENGINE_set_id, ENGINE_set_init_function, ENGINE_set_load_privkey_function, 33ENGINE_set_load_pubkey_function, ENGINE_set_name, ENGINE_up_ref, 34ENGINE_get_table_flags, ENGINE_cleanup, 35ENGINE_load_builtin_engines, ENGINE_register_all_DH, 36ENGINE_register_all_DSA, 37ENGINE_register_all_RAND, 38ENGINE_register_all_RSA, ENGINE_register_all_ciphers, 39ENGINE_register_all_digests, ENGINE_set_table_flags, ENGINE_unregister_DH, 40ENGINE_unregister_DSA, 41ENGINE_unregister_RAND, ENGINE_unregister_RSA, ENGINE_unregister_ciphers, 42ENGINE_unregister_digests 43- ENGINE cryptographic module support 44 45=head1 SYNOPSIS 46 47 #include <openssl/engine.h> 48 49The following functions have been deprecated since OpenSSL 3.0, and can be 50hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, 51see L<openssl_user_macros(7)>: 52 53 ENGINE *ENGINE_get_first(void); 54 ENGINE *ENGINE_get_last(void); 55 ENGINE *ENGINE_get_next(ENGINE *e); 56 ENGINE *ENGINE_get_prev(ENGINE *e); 57 58 int ENGINE_add(ENGINE *e); 59 int ENGINE_remove(ENGINE *e); 60 61 ENGINE *ENGINE_by_id(const char *id); 62 63 int ENGINE_init(ENGINE *e); 64 int ENGINE_finish(ENGINE *e); 65 66 void ENGINE_load_builtin_engines(void); 67 68 ENGINE *ENGINE_get_default_RSA(void); 69 ENGINE *ENGINE_get_default_DSA(void); 70 ENGINE *ENGINE_get_default_DH(void); 71 ENGINE *ENGINE_get_default_RAND(void); 72 ENGINE *ENGINE_get_cipher_engine(int nid); 73 ENGINE *ENGINE_get_digest_engine(int nid); 74 75 int ENGINE_set_default_RSA(ENGINE *e); 76 int ENGINE_set_default_DSA(ENGINE *e); 77 int ENGINE_set_default_DH(ENGINE *e); 78 int ENGINE_set_default_RAND(ENGINE *e); 79 int ENGINE_set_default_ciphers(ENGINE *e); 80 int ENGINE_set_default_digests(ENGINE *e); 81 int ENGINE_set_default_string(ENGINE *e, const char *list); 82 83 int ENGINE_set_default(ENGINE *e, unsigned int flags); 84 85 unsigned int ENGINE_get_table_flags(void); 86 void ENGINE_set_table_flags(unsigned int flags); 87 88 int ENGINE_register_RSA(ENGINE *e); 89 void ENGINE_unregister_RSA(ENGINE *e); 90 void ENGINE_register_all_RSA(void); 91 int ENGINE_register_DSA(ENGINE *e); 92 void ENGINE_unregister_DSA(ENGINE *e); 93 void ENGINE_register_all_DSA(void); 94 int ENGINE_register_DH(ENGINE *e); 95 void ENGINE_unregister_DH(ENGINE *e); 96 void ENGINE_register_all_DH(void); 97 int ENGINE_register_RAND(ENGINE *e); 98 void ENGINE_unregister_RAND(ENGINE *e); 99 void ENGINE_register_all_RAND(void); 100 int ENGINE_register_ciphers(ENGINE *e); 101 void ENGINE_unregister_ciphers(ENGINE *e); 102 void ENGINE_register_all_ciphers(void); 103 int ENGINE_register_digests(ENGINE *e); 104 void ENGINE_unregister_digests(ENGINE *e); 105 void ENGINE_register_all_digests(void); 106 int ENGINE_register_complete(ENGINE *e); 107 int ENGINE_register_all_complete(void); 108 109 int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)(void)); 110 int ENGINE_cmd_is_executable(ENGINE *e, int cmd); 111 int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name, 112 long i, void *p, void (*f)(void), int cmd_optional); 113 int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg, 114 int cmd_optional); 115 116 ENGINE *ENGINE_new(void); 117 int ENGINE_free(ENGINE *e); 118 int ENGINE_up_ref(ENGINE *e); 119 120 int ENGINE_set_id(ENGINE *e, const char *id); 121 int ENGINE_set_name(ENGINE *e, const char *name); 122 int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth); 123 int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth); 124 int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth); 125 int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth); 126 int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f); 127 int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f); 128 int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f); 129 int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f); 130 int ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f); 131 int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f); 132 int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f); 133 int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f); 134 int ENGINE_set_flags(ENGINE *e, int flags); 135 int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns); 136 137 const char *ENGINE_get_id(const ENGINE *e); 138 const char *ENGINE_get_name(const ENGINE *e); 139 const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e); 140 const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e); 141 const DH_METHOD *ENGINE_get_DH(const ENGINE *e); 142 const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e); 143 ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e); 144 ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e); 145 ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e); 146 ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e); 147 ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e); 148 ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e); 149 ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e); 150 ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e); 151 const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid); 152 const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid); 153 int ENGINE_get_flags(const ENGINE *e); 154 const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e); 155 156 EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id, 157 UI_METHOD *ui_method, void *callback_data); 158 EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id, 159 UI_METHOD *ui_method, void *callback_data); 160 161The following function has been deprecated since OpenSSL 1.1.0, and can be 162hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, 163see L<openssl_user_macros(7)>: 164 165 void ENGINE_cleanup(void); 166 167=head1 DESCRIPTION 168 169All of the functions described on this page are deprecated. 170Applications should instead use the provider APIs. 171 172These functions create, manipulate, and use cryptographic modules in the 173form of B<ENGINE> objects. These objects act as containers for 174implementations of cryptographic algorithms, and support a 175reference-counted mechanism to allow them to be dynamically loaded in and 176out of the running application. 177 178The cryptographic functionality that can be provided by an B<ENGINE> 179implementation includes the following abstractions; 180 181 RSA_METHOD - for providing alternative RSA implementations 182 DSA_METHOD, DH_METHOD, RAND_METHOD, ECDH_METHOD, ECDSA_METHOD, 183 - similarly for other OpenSSL APIs 184 EVP_CIPHER - potentially multiple cipher algorithms (indexed by 'nid') 185 EVP_DIGEST - potentially multiple hash algorithms (indexed by 'nid') 186 key-loading - loading public and/or private EVP_PKEY keys 187 188=head2 Reference counting and handles 189 190Due to the modular nature of the ENGINE API, pointers to ENGINEs need to be 191treated as handles - i.e. not only as pointers, but also as references to 192the underlying ENGINE object. Ie. one should obtain a new reference when 193making copies of an ENGINE pointer if the copies will be used (and 194released) independently. 195 196ENGINE objects have two levels of reference-counting to match the way in 197which the objects are used. At the most basic level, each ENGINE pointer is 198inherently a B<structural> reference - a structural reference is required 199to use the pointer value at all, as this kind of reference is a guarantee 200that the structure can not be deallocated until the reference is released. 201 202However, a structural reference provides no guarantee that the ENGINE is 203initialised and able to use any of its cryptographic 204implementations. Indeed it's quite possible that most ENGINEs will not 205initialise at all in typical environments, as ENGINEs are typically used to 206support specialised hardware. To use an ENGINE's functionality, you need a 207B<functional> reference. This kind of reference can be considered a 208specialised form of structural reference, because each functional reference 209implicitly contains a structural reference as well - however to avoid 210difficult-to-find programming bugs, it is recommended to treat the two 211kinds of reference independently. If you have a functional reference to an 212ENGINE, you have a guarantee that the ENGINE has been initialised and 213is ready to perform cryptographic operations, and will remain initialised 214until after you have released your reference. 215 216I<Structural references> 217 218This basic type of reference is used for instantiating new ENGINEs, 219iterating across OpenSSL's internal linked-list of loaded 220ENGINEs, reading information about an ENGINE, etc. Essentially a structural 221reference is sufficient if you only need to query or manipulate the data of 222an ENGINE implementation rather than use its functionality. 223 224The ENGINE_new() function returns a structural reference to a new (empty) 225ENGINE object. There are other ENGINE API functions that return structural 226references such as; ENGINE_by_id(), ENGINE_get_first(), ENGINE_get_last(), 227ENGINE_get_next(), ENGINE_get_prev(). All structural references should be 228released by a corresponding to call to the ENGINE_free() function - the 229ENGINE object itself will only actually be cleaned up and deallocated when 230the last structural reference is released. 231 232It should also be noted that many ENGINE API function calls that accept a 233structural reference will internally obtain another reference - typically 234this happens whenever the supplied ENGINE will be needed by OpenSSL after 235the function has returned. Eg. the function to add a new ENGINE to 236OpenSSL's internal list is ENGINE_add() - if this function returns success, 237then OpenSSL will have stored a new structural reference internally so the 238caller is still responsible for freeing their own reference with 239ENGINE_free() when they are finished with it. In a similar way, some 240functions will automatically release the structural reference passed to it 241if part of the function's job is to do so. Eg. the ENGINE_get_next() and 242ENGINE_get_prev() functions are used for iterating across the internal 243ENGINE list - they will return a new structural reference to the next (or 244previous) ENGINE in the list or NULL if at the end (or beginning) of the 245list, but in either case the structural reference passed to the function is 246released on behalf of the caller. 247 248To clarify a particular function's handling of references, one should 249always consult that function's documentation "man" page, or failing that 250the F<< <openssl/engine.h> >> header file includes some hints. 251 252I<Functional references> 253 254As mentioned, functional references exist when the cryptographic 255functionality of an ENGINE is required to be available. A functional 256reference can be obtained in one of two ways; from an existing structural 257reference to the required ENGINE, or by asking OpenSSL for the default 258operational ENGINE for a given cryptographic purpose. 259 260To obtain a functional reference from an existing structural reference, 261call the ENGINE_init() function. This returns zero if the ENGINE was not 262already operational and couldn't be successfully initialised (e.g. lack of 263system drivers, no special hardware attached, etc), otherwise it will 264return nonzero to indicate that the ENGINE is now operational and will 265have allocated a new B<functional> reference to the ENGINE. All functional 266references are released by calling ENGINE_finish() (which removes the 267implicit structural reference as well). 268 269The second way to get a functional reference is by asking OpenSSL for a 270default implementation for a given task, e.g. by ENGINE_get_default_RSA(), 271ENGINE_get_default_cipher_engine(), etc. These are discussed in the next 272section, though they are not usually required by application programmers as 273they are used automatically when creating and using the relevant 274algorithm-specific types in OpenSSL, such as RSA, DSA, EVP_CIPHER_CTX, etc. 275 276=head2 Default implementations 277 278For each supported abstraction, the ENGINE code maintains an internal table 279of state to control which implementations are available for a given 280abstraction and which should be used by default. These implementations are 281registered in the tables and indexed by an 'nid' value, because 282abstractions like EVP_CIPHER and EVP_DIGEST support many distinct 283algorithms and modes, and ENGINEs can support arbitrarily many of them. 284In the case of other abstractions like RSA, DSA, etc, there is only one 285"algorithm" so all implementations implicitly register using the same 'nid' 286index. 287 288When a default ENGINE is requested for a given abstraction/algorithm/mode, (e.g. 289when calling RSA_new_method(NULL)), a "get_default" call will be made to the 290ENGINE subsystem to process the corresponding state table and return a 291functional reference to an initialised ENGINE whose implementation should be 292used. If no ENGINE should (or can) be used, it will return NULL and the caller 293will operate with a NULL ENGINE handle - this usually equates to using the 294conventional software implementation. In the latter case, OpenSSL will from 295then on behave the way it used to before the ENGINE API existed. 296 297Each state table has a flag to note whether it has processed this 298"get_default" query since the table was last modified, because to process 299this question it must iterate across all the registered ENGINEs in the 300table trying to initialise each of them in turn, in case one of them is 301operational. If it returns a functional reference to an ENGINE, it will 302also cache another reference to speed up processing future queries (without 303needing to iterate across the table). Likewise, it will cache a NULL 304response if no ENGINE was available so that future queries won't repeat the 305same iteration unless the state table changes. This behaviour can also be 306changed; if the ENGINE_TABLE_FLAG_NOINIT flag is set (using 307ENGINE_set_table_flags()), no attempted initialisations will take place, 308instead the only way for the state table to return a non-NULL ENGINE to the 309"get_default" query will be if one is expressly set in the table. Eg. 310ENGINE_set_default_RSA() does the same job as ENGINE_register_RSA() except 311that it also sets the state table's cached response for the "get_default" 312query. In the case of abstractions like EVP_CIPHER, where implementations are 313indexed by 'nid', these flags and cached-responses are distinct for each 'nid' 314value. 315 316=head2 Application requirements 317 318This section will explain the basic things an application programmer should 319support to make the most useful elements of the ENGINE functionality 320available to the user. The first thing to consider is whether the 321programmer wishes to make alternative ENGINE modules available to the 322application and user. OpenSSL maintains an internal linked list of 323"visible" ENGINEs from which it has to operate - at start-up, this list is 324empty and in fact if an application does not call any ENGINE API calls and 325it uses static linking against openssl, then the resulting application 326binary will not contain any alternative ENGINE code at all. So the first 327consideration is whether any/all available ENGINE implementations should be 328made visible to OpenSSL - this is controlled by calling the various "load" 329functions. 330 331The fact that ENGINEs are made visible to OpenSSL (and thus are linked into 332the program and loaded into memory at run-time) does not mean they are 333"registered" or called into use by OpenSSL automatically - that behaviour 334is something for the application to control. Some applications 335will want to allow the user to specify exactly which ENGINE they want used 336if any is to be used at all. Others may prefer to load all support and have 337OpenSSL automatically use at run-time any ENGINE that is able to 338successfully initialise - i.e. to assume that this corresponds to 339acceleration hardware attached to the machine or some such thing. There are 340probably numerous other ways in which applications may prefer to handle 341things, so we will simply illustrate the consequences as they apply to a 342couple of simple cases and leave developers to consider these and the 343source code to openssl's built-in utilities as guides. 344 345If no ENGINE API functions are called within an application, then OpenSSL 346will not allocate any internal resources. Prior to OpenSSL 1.1.0, however, 347if any ENGINEs are loaded, even if not registered or used, it was necessary to 348call ENGINE_cleanup() before the program exits. 349 350I<Using a specific ENGINE implementation> 351 352Here we'll assume an application has been configured by its user or admin 353to want to use the "ACME" ENGINE if it is available in the version of 354OpenSSL the application was compiled with. If it is available, it should be 355used by default for all RSA, DSA, and symmetric cipher operations, otherwise 356OpenSSL should use its built-in software as per usual. The following code 357illustrates how to approach this; 358 359 ENGINE *e; 360 const char *engine_id = "ACME"; 361 ENGINE_load_builtin_engines(); 362 e = ENGINE_by_id(engine_id); 363 if (!e) 364 /* the engine isn't available */ 365 return; 366 if (!ENGINE_init(e)) { 367 /* the engine couldn't initialise, release 'e' */ 368 ENGINE_free(e); 369 return; 370 } 371 if (!ENGINE_set_default_RSA(e)) 372 /* 373 * This should only happen when 'e' can't initialise, but the previous 374 * statement suggests it did. 375 */ 376 abort(); 377 ENGINE_set_default_DSA(e); 378 ENGINE_set_default_ciphers(e); 379 /* Release the functional reference from ENGINE_init() */ 380 ENGINE_finish(e); 381 /* Release the structural reference from ENGINE_by_id() */ 382 ENGINE_free(e); 383 384I<Automatically using built-in ENGINE implementations> 385 386Here we'll assume we want to load and register all ENGINE implementations 387bundled with OpenSSL, such that for any cryptographic algorithm required by 388OpenSSL - if there is an ENGINE that implements it and can be initialised, 389it should be used. The following code illustrates how this can work; 390 391 /* Load all bundled ENGINEs into memory and make them visible */ 392 ENGINE_load_builtin_engines(); 393 /* Register all of them for every algorithm they collectively implement */ 394 ENGINE_register_all_complete(); 395 396That's all that's required. Eg. the next time OpenSSL tries to set up an 397RSA key, any bundled ENGINEs that implement RSA_METHOD will be passed to 398ENGINE_init() and if any of those succeed, that ENGINE will be set as the 399default for RSA use from then on. 400 401=head2 Advanced configuration support 402 403There is a mechanism supported by the ENGINE framework that allows each 404ENGINE implementation to define an arbitrary set of configuration 405"commands" and expose them to OpenSSL and any applications based on 406OpenSSL. This mechanism is entirely based on the use of name-value pairs 407and assumes ASCII input (no unicode or UTF for now!), so it is ideal if 408applications want to provide a transparent way for users to provide 409arbitrary configuration "directives" directly to such ENGINEs. It is also 410possible for the application to dynamically interrogate the loaded ENGINE 411implementations for the names, descriptions, and input flags of their 412available "control commands", providing a more flexible configuration 413scheme. However, if the user is expected to know which ENGINE device he/she 414is using (in the case of specialised hardware, this goes without saying) 415then applications may not need to concern themselves with discovering the 416supported control commands and simply prefer to pass settings into ENGINEs 417exactly as they are provided by the user. 418 419Before illustrating how control commands work, it is worth mentioning what 420they are typically used for. Broadly speaking there are two uses for 421control commands; the first is to provide the necessary details to the 422implementation (which may know nothing at all specific to the host system) 423so that it can be initialised for use. This could include the path to any 424driver or config files it needs to load, required network addresses, 425smart-card identifiers, passwords to initialise protected devices, 426logging information, etc etc. This class of commands typically needs to be 427passed to an ENGINE B<before> attempting to initialise it, i.e. before 428calling ENGINE_init(). The other class of commands consist of settings or 429operations that tweak certain behaviour or cause certain operations to take 430place, and these commands may work either before or after ENGINE_init(), or 431in some cases both. ENGINE implementations should provide indications of 432this in the descriptions attached to built-in control commands and/or in 433external product documentation. 434 435I<Issuing control commands to an ENGINE> 436 437Let's illustrate by example; a function for which the caller supplies the 438name of the ENGINE it wishes to use, a table of string-pairs for use before 439initialisation, and another table for use after initialisation. Note that 440the string-pairs used for control commands consist of a command "name" 441followed by the command "parameter" - the parameter could be NULL in some 442cases but the name can not. This function should initialise the ENGINE 443(issuing the "pre" commands beforehand and the "post" commands afterwards) 444and set it as the default for everything except RAND and then return a 445boolean success or failure. 446 447 int generic_load_engine_fn(const char *engine_id, 448 const char **pre_cmds, int pre_num, 449 const char **post_cmds, int post_num) 450 { 451 ENGINE *e = ENGINE_by_id(engine_id); 452 if (!e) return 0; 453 while (pre_num--) { 454 if (!ENGINE_ctrl_cmd_string(e, pre_cmds[0], pre_cmds[1], 0)) { 455 fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id, 456 pre_cmds[0], pre_cmds[1] ? pre_cmds[1] : "(NULL)"); 457 ENGINE_free(e); 458 return 0; 459 } 460 pre_cmds += 2; 461 } 462 if (!ENGINE_init(e)) { 463 fprintf(stderr, "Failed initialisation\n"); 464 ENGINE_free(e); 465 return 0; 466 } 467 /* 468 * ENGINE_init() returned a functional reference, so free the structural 469 * reference from ENGINE_by_id(). 470 */ 471 ENGINE_free(e); 472 while (post_num--) { 473 if (!ENGINE_ctrl_cmd_string(e, post_cmds[0], post_cmds[1], 0)) { 474 fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id, 475 post_cmds[0], post_cmds[1] ? post_cmds[1] : "(NULL)"); 476 ENGINE_finish(e); 477 return 0; 478 } 479 post_cmds += 2; 480 } 481 ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND); 482 /* Success */ 483 return 1; 484 } 485 486Note that ENGINE_ctrl_cmd_string() accepts a boolean argument that can 487relax the semantics of the function - if set nonzero it will only return 488failure if the ENGINE supported the given command name but failed while 489executing it, if the ENGINE doesn't support the command name it will simply 490return success without doing anything. In this case we assume the user is 491only supplying commands specific to the given ENGINE so we set this to 492FALSE. 493 494I<Discovering supported control commands> 495 496It is possible to discover at run-time the names, numerical-ids, descriptions 497and input parameters of the control commands supported by an ENGINE using a 498structural reference. Note that some control commands are defined by OpenSSL 499itself and it will intercept and handle these control commands on behalf of the 500ENGINE, i.e. the ENGINE's ctrl() handler is not used for the control command. 501F<< <openssl/engine.h> >> defines an index, ENGINE_CMD_BASE, that all control 502commands implemented by ENGINEs should be numbered from. Any command value 503lower than this symbol is considered a "generic" command is handled directly 504by the OpenSSL core routines. 505 506It is using these "core" control commands that one can discover the control 507commands implemented by a given ENGINE, specifically the commands: 508 509 ENGINE_HAS_CTRL_FUNCTION 510 ENGINE_CTRL_GET_FIRST_CMD_TYPE 511 ENGINE_CTRL_GET_NEXT_CMD_TYPE 512 ENGINE_CTRL_GET_CMD_FROM_NAME 513 ENGINE_CTRL_GET_NAME_LEN_FROM_CMD 514 ENGINE_CTRL_GET_NAME_FROM_CMD 515 ENGINE_CTRL_GET_DESC_LEN_FROM_CMD 516 ENGINE_CTRL_GET_DESC_FROM_CMD 517 ENGINE_CTRL_GET_CMD_FLAGS 518 519Whilst these commands are automatically processed by the OpenSSL framework code, 520they use various properties exposed by each ENGINE to process these 521queries. An ENGINE has 3 properties it exposes that can affect how this behaves; 522it can supply a ctrl() handler, it can specify ENGINE_FLAGS_MANUAL_CMD_CTRL in 523the ENGINE's flags, and it can expose an array of control command descriptions. 524If an ENGINE specifies the ENGINE_FLAGS_MANUAL_CMD_CTRL flag, then it will 525simply pass all these "core" control commands directly to the ENGINE's ctrl() 526handler (and thus, it must have supplied one), so it is up to the ENGINE to 527reply to these "discovery" commands itself. If that flag is not set, then the 528OpenSSL framework code will work with the following rules: 529 530 if no ctrl() handler supplied; 531 ENGINE_HAS_CTRL_FUNCTION returns FALSE (zero), 532 all other commands fail. 533 if a ctrl() handler was supplied but no array of control commands; 534 ENGINE_HAS_CTRL_FUNCTION returns TRUE, 535 all other commands fail. 536 if a ctrl() handler and array of control commands was supplied; 537 ENGINE_HAS_CTRL_FUNCTION returns TRUE, 538 all other commands proceed processing ... 539 540If the ENGINE's array of control commands is empty then all other commands will 541fail, otherwise; ENGINE_CTRL_GET_FIRST_CMD_TYPE returns the identifier of 542the first command supported by the ENGINE, ENGINE_GET_NEXT_CMD_TYPE takes the 543identifier of a command supported by the ENGINE and returns the next command 544identifier or fails if there are no more, ENGINE_CMD_FROM_NAME takes a string 545name for a command and returns the corresponding identifier or fails if no such 546command name exists, and the remaining commands take a command identifier and 547return properties of the corresponding commands. All except 548ENGINE_CTRL_GET_FLAGS return the string length of a command name or description, 549or populate a supplied character buffer with a copy of the command name or 550description. ENGINE_CTRL_GET_FLAGS returns a bitwise-OR'd mask of the following 551possible values: 552 553 ENGINE_CMD_FLAG_NUMERIC 554 ENGINE_CMD_FLAG_STRING 555 ENGINE_CMD_FLAG_NO_INPUT 556 ENGINE_CMD_FLAG_INTERNAL 557 558If the ENGINE_CMD_FLAG_INTERNAL flag is set, then any other flags are purely 559informational to the caller - this flag will prevent the command being usable 560for any higher-level ENGINE functions such as ENGINE_ctrl_cmd_string(). 561"INTERNAL" commands are not intended to be exposed to text-based configuration 562by applications, administrations, users, etc. These can support arbitrary 563operations via ENGINE_ctrl(), including passing to and/or from the control 564commands data of any arbitrary type. These commands are supported in the 565discovery mechanisms simply to allow applications to determine if an ENGINE 566supports certain specific commands it might want to use (e.g. application "foo" 567might query various ENGINEs to see if they implement "FOO_GET_VENDOR_LOGO_GIF" - 568and ENGINE could therefore decide whether or not to support this "foo"-specific 569extension). 570 571=head1 ENVIRONMENT 572 573=over 4 574 575=item B<OPENSSL_ENGINES> 576 577The path to the engines directory. 578Ignored in set-user-ID and set-group-ID programs. 579 580=back 581 582=head1 RETURN VALUES 583 584ENGINE_get_first(), ENGINE_get_last(), ENGINE_get_next() and ENGINE_get_prev() 585return a valid B<ENGINE> structure or NULL if an error occurred. 586 587ENGINE_add() and ENGINE_remove() return 1 on success or 0 on error. 588 589ENGINE_by_id() returns a valid B<ENGINE> structure or NULL if an error occurred. 590 591ENGINE_init() and ENGINE_finish() return 1 on success or 0 on error. 592 593All ENGINE_get_default_TYPE() functions, ENGINE_get_cipher_engine() and 594ENGINE_get_digest_engine() return a valid B<ENGINE> structure on success or NULL 595if an error occurred. 596 597All ENGINE_set_default_TYPE() functions return 1 on success or 0 on error. 598 599ENGINE_set_default() returns 1 on success or 0 on error. 600 601ENGINE_get_table_flags() returns an unsigned integer value representing the 602global table flags which are used to control the registration behaviour of 603B<ENGINE> implementations. 604 605All ENGINE_register_TYPE() functions return 1 on success or 0 on error. 606 607ENGINE_register_complete() and ENGINE_register_all_complete() always return 1. 608 609ENGINE_ctrl() returns a positive value on success or others on error. 610 611ENGINE_cmd_is_executable() returns 1 if B<cmd> is executable or 0 otherwise. 612 613ENGINE_ctrl_cmd() and ENGINE_ctrl_cmd_string() return 1 on success or 0 on error. 614 615ENGINE_new() returns a valid B<ENGINE> structure on success or NULL if an error 616occurred. 617 618ENGINE_free() always returns 1. 619 620ENGINE_up_ref() returns 1 on success or 0 on error. 621 622ENGINE_set_id() and ENGINE_set_name() return 1 on success or 0 on error. 623 624All other B<ENGINE_set_*> functions return 1 on success or 0 on error. 625 626ENGINE_get_id() and ENGINE_get_name() return a string representing the identifier 627and the name of the ENGINE B<e> respectively. 628 629ENGINE_get_RSA(), ENGINE_get_DSA(), ENGINE_get_DH() and ENGINE_get_RAND() 630return corresponding method structures for each algorithms. 631 632ENGINE_get_destroy_function(), ENGINE_get_init_function(), 633ENGINE_get_finish_function(), ENGINE_get_ctrl_function(), 634ENGINE_get_load_privkey_function(), ENGINE_get_load_pubkey_function(), 635ENGINE_get_ciphers() and ENGINE_get_digests() return corresponding function 636pointers of the callbacks. 637 638ENGINE_get_cipher() returns a valid B<EVP_CIPHER> structure on success or NULL 639if an error occurred. 640 641ENGINE_get_digest() returns a valid B<EVP_MD> structure on success or NULL if an 642error occurred. 643 644ENGINE_get_flags() returns an integer representing the ENGINE flags which are 645used to control various behaviours of an ENGINE. 646 647ENGINE_get_cmd_defns() returns an B<ENGINE_CMD_DEFN> structure or NULL if it's 648not set. 649 650ENGINE_load_private_key() and ENGINE_load_public_key() return a valid B<EVP_PKEY> 651structure on success or NULL if an error occurred. 652 653=head1 SEE ALSO 654 655L<OPENSSL_init_crypto(3)>, L<RSA_new_method(3)>, L<DSA_new(3)>, L<DH_new(3)>, 656L<RAND_bytes(3)>, L<config(5)> 657 658=head1 HISTORY 659 660All of these functions were deprecated in OpenSSL 3.0. 661 662ENGINE_cleanup() was deprecated in OpenSSL 1.1.0 by the automatic cleanup 663done by OPENSSL_cleanup() 664and should not be used. 665 666=head1 COPYRIGHT 667 668Copyright 2002-2021 The OpenSSL Project Authors. All Rights Reserved. 669 670Licensed under the Apache License 2.0 (the "License"). You may not use 671this file except in compliance with the License. You can obtain a copy 672in the file LICENSE in the source distribution or at 673L<https://www.openssl.org/source/license.html>. 674 675=cut 676
