NAME

ENGINE_get_default_RSA, ENGINE_get_default_DSA, ENGINE_get_default_ECDH, ENGINE_get_default_ECDSA, ENGINE_get_default_DH, ENGINE_get_default_RAND, ENGINE_get_cipher_engine, ENGINE_get_digest_engine, ENGINE_set_table_flags, ENGINE_get_table_flags — retrieve the default ENGINE for an algorithm

SYNOPSIS

#include <openssl/engine.h>

ENGINE *
ENGINE_get_default_RSA(void);

ENGINE *
ENGINE_get_default_DSA(void);

ENGINE *
ENGINE_get_default_ECDH(void);

ENGINE *
ENGINE_get_default_ECDSA(void);

ENGINE *
ENGINE_get_default_DH(void);

ENGINE *
ENGINE_get_default_RAND(void);

ENGINE *
ENGINE_get_cipher_engine(int nid);

ENGINE *
ENGINE_get_digest_engine(int nid);

void
ENGINE_set_table_flags(unsigned int flags);

unsigned int
ENGINE_get_table_flags(void);

DESCRIPTION

These functions retrieve the current default ENGINE implementing the respective algorithm.

If a default engine was previously selected, ENGINE_init(3) is called on it again and it is used. Otherwise, these functions inspect the engines registered with the functions documented in ENGINE_register_RSA(3) in the order of the table for the respective algorithm. If an inspected engine is already successfully initialized, ENGINE_init(3) is called on it again and it is used as the new default. Otherwise, unless the global flag ENGINE_TABLE_FLAG_NOINIT is set, ENGINE_init(3) is tried on it. If it succeeds, that engine is used as the new default. If it fails or if ENGINE_TABLE_FLAG_NOINIT is set, inspection continues with the next engine.

The global flag can be set by calling ENGINE_set_table_flags() with an argument of ENGINE_TABLE_FLAG_NOINIT or cleared by calling it with an argument of 0. By default, the flag is not set.

While all the other functions operate on exactly one algorithm, ENGINE_get_cipher_engine() and ENGINE_get_digest_engine() are special in so far as they can handle multiple algorithms, identified by the given nid. The default engine is remembered separately for each algorithm.

Application programs rarely need to call these functions because they are called automatically when needed, in particular from RSA_new(3), DSA_new(3), ECDH_set_method(), ECDH_compute_key(), ECDSA_set_method(3), ECDSA_do_sign_ex(3), ECDSA_do_verify(3), DH_new(3), EVP_CipherInit_ex(3), and EVP_DigestInit_ex(3).

RETURN VALUES

These functions return a functional reference to an ENGINE object or NULL on failure, in particular when no engine implementing the algorithm is available, when ENGINE_init(3) fails for all implementations, or when insufficient memory is available. Even when these functions fail, the application may still be able to use the algorithm in question because the built-in implementation is used in that case, if one is available.

ENGINE_get_table_flags() returns ENGINE_TABLE_FLAG_NOINIT if the global flag is set or 0 otherwise.

SEE ALSO

ENGINE_init(3), ENGINE_new(3), ENGINE_register_RSA(3), ENGINE_set_default(3)

HISTORY

ENGINE_get_default_RSA(), ENGINE_get_default_DSA(), ENGINE_get_default_DH(), and ENGINE_get_default_RAND() first appeared in OpenSSL 0.9.7 and have been available since OpenBSD 2.9.

ENGINE_get_cipher_engine(), ENGINE_get_digest_engine(), ENGINE_set_table_flags(), and ENGINE_get_table_flags() first appeared in OpenSSL 0.9.7 and have been available since OpenBSD 3.2.

ENGINE_get_default_ECDH() and ENGINE_get_default_ECDSA() first appeared in OpenSSL 0.9.8 and have been available since OpenBSD 4.5.