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.