.\" $OpenBSD: ENGINE_get_default_RSA.3,v 1.2 2018/04/18 03:39:22 schwarze Exp $
.\" content checked up to:
.\" OpenSSL ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800
.\"
.\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: April 18 2018 $
.Dt ENGINE_GET_DEFAULT_RSA 3
.Os
.Sh NAME
.Nm ENGINE_get_default_RSA ,
.Nm ENGINE_get_default_DSA ,
.Nm ENGINE_get_default_ECDH ,
.Nm ENGINE_get_default_ECDSA ,
.Nm ENGINE_get_default_DH ,
.Nm ENGINE_get_default_RAND ,
.Nm ENGINE_get_cipher_engine ,
.Nm ENGINE_get_digest_engine ,
.Nm ENGINE_set_table_flags ,
.Nm ENGINE_get_table_flags
.Nd retrieve the default ENGINE for an algorithm
.Sh SYNOPSIS
.In openssl/engine.h
.Ft ENGINE *
.Fn ENGINE_get_default_RSA void
.Ft ENGINE *
.Fn ENGINE_get_default_DSA void
.Ft ENGINE *
.Fn ENGINE_get_default_ECDH void
.Ft ENGINE *
.Fn ENGINE_get_default_ECDSA void
.Ft ENGINE *
.Fn ENGINE_get_default_DH void
.Ft ENGINE *
.Fn ENGINE_get_default_RAND void
.Ft ENGINE *
.Fo ENGINE_get_cipher_engine
.Fa "int nid"
.Fc
.Ft ENGINE *
.Fo ENGINE_get_digest_engine
.Fa "int nid"
.Fc
.Ft void
.Fo ENGINE_set_table_flags
.Fa "unsigned int flags"
.Fc
.Ft unsigned int
.Fn ENGINE_get_table_flags void
.Sh DESCRIPTION
These functions retrieve the current default
.Vt ENGINE
implementing the respective algorithm.
.Pp
If a default engine was previously selected,
.Xr ENGINE_init 3
is called on it again and it is used.
Otherwise, these functions inspect the engines registered
with the functions documented in
.Xr ENGINE_register_RSA 3
in the order of the table for the respective algorithm.
If an inspected engine is already successfully initialized,
.Xr ENGINE_init 3
is called on it again and it is used as the new default.
Otherwise, unless the global flag
.Dv ENGINE_TABLE_FLAG_NOINIT
is set,
.Xr ENGINE_init 3
is tried on it.
If it succeeds, that engine is used as the new default.
If it fails or if
.Dv ENGINE_TABLE_FLAG_NOINIT
is set, inspection continues with the next engine.
.Pp
The global flag can be set by calling
.Fn ENGINE_set_table_flags
with an argument of
.Dv ENGINE_TABLE_FLAG_NOINIT
or cleared by calling it with an argument of 0.
By default, the flag is not set.
.Pp
While all the other functions operate on exactly one algorithm,
.Fn ENGINE_get_cipher_engine
and
.Fn ENGINE_get_digest_engine
are special in so far as they can handle multiple algorithms,
identified by the given
.Fa nid .
The default engine is remembered separately for each algorithm.
.Pp
Application programs rarely need to call these functions because
they are called automatically when needed, in particular from
.Xr RSA_new 3 ,
.Xr DSA_new 3 ,
.Fn ECDH_set_method ,
.Fn ECDH_compute_key ,
.Xr ECDSA_set_method 3 ,
.Xr ECDSA_do_sign_ex 3 ,
.Xr ECDSA_do_verify 3 ,
.Xr DH_new 3 ,
.Xr EVP_CipherInit_ex 3 ,
and
.Xr EVP_DigestInit_ex 3 .
.Sh RETURN VALUES
These functions return a functional reference to an
.Vt ENGINE
object or
.Dv NULL
on failure, in particular when no engine implementing the algorithm
is available, when
.Xr 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.
.Pp
.Fn ENGINE_get_table_flags
returns
.Dv ENGINE_TABLE_FLAG_NOINIT
if the global flag is set or 0 otherwise.
.Sh SEE ALSO
.Xr ENGINE_init 3 ,
.Xr ENGINE_new 3 ,
.Xr ENGINE_register_RSA 3 ,
.Xr ENGINE_set_default 3
.Sh HISTORY
.Fn ENGINE_get_default_RSA ,
.Fn ENGINE_get_default_DSA ,
.Fn ENGINE_get_default_DH ,
and
.Fn ENGINE_get_default_RAND
first appeared in OpenSSL 0.9.7 and have been available since
.Ox 2.9 .
.Pp
.Fn ENGINE_get_cipher_engine ,
.Fn ENGINE_get_digest_engine ,
.Fn ENGINE_set_table_flags ,
and
.Fn ENGINE_get_table_flags
first appeared in OpenSSL 0.9.7 and have been available since
.Ox 3.2 .
.Pp
.Fn ENGINE_get_default_ECDH
and
.Fn ENGINE_get_default_ECDSA
first appeared in OpenSSL 0.9.8 and have been available since
.Ox 4.5 .