|ENGINE_NEW(3)||Library Functions Manual||ENGINE_NEW(3)|
create and destroy ENGINE objects
*e, ENGINE_GEN_INT_FUNC_PTR destroy_f);
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 refence 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
NULL pointer, no action occurs.
Many functions internally call the equivalent of
ENGINE_free(). Some of them, including
invalidate the structural reference passed in by the user. Other functions,
ENGINE_remove(3), and the
of functions do so when an internally stored structural reference is no
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
ENGINE_new() returns a structural
reference to the new ENGINE object or
NULL if an error occurs.
ENGINE_up_ref() returns 0 if
NULL and 1 otherwise.
ENGINE_set_destroy_function() always return 1.
ENGINE_get_destroy_function() returns a
function pointer to the callback, or
NULL if none is
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)
ENGINE_free() first appeared in OpenSSL 0.9.7 and
have been available since OpenBSD 2.9.
ENGINE_get_destroy_function() first appeared in
OpenSSL 0.9.7 and have been available since OpenBSD
ENGINE_up_ref() first appeared in OpenSSL
0.9.7 and has been available since OpenBSD 3.4.
|June 10, 2019||OpenBSD-current|