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.