.\" $OpenBSD: OPENSSL_init_crypto.3,v 1.3 2018/03/23 23:18:17 schwarze Exp $
.\" 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: March 23 2018 $
.Dt OPENSSL_INIT_CRYPTO 3
.Os
.Sh NAME
.Nm OPENSSL_init_crypto
.Nd initialise the crypto library
.Sh SYNOPSIS
.In openssl/crypto.h
.Ft int
.Fo OPENSSL_init_crypto
.Fa "uint64_t options"
.Fa "const void *dummy"
.Fc
.Sh DESCRIPTION
If
.Fn OPENSSL_init_crypto
is called before any other crypto or ssl functions, the crypto
library is initialised by allocating various internal resources.
.Pp
The following
.Fa options
are supported:
.Bl -tag -width Ds
.It Dv OPENSSL_INIT_LOAD_CONFIG
At the end of the initialization, call
.Xr OPENSSL_config 3
with a
.Dv NULL
argument, loading the default configuration file.
.It Dv OPENSSL_INIT_NO_LOAD_CONFIG
Ignore any later calls to
.Xr OPENSSL_config 3 .
.El
.Pp
The other
.Fa options
flags defined by OpenSSL are all ignored by LibreSSL.
The
.Fa dummy
argument has no effect.
.Pp
Calling this function is almost never useful because it is internally
called with an
.Fa options
argument of 0 by those functions in the crypto and ssl libraries
that require it.
It is safest to assume that any function may do so.
.Pp
If this function is called more than once, none of the calls except
the first one have any effect.
.Sh RETURN VALUES
.Fn OPENSSL_init_crypto
is intended to return 1 on success or 0 on error.
.Sh SEE ALSO
.Xr CONF_modules_load_file 3 ,
.Xr OPENSSL_config 3 ,
.Xr OPENSSL_init_ssl 3 ,
.Xr OPENSSL_load_builtin_modules 3 ,
.Xr openssl.cnf 5
.Sh HISTORY
.Fn OPENSSL_init_crypto
first appeared in OpenSSL 1.1.0 and has been available since
.Ox 6.3 .
.Sh BUGS
.Fn OPENSSL_init_crypto
silently ignores almost all kinds of errors.
In particular, if memory allocation fails, initialisation is likely
to remain incomplete, the library may be in an inconsistent internal
state, but the return value will usually indicate success anyway.
There is no way for the application program to find out whether
library initialisation is actually complete, nor to get back to a
consistent state if it isn't.