NAME
ENGINE_add,
ENGINE_set_id,
ENGINE_get_id,
ENGINE_set_name,
ENGINE_get_name,
ENGINE_remove,
ENGINE_cleanup,
ENGINE_get_first,
ENGINE_get_last,
ENGINE_get_next,
ENGINE_get_prev,
ENGINE_by_id —
maintain a global list of ENGINE
objects
SYNOPSIS
#include
<openssl/engine.h>
int
ENGINE_add(ENGINE *e);
int
ENGINE_set_id(ENGINE *e,
const char *id);
const char *
ENGINE_get_id(const ENGINE
*e);
int
ENGINE_set_name(ENGINE *e,
const char *name);
const char *
ENGINE_get_name(const ENGINE
*e);
int
ENGINE_remove(ENGINE *e);
void
ENGINE_cleanup(void);
ENGINE *
ENGINE_get_first(void);
ENGINE *
ENGINE_get_last(void);
ENGINE *
ENGINE_get_next(ENGINE *e);
ENGINE *
ENGINE_get_prev(ENGINE *e);
ENGINE *
ENGINE_by_id(const char
*id);
DESCRIPTION
The crypto library maintains a global list of ENGINE objects.ENGINE_add()
appends e to the end of the list and increments its
structural reference count by 1. A unique identifier and a name of
e have to be set with
ENGINE_set_id()
and
ENGINE_set_name()
before calling this function. ENGINE_add() fails if
the list already contains an ENGINE with the same
identifier.
ENGINE_remove()
removes e from the list. If successful, it calls
ENGINE_free(3) on e.
ENGINE_cleanup()
calls
ENGINE_finish(3) on all ENGINE objects
that were selected as default engines, for example using the functions
documented in the
ENGINE_set_default(3) and
ENGINE_get_default_RSA(3) manual pages, and it calls
ENGINE_remove() on all ENGINE
objects that were added to the global list with
ENGINE_add(). Calling this function is required at
the end of each program using ENGINE_add(), even if
no engines are explicitly registered or used.
ENGINE_get_first()
and
ENGINE_get_last()
provide access to the first and last ENGINE object on
the list, respectively. Unless the list is empty, they increment the
structural reference count of the retrieved object by 1.
ENGINE_get_next()
and
ENGINE_get_prev()
support iteration of the list. They always call
ENGINE_free(3) on e. Unless the end of
the list is reached, they increment the structural reference count of the
retrieved object by 1.
ENGINE_by_id()
searches the list for an ENGINE object with a matching
id. If found, it increments the structural reference
count of the retrieved object by 1. If
ENGINE_FLAGS_BY_ID_COPY was set on
e with
ENGINE_set_flags(3), it returns a shallow copy of the object
rather than incrementing the reference count and returning a pointer to the
original.
RETURN VALUES
ENGINE_add(),
ENGINE_set_id(),
ENGINE_set_name(), and
ENGINE_remove() return 1 on success or 0 on error.
ENGINE_set_id() and
ENGINE_set_name() can only fail if the supplied
id or name is
NULL.
ENGINE_get_id() and
ENGINE_get_name() return a pointer to an internal
string representing the identifier and the name of e,
respectively.
ENGINE_get_first() and
ENGINE_get_last() return an
ENGINE object or NULL if the
list is empty.
ENGINE_get_next() and
ENGINE_get_prev() return an
ENGINE object or NULL when the
end of the list is reached.
ENGINE_by_id() returns an
ENGINE object or NULL if no
matching object is found.
SEE ALSO
ENGINE_get_default_RSA(3), ENGINE_init(3), ENGINE_new(3), ENGINE_register_all_RSA(3), ENGINE_register_RSA(3), ENGINE_set_default(3), ENGINE_set_flags(3), ENGINE_unregister_RSA(3)
HISTORY
ENGINE_add(),
ENGINE_set_id(),
ENGINE_get_id(),
ENGINE_set_name(),
ENGINE_get_name(),
ENGINE_remove(),
ENGINE_get_first(),
ENGINE_get_last(),
ENGINE_get_next(),
ENGINE_get_prev(), and
ENGINE_by_id() first appeared in OpenSSL 0.9.7 and
have been available since OpenBSD 2.9.
ENGINE_cleanup() first appeared in OpenSSL
0.9.7 and has been available since OpenBSD 3.2.