include/openssl/engine.h

70 #error ENGINE is disabled.
119  * internally to control registration of ENGINE implementations, and can be set
124 /* ENGINE flags that can be set by ENGINE_set_flags(). */
129  * control commands on behalf of the ENGINE using their "cmd_defns" data. */
133  * "ENGINE_by_id()". When an ENGINE must store state (eg. if ENGINE_ctrl()
136  * to obtain the ENGINE will result in it being copied into a new structure.
138  * the existing ENGINE's structural reference count. */
167  * same functionality to their own ENGINE-specific control functions that can be
170  * fact that application code can find and use them without requiring per-ENGINE
196  * including ENGINE-specific command types, return zero for an error.
198  * An ENGINE can choose to implement these ctrl functions, and can internally
201  * ENGINE_ctrl() code handles this on the ENGINE's behalf using the cmd_defns
202  * data (set using ENGINE_set_cmd_defns()). This means an ENGINE's ctrl()
206 /* Returns non-zero if the supplied ENGINE has a ctrl() handler. If "not", then
236 /* ENGINE implementations should start the numbering of their own control
241  * functionality is now available through ENGINE-specific control commands
256 /* If an ENGINE supports its own specific control commands and wishes the
275 typedef int (*ENGINE_GEN_INT_FUNC_PTR)(ENGINE *);
277 typedef int (*ENGINE_CTRL_FUNC_PTR)(ENGINE *, int, long, void *, void (*f)(void));
279 typedef EVP_PKEY * (*ENGINE_LOAD_KEY_PTR)(ENGINE *, const char *,
281 /* These callback types are for an ENGINE's handler for cipher and digest logic.
283  *   int foo(ENGINE *e, const EVP_CIPHER **cipher, const int **nids, int nid);
284  *   int foo(ENGINE *e, const EVP_MD **digest, const int **nids, int nid);
293 typedef int (*ENGINE_CIPHERS_PTR)(ENGINE *, const EVP_CIPHER **, const int **, int);
294 typedef int (*ENGINE_DIGESTS_PTR)(ENGINE *, const EVP_MD **, const int **, int);
296 /* STRUCTURE functions ... all of these functions deal with pointers to ENGINE
302  * decrement the structural reference count of the "current" ENGINE and
303  * increment the structural reference count of the ENGINE it returns (unless it
306 /* Get the first/last "ENGINE" type available. */
307 ENGINE *ENGINE_get_first(void);
308 ENGINE *ENGINE_get_last(void);
309 /* Iterate to the next/previous "ENGINE" type (NULL = end of the list). */
310 ENGINE *ENGINE_get_next(ENGINE *e);
311 ENGINE *ENGINE_get_prev(ENGINE *e);
312 /* Add another "ENGINE" type into the array. */
313 int ENGINE_add(ENGINE *e);
314 /* Remove an existing "ENGINE" type from the array. */
315 int ENGINE_remove(ENGINE *e);
317 ENGINE *ENGINE_by_id(const char *id);
351 int ENGINE_register_RSA(ENGINE *e);
352 void ENGINE_unregister_RSA(ENGINE *e);
355 int ENGINE_register_DSA(ENGINE *e);
356 void ENGINE_unregister_DSA(ENGINE *e);
359 int ENGINE_register_ECDH(ENGINE *e);
360 void ENGINE_unregister_ECDH(ENGINE *e);
363 int ENGINE_register_ECDSA(ENGINE *e);
364 void ENGINE_unregister_ECDSA(ENGINE *e);
367 int ENGINE_register_DH(ENGINE *e);
368 void ENGINE_unregister_DH(ENGINE *e);
371 int ENGINE_register_RAND(ENGINE *e);
372 void ENGINE_unregister_RAND(ENGINE *e);
375 int ENGINE_register_STORE(ENGINE *e);
376 void ENGINE_unregister_STORE(ENGINE *e);
379 int ENGINE_register_ciphers(ENGINE *e);
380 void ENGINE_unregister_ciphers(ENGINE *e);
383 int ENGINE_register_digests(ENGINE *e);
384 void ENGINE_unregister_digests(ENGINE *e);
391 int ENGINE_register_complete(ENGINE *e);
400  * operational ENGINE, and only use functional references in such situations. */
401 int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)(void));
403 /* This function tests if an ENGINE-specific command is usable as a "setting".
407 int ENGINE_cmd_is_executable(ENGINE *e, int cmd);
413 int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name,
416 /* This function passes a command-name and argument to an ENGINE. The cmd_name
418  * 'arg' as an argument (unless the ENGINE doesn't support such a command, in
421  * cmd_optional is non-zero, then if the ENGINE doesn't support the given
424  * engine-specific config data to the ENGINE at run-time to control behaviour of
431  * other words, vendors of 'ENGINE'-enabled devices should write ENGINE
433  * compliant ENGINE-based applications can work consistently with the same
434  * configuration for the same ENGINE-enabled devices, across applications. */
435 int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg,
438 /* These functions are useful for manufacturing new ENGINE structures. They
439  * don't address reference counting at all - one uses them to populate an ENGINE
441  * directly or adding it to the builtin ENGINE list in OpenSSL. These are also
442  * here so that the ENGINE structure doesn't have to be exposed and break binary
444 ENGINE *ENGINE_new(void);
445 int ENGINE_free(ENGINE *e);
446 int ENGINE_up_ref(ENGINE *e);
447 int ENGINE_set_id(ENGINE *e, const char *id);
448 int ENGINE_set_name(ENGINE *e, const char *name);
449 int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth);
450 int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth);
451 int ENGINE_set_ECDH(ENGINE *e, const ECDH_METHOD *ecdh_meth);
452 int ENGINE_set_ECDSA(ENGINE *e, const ECDSA_METHOD *ecdsa_meth);
453 int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth);
454 int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth);
455 int ENGINE_set_STORE(ENGINE *e, const STORE_METHOD *store_meth);
456 int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f);
457 int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f);
458 int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f);
459 int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f);
460 int ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f);
461 int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f);
462 int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f);
463 int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f);
464 int ENGINE_set_flags(ENGINE *e, int flags);
465 int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns);
466 /* These functions allow control over any per-structure ENGINE data. */
469 int ENGINE_set_ex_data(ENGINE *e, int idx, void *arg);
470 void *ENGINE_get_ex_data(const ENGINE *e, int idx);
478 /* These return values from within the ENGINE structure. These can be useful
482 const char *ENGINE_get_id(const ENGINE *e);
483 const char *ENGINE_get_name(const ENGINE *e);
484 const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e);
485 const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e);
486 const ECDH_METHOD *ENGINE_get_ECDH(const ENGINE *e);
487 const ECDSA_METHOD *ENGINE_get_ECDSA(const ENGINE *e);
488 const DH_METHOD *ENGINE_get_DH(const ENGINE *e);
489 const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e);
490 const STORE_METHOD *ENGINE_get_STORE(const ENGINE *e);
491 ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e);
492 ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e);
493 ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e);
494 ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e);
495 ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e);
496 ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e);
497 ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e);
498 ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e);
499 const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid);
500 const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid);
501 const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e);
502 int ENGINE_get_flags(const ENGINE *e);
504 /* FUNCTIONAL functions. These functions deal with ENGINE structures
511  * attached or not functioning correctly. Each ENGINE has 2 reference
519 int ENGINE_init(ENGINE *e);
523 int ENGINE_finish(ENGINE *e);
528 EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id,
530 EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id,
533 /* This returns a pointer for the current ENGINE structure that
537 ENGINE *ENGINE_get_default_RSA(void);
539 ENGINE *ENGINE_get_default_DSA(void);
540 ENGINE *ENGINE_get_default_ECDH(void);
541 ENGINE *ENGINE_get_default_ECDSA(void);
542 ENGINE *ENGINE_get_default_DH(void);
543 ENGINE *ENGINE_get_default_RAND(void);
546 ENGINE *ENGINE_get_cipher_engine(int nid);
547 ENGINE *ENGINE_get_digest_engine(int nid);
549 /* This sets a new default ENGINE structure for performing RSA
550  * operations. If the result is non-zero (success) then the ENGINE
553 int ENGINE_set_default_RSA(ENGINE *e);
554 int ENGINE_set_default_string(ENGINE *e, const char *def_list);
556 int ENGINE_set_default_DSA(ENGINE *e);
557 int ENGINE_set_default_ECDH(ENGINE *e);
558 int ENGINE_set_default_ECDSA(ENGINE *e);
559 int ENGINE_set_default_DH(ENGINE *e);
560 int ENGINE_set_default_RAND(ENGINE *e);
561 int ENGINE_set_default_ciphers(ENGINE *e);
562 int ENGINE_set_default_digests(ENGINE *e);
569 int ENGINE_set_default(ENGINE *e, unsigned int flags);
577 /* DYNAMIC ENGINE SUPPORT */
586 /* When compiling an ENGINE entirely as an external shared library, loadable by
587  * the "dynamic" ENGINE, these types are needed. The 'dynamic_fns' structure
644 /* This function is passed the ENGINE structure to initialise with its own
647  * be aborted, (b) the previous ENGINE state will be memcpy'd back onto the
650  * could leak. The 'id' parameter, if non-NULL, represents the ENGINE id that
652  * return failure or to initialise a 'default' ENGINE. If non-NULL, the shared
653  * library must initialise only an ENGINE matching the passed 'id'. The function
656  * the parameter 'fn' is a callback function that populates the ENGINE structure
658  *    [static] int fn(ENGINE *e, const char *id); */
659 typedef int (*dynamic_bind_engine)(ENGINE *e, const char *id,
663 	int bind_engine(ENGINE *e, const char *id, const dynamic_fns *fns) { \
680 /* If the loading application (or library) and the loaded ENGINE library share
684  * loaded ENGINE has (or gets from through the loader) its own copy of the
687  * and let the loading application and loaded ENGINE compare their respective
701 /* Error codes for the ENGINE functions. */