NAME

ENGINE_new, ENGINE_up_ref, ENGINE_free, ENGINE_set_destroy_function, ENGINE_get_destroy_function — create and destroy ENGINE objects

SYNOPSIS

#include <openssl/engine.h> ENGINE *
ENGINE_new(void); int
ENGINE_up_ref(ENGINE *e); int
ENGINE_free(ENGINE *e); typedef int
(*ENGINE_GEN_INT_FUNC_PTR)(ENGINE *e); int
ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f); ENGINE_GEN_INT_FUNC_PTR
ENGINE_get_destroy_function(const ENGINE *e);

DESCRIPTION

ENGINE objects can be used to provide alternative implementations of cryptographic algorithms, to support additional algorithms, to support cryptographic hardware, and to switch among alternative implementations of algorithms at run time. LibreSSL generally avoids engines and prefers providing cryptographic functionality in the crypto library itself. ENGINE_new() allocates and initializes an empty ENGINE object and sets its structural reference count to 1 and its functional reference count to 0. For more information about the functional reference count, see the ENGINE_init(3) manual page. Many functions increment the structural reference count by 1 when successful. Some of them, including ENGINE_get_first(3), ENGINE_get_last(3), ENGINE_get_next(3), ENGINE_get_prev(3), and ENGINE_by_id(3), do so because they return a structural reference to the user. Other functions, including ENGINE_add(3), ENGINE_init(3), ENGINE_get_cipher_engine(3), ENGINE_get_digest_engine(3), and the ENGINE_get_default_RSA(3) and ENGINE_set_default(3) families of functions do so when they store a structural reference internally. ENGINE_up_ref() explicitly increment the structural reference count by 1. ENGINE_free() decrements the structural reference count by 1, and if it reaches 0, the optional destroy_f previously installed with ENGINE_set_destroy_function() is called, if one is installed, and both the memory used internally by e and e itself are freed. If e is a NULL pointer, no action occurs. Many functions internally call the equivalent of ENGINE_free(). Some of them, including ENGINE_get_next(3) and ENGINE_get_prev(3), thus invalidate the structural reference passed in by the user. Other functions, including ENGINE_finish(3), ENGINE_remove(3), and the ENGINE_set_default(3) family of functions do so when an internally stored structural reference is no longer needed. ENGINE_set_destroy_function() installs a callback function that will be called by ENGINE_free(), but only when e actually gets destroyed, not when only its reference count gets decremented. The value returned from the destroy_f will be ignored.

RETURN VALUES

ENGINE_new() returns a structural reference to the new ENGINE object or NULL if an error occurs. ENGINE_up_ref() returns 0 if e is NULL and 1 otherwise. ENGINE_free() and ENGINE_set_destroy_function() always return 1. ENGINE_get_destroy_function() returns a function pointer to the callback, or NULL if none is installed.

SEE ALSO

crypto(3), ENGINE_add(3), ENGINE_ctrl(3), ENGINE_get_default_RSA(3), ENGINE_init(3), ENGINE_register_all_RSA(3), ENGINE_register_RSA(3), ENGINE_set_default(3), ENGINE_set_flags(3), ENGINE_set_RSA(3), ENGINE_unregister_RSA(3)

HISTORY

ENGINE_new() and ENGINE_free() first appeared in OpenSSL 0.9.7 and have been available since OpenBSD 2.9. ENGINE_set_destroy_function() and ENGINE_get_destroy_function() first appeared in OpenSSL 0.9.7 and have been available since OpenBSD 3.2. ENGINE_up_ref() first appeared in OpenSSL 0.9.7 and has been available since OpenBSD 3.4.