OpenBSD manual page server

NAME

ENGINE_set_RSA, ENGINE_get_RSA, ENGINE_set_DSA, ENGINE_get_DSA, ENGINE_set_ECDH, ENGINE_get_ECDH, ENGINE_set_ECDSA, ENGINE_get_ECDSA, ENGINE_set_DH, ENGINE_get_DH, ENGINE_set_RAND, ENGINE_get_RAND, ENGINE_set_STORE, ENGINE_get_STORE, ENGINE_set_ciphers, ENGINE_get_ciphers, ENGINE_get_cipher, ENGINE_set_digests, ENGINE_get_digests, ENGINE_get_digest — install and retrieve function tables of crypto engines

SYNOPSIS

#include <openssl/engine.h>

int
ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth);

const RSA_METHOD *
ENGINE_get_RSA(const ENGINE *e);

int
ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth);

const DSA_METHOD *
ENGINE_get_DSA(const ENGINE *e);

int
ENGINE_set_ECDH(ENGINE *e, const ECDH_METHOD *dh_meth);

const ECDH_METHOD *
ENGINE_get_ECDH(const ENGINE *e);

int
ENGINE_set_ECDSA(ENGINE *e, const ECDSA_METHOD *dh_meth);

const ECDSA_METHOD *
ENGINE_get_ECDSA(const ENGINE *e);

int
ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth);

const DH_METHOD *
ENGINE_get_DH(const ENGINE *e);

int
ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth);

const RAND_METHOD *
ENGINE_get_RAND(const ENGINE *e);

int
ENGINE_set_STORE(ENGINE *e, const STORE_METHOD *rand_meth);

const STORE_METHOD *
ENGINE_get_STORE(const ENGINE *e);

typedef int
(*ENGINE_CIPHERS_PTR)(ENGINE *e, const EVP_CIPHER **impl, const int **nids, int nid);

int
ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f);

ENGINE_CIPHERS_PTR
ENGINE_get_ciphers(const ENGINE *e);

const EVP_CIPHER *
ENGINE_get_cipher(ENGINE *e, int nid);

typedef int
(*ENGINE_DIGESTS_PTR)(ENGINE *e, const EVP_MD **impl, const int **nids, int nid);

int
ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f);

ENGINE_DIGESTS_PTR
ENGINE_get_digests(const ENGINE *e);

const EVP_MD *
ENGINE_get_digest(ENGINE *e, int nid);

DESCRIPTION

The ENGINE_set_*() functions install a table of function pointers implementing the respective algorithm in e. Partial information about the various method objects is available from RSA_meth_new(3), RSA_get_default_method(3), DSA_meth_new(3), DSA_get_default_method(3), ECDH_get_default_method(), ECDSA_get_default_method(3), DH_get_default_method(3), RAND_get_rand_method(3), EVP_get_cipherbynid(3), and EVP_get_digestbynid(3). STORE_METHOD is an incomplete type, and the pointers to it are not used for anything. For complete descriptions of these types, refer to the respective header files.

The functions described in the ENGINE_register_RSA(3) and ENGINE_set_default(3) manual pages only have an effect after function pointers were installed using the functions described here.

ENGINE_set_ciphers() and ENGINE_set_digests() are special in so far as the ENGINE structure does not provide fields to store function pointers implementing ciphers or digests. Instead, these two functions only install a callback to retrieve implementations. Where the pointers to the implementations are stored internally, how they get initialized, and how the ENGINE_CIPHERS_PTR and ENGINE_DIGESTS_PTR callbacks retrieve them is up to the implementation of each individual engine.

If the ENGINE_CIPHERS_PTR and ENGINE_DIGESTS_PTR callbacks are called with a non-zero nid, they retrieve the implementation of that cipher or digest, respectively. In this case, a NULL pointer can be passed as the nids argument. ENGINE_get_cipher() and ENGINE_get_digest() call the callbacks installed in e in this way.

If 0 is passed as the nid argument, an internal pointer to the array of implementations available in e is returned in *impl, and an internal pointer to the array of corresponding identifiers in *nids. The return value of the callback indicates the number of implementations returned.

The ENGINE_get_*() functions retrieve the previously installed function tables. They are used when constructing basic cryptographic objects as shown in the following table:

RETURN VALUES

The ENGINE_set_*() functions return 1 on success or 0 on error. Currently, they cannot fail.

The ENGINE_get_*() functions return a method object for the respective algorithm, or NULL if none is installed.

ENGINE_get_ciphers() and ENGINE_get_digests() return a function pointer to the respective callback, or NULL if none is installed.

ENGINE_get_cipher() returns an EVP_CIPHER object implementing the cipher nid or NULL if e does not implement that cipher.

ENGINE_get_digest() returns an EVP_MD object implementing the digest nid or NULL if e does not implement that digest.

SEE ALSO

ENGINE_ctrl(3), ENGINE_new(3), ENGINE_register_RSA(3), ENGINE_set_default(3), ENGINE_set_flags(3)

HISTORY

ENGINE_set_RSA(), ENGINE_get_RSA(), ENGINE_set_DSA(), ENGINE_get_DSA(), ENGINE_set_DH(), ENGINE_get_DH(), ENGINE_set_RAND(), ENGINE_get_RAND(), first appeared in OpenSSL 0.9.7 and have been available since OpenBSD 2.9.

ENGINE_set_ciphers(), ENGINE_get_ciphers(), ENGINE_get_cipher(), ENGINE_set_digests(), ENGINE_get_digests(), and ENGINE_get_digest() first appeared in OpenSSL 0.9.7 and have been available since OpenBSD 3.2.

ENGINE_set_ECDH(), ENGINE_get_ECDH(), ENGINE_set_ECDSA(), ENGINE_get_ECDSA(), ENGINE_set_STORE(), and ENGINE_get_STORE() first appeared in OpenSSL 0.9.8 and have been available since OpenBSD 4.5.