Imported OpenSSL 1.1.1a
This commit is contained in:
Steve Dower
252
doc/man3/OPENSSL_init_crypto.pod
Normal file
252
doc/man3/OPENSSL_init_crypto.pod
Normal file
@@ -0,0 +1,252 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
OPENSSL_INIT_new, OPENSSL_INIT_set_config_appname, OPENSSL_INIT_free,
|
||||
OPENSSL_init_crypto, OPENSSL_cleanup,
|
||||
OPENSSL_atexit, OPENSSL_thread_stop - OpenSSL
|
||||
initialisation and deinitialisation functions
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/crypto.h>
|
||||
|
||||
void OPENSSL_cleanup(void);
|
||||
int OPENSSL_init_crypto(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings);
|
||||
int OPENSSL_atexit(void (*handler)(void));
|
||||
void OPENSSL_thread_stop(void);
|
||||
|
||||
OPENSSL_INIT_SETTINGS *OPENSSL_INIT_new(void);
|
||||
int OPENSSL_INIT_set_config_appname(OPENSSL_INIT_SETTINGS *init,
|
||||
const char* name);
|
||||
void OPENSSL_INIT_free(OPENSSL_INIT_SETTINGS *init);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
During normal operation OpenSSL (libcrypto) will allocate various resources at
|
||||
start up that must, subsequently, be freed on close down of the library.
|
||||
Additionally some resources are allocated on a per thread basis (if the
|
||||
application is multi-threaded), and these resources must be freed prior to the
|
||||
thread closing.
|
||||
|
||||
As of version 1.1.0 OpenSSL will automatically allocate all resources that it
|
||||
needs so no explicit initialisation is required. Similarly it will also
|
||||
automatically deinitialise as required.
|
||||
|
||||
However, there way be situations when explicit initialisation is desirable or
|
||||
needed, for example when some non-default initialisation is required. The
|
||||
function OPENSSL_init_crypto() can be used for this purpose for
|
||||
libcrypto (see also L<OPENSSL_init_ssl(3)> for the libssl
|
||||
equivalent).
|
||||
|
||||
Numerous internal OpenSSL functions call OPENSSL_init_crypto().
|
||||
Therefore, in order to perform non-default initialisation,
|
||||
OPENSSL_init_crypto() MUST be called by application code prior to
|
||||
any other OpenSSL function calls.
|
||||
|
||||
The B<opts> parameter specifies which aspects of libcrypto should be
|
||||
initialised. Valid options are:
|
||||
|
||||
=over 4
|
||||
|
||||
=item OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS
|
||||
|
||||
Suppress automatic loading of the libcrypto error strings. This option is
|
||||
not a default option. Once selected subsequent calls to
|
||||
OPENSSL_init_crypto() with the option
|
||||
B<OPENSSL_INIT_LOAD_CRYPTO_STRINGS> will be ignored.
|
||||
|
||||
=item OPENSSL_INIT_LOAD_CRYPTO_STRINGS
|
||||
|
||||
Automatic loading of the libcrypto error strings. With this option the
|
||||
library will automatically load the libcrypto error strings.
|
||||
This option is a default option. Once selected subsequent calls to
|
||||
OPENSSL_init_crypto() with the option
|
||||
B<OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS> will be ignored.
|
||||
|
||||
=item OPENSSL_INIT_ADD_ALL_CIPHERS
|
||||
|
||||
With this option the library will automatically load and make available all
|
||||
libcrypto ciphers. This option is a default option. Once selected subsequent
|
||||
calls to OPENSSL_init_crypto() with the option
|
||||
B<OPENSSL_INIT_NO_ADD_ALL_CIPHERS> will be ignored.
|
||||
|
||||
=item OPENSSL_INIT_ADD_ALL_DIGESTS
|
||||
|
||||
With this option the library will automatically load and make available all
|
||||
libcrypto digests. This option is a default option. Once selected subsequent
|
||||
calls to OPENSSL_init_crypto() with the option
|
||||
B<OPENSSL_INIT_NO_ADD_ALL_CIPHERS> will be ignored.
|
||||
|
||||
=item OPENSSL_INIT_NO_ADD_ALL_CIPHERS
|
||||
|
||||
With this option the library will suppress automatic loading of libcrypto
|
||||
ciphers. This option is not a default option. Once selected subsequent
|
||||
calls to OPENSSL_init_crypto() with the option
|
||||
B<OPENSSL_INIT_ADD_ALL_CIPHERS> will be ignored.
|
||||
|
||||
=item OPENSSL_INIT_NO_ADD_ALL_DIGESTS
|
||||
|
||||
With this option the library will suppress automatic loading of libcrypto
|
||||
digests. This option is not a default option. Once selected subsequent
|
||||
calls to OPENSSL_init_crypto() with the option
|
||||
B<OPENSSL_INIT_ADD_ALL_DIGESTS> will be ignored.
|
||||
|
||||
=item OPENSSL_INIT_LOAD_CONFIG
|
||||
|
||||
With this option an OpenSSL configuration file will be automatically loaded and
|
||||
used by calling OPENSSL_config(). This is not a default option for libcrypto.
|
||||
From OpenSSL 1.1.1 this is a default option for libssl (see
|
||||
L<OPENSSL_init_ssl(3)> for further details about libssl initialisation). See the
|
||||
description of OPENSSL_INIT_new(), below.
|
||||
|
||||
=item OPENSSL_INIT_NO_LOAD_CONFIG
|
||||
|
||||
With this option the loading of OpenSSL configuration files will be suppressed.
|
||||
It is the equivalent of calling OPENSSL_no_config(). This is not a default
|
||||
option.
|
||||
|
||||
=item OPENSSL_INIT_ASYNC
|
||||
|
||||
With this option the library with automatically initialise the libcrypto async
|
||||
sub-library (see L<ASYNC_start_job(3)>). This is a default option.
|
||||
|
||||
=item OPENSSL_INIT_ENGINE_RDRAND
|
||||
|
||||
With this option the library will automatically load and initialise the
|
||||
RDRAND engine (if available). This not a default option.
|
||||
|
||||
=item OPENSSL_INIT_ENGINE_DYNAMIC
|
||||
|
||||
With this option the library will automatically load and initialise the
|
||||
dynamic engine. This not a default option.
|
||||
|
||||
=item OPENSSL_INIT_ENGINE_OPENSSL
|
||||
|
||||
With this option the library will automatically load and initialise the
|
||||
openssl engine. This not a default option.
|
||||
|
||||
=item OPENSSL_INIT_ENGINE_CRYPTODEV
|
||||
|
||||
With this option the library will automatically load and initialise the
|
||||
cryptodev engine (if available). This not a default option.
|
||||
|
||||
=item OPENSSL_INIT_ENGINE_CAPI
|
||||
|
||||
With this option the library will automatically load and initialise the
|
||||
CAPI engine (if available). This not a default option.
|
||||
|
||||
=item OPENSSL_INIT_ENGINE_PADLOCK
|
||||
|
||||
With this option the library will automatically load and initialise the
|
||||
padlock engine (if available). This not a default option.
|
||||
|
||||
=item OPENSSL_INIT_ENGINE_AFALG
|
||||
|
||||
With this option the library will automatically load and initialise the
|
||||
AFALG engine. This not a default option.
|
||||
|
||||
=item OPENSSL_INIT_ENGINE_ALL_BUILTIN
|
||||
|
||||
With this option the library will automatically load and initialise all the
|
||||
built in engines listed above with the exception of the openssl and afalg
|
||||
engines. This not a default option.
|
||||
|
||||
=item OPENSSL_INIT_ATFORK
|
||||
|
||||
With this option the library will register its fork handlers.
|
||||
See OPENSSL_fork_prepare(3) for details.
|
||||
|
||||
=back
|
||||
|
||||
Multiple options may be combined together in a single call to
|
||||
OPENSSL_init_crypto(). For example:
|
||||
|
||||
OPENSSL_init_crypto(OPENSSL_INIT_NO_ADD_ALL_CIPHERS
|
||||
| OPENSSL_INIT_NO_ADD_ALL_DIGESTS, NULL);
|
||||
|
||||
The OPENSSL_cleanup() function deinitialises OpenSSL (both libcrypto
|
||||
and libssl). All resources allocated by OpenSSL are freed. Typically there
|
||||
should be no need to call this function directly as it is initiated
|
||||
automatically on application exit. This is done via the standard C library
|
||||
atexit() function. In the event that the application will close in a manner
|
||||
that will not call the registered atexit() handlers then the application should
|
||||
call OPENSSL_cleanup() directly. Developers of libraries using OpenSSL
|
||||
are discouraged from calling this function and should instead, typically, rely
|
||||
on auto-deinitialisation. This is to avoid error conditions where both an
|
||||
application and a library it depends on both use OpenSSL, and the library
|
||||
deinitialises it before the application has finished using it.
|
||||
|
||||
Once OPENSSL_cleanup() has been called the library cannot be reinitialised.
|
||||
Attempts to call OPENSSL_init_crypto() will fail and an ERR_R_INIT_FAIL error
|
||||
will be added to the error stack. Note that because initialisation has failed
|
||||
OpenSSL error strings will not be available, only an error code. This code can
|
||||
be put through the openssl errstr command line application to produce a human
|
||||
readable error (see L<errstr(1)>).
|
||||
|
||||
The OPENSSL_atexit() function enables the registration of a
|
||||
function to be called during OPENSSL_cleanup(). Stop handlers are
|
||||
called after deinitialisation of resources local to a thread, but before other
|
||||
process wide resources are freed. In the event that multiple stop handlers are
|
||||
registered, no guarantees are made about the order of execution.
|
||||
|
||||
The OPENSSL_thread_stop() function deallocates resources associated
|
||||
with the current thread. Typically this function will be called automatically by
|
||||
the library when the thread exits. This should only be called directly if
|
||||
resources should be freed at an earlier time, or under the circumstances
|
||||
described in the NOTES section below.
|
||||
|
||||
The B<OPENSSL_INIT_LOAD_CONFIG> flag will load a default configuration
|
||||
file. For optional configuration file settings, an B<OPENSSL_INIT_SETTINGS>
|
||||
must be created and used.
|
||||
The routines OPENSSL_init_new() and OPENSSL_INIT_set_config_appname() can
|
||||
be used to allocate the object and set the application name, and then the
|
||||
object can be released with OPENSSL_INIT_free() when done.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
Resources local to a thread are deallocated automatically when the thread exits
|
||||
(e.g. in a pthreads environment, when pthread_exit() is called). On Windows
|
||||
platforms this is done in response to a DLL_THREAD_DETACH message being sent to
|
||||
the libcrypto32.dll entry point. Some windows functions may cause threads to exit
|
||||
without sending this message (for example ExitProcess()). If the application
|
||||
uses such functions, then the application must free up OpenSSL resources
|
||||
directly via a call to OPENSSL_thread_stop() on each thread. Similarly this
|
||||
message will also not be sent if OpenSSL is linked statically, and therefore
|
||||
applications using static linking should also call OPENSSL_thread_stop() on each
|
||||
thread. Additionally if OpenSSL is loaded dynamically via LoadLibrary() and the
|
||||
threads are not destroyed until after FreeLibrary() is called then each thread
|
||||
should call OPENSSL_thread_stop() prior to the FreeLibrary() call.
|
||||
|
||||
On Linux/Unix where OpenSSL has been loaded via dlopen() and the application is
|
||||
multi-threaded and if dlclose() is subsequently called prior to the threads
|
||||
being destroyed then OpenSSL will not be able to deallocate resources associated
|
||||
with those threads. The application should either call OPENSSL_thread_stop() on
|
||||
each thread prior to the dlclose() call, or alternatively the original dlopen()
|
||||
call should use the RTLD_NODELETE flag (where available on the platform).
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
The functions OPENSSL_init_crypto, OPENSSL_atexit() and
|
||||
OPENSSL_INIT_set_config_appname() return 1 on success or 0 on error.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<OPENSSL_init_ssl(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The OPENSSL_init_crypto(), OPENSSL_cleanup(), OPENSSL_atexit(),
|
||||
OPENSSL_thread_stop(), OPENSSL_INIT_new(), OPENSSL_INIT_set_config_appname()
|
||||
and OPENSSL_INIT_free() functions were added in OpenSSL 1.1.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
Licensed under the OpenSSL license (the "License"). You may not use
|
||||
this file except in compliance with the License. You can obtain a copy
|
||||
in the file LICENSE in the source distribution or at
|
||||
L<https://www.openssl.org/source/license.html>.
|
||||
|
||||
=cut
|
||||
Reference in New Issue
Block a user