Provide documentation for auto-init/auto-deinit

Provide some man pages for auto-init/deinit. Also update the INSTALL
documentation for information on the new Configure options implemented as
part of this.

Reviewed-by: Richard Levitte <levitte@openssl.org>

2 files changed, 304 insertions, 0 deletions

diff --git a/doc/crypto/OPENSSL_INIT_crypto_library_start.pod b/doc/crypto/OPENSSL_INIT_crypto_library_start.pod
new file mode 100644
index 0000000000..bea0e62f93
--- /dev/null
+++ b/doc/crypto/OPENSSL_INIT_crypto_library_start.pod
@@ -0,0 +1,226 @@
+=pod
+
+=head1 NAME
+
+OPENSSL_INIT_library_stop, OPENSSL_INIT_crypto_library_start,
+OPENSSL_INIT_register_stop_handler, OPENSSL_INIT_thread_stop - OpenSSL
+initialisation and deinitialisation functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/crypto.h>
+
+ void OPENSSL_INIT_library_stop(void);
+ void OPENSSL_INIT_crypto_library_start(uint64_t opts,
+                                        const OPENSSL_INIT_SETTINGS *settings);
+ int OPENSSL_INIT_register_stop_handler(void (*handler)(void));
+ void OPENSSL_INIT_thread_stop(void);
+
+=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_library_start() can be used for this purpose for
+libcrypto (see also L<OPENSSL_INIT_ssl_library_start(3)> for the libssl
+equivalent). In order to perform non-default initialisation it MUST be called
+prior to any other calls of this function. As numerous internal OpenSSL
+functions also call this, this usually means you should call it 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. With this option the
+library will not automatically call ERR_load_crypto_strings(). This option is
+not a default option. Once selected subsequent calls to
+OPENSSL_INIT_crypto_library_start() with the option
+B<OPENSSL_INIT_LOAD_CRYPTO_STRINGS> will be ignored. Applications may call
+ERR_load_crypto_strings() directly if they wish even if this option has been
+selected. If they do so then they must also explicitly call ERR_free_strings()
+on application close down.
+
+=item OPENSSL_INIT_LOAD_CRYPTO_STRINGS
+
+Automatic loading of the libcrypto error strings. With this option the
+library will automatically call ERR_load_crypto_strings(). This option is a
+default option. Once selected subsequent calls to
+OPENSSL_INIT_crypto_library_start() 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_library_start() 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_library_start() 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_library_start() 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_library_start() 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.
+
+=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_DASYNC
+
+With this option the library will automatically load and initialise the
+DASYNC 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 dasync
+engines. This not a default option.
+
+=back
+
+Multiple options may be combined together in a single call to
+OPENSSL_INIT_start_library(). For example:
+
+ OPENSSL_INIT_start_library(OPENSSL_INIT_NO_ADD_ALL_CIPHERS
+                            | OPENSSL_INIT_NO_ADD_ALL_DIGESTS, NULL);
+
+
+The B<settings> parameter to OPENSSL_INIT_start_library() may be used to
+provide optional settings values to an option. Currently the only option this
+applies to is OPENSSL_INIT_LOAD_CONFIG. This provides the optional
+OPENSSL_INIT_SET_CONF_FILENAME parameter to provide a filename to load
+configuration from. If no filename is provided then the system default
+configuration file is assumed. For example
+
+ const OPENSSL_INIT_SETTINGS settings[2] = {
+     { OPENSSL_INIT_SET_CONF_FILENAME, .value.type_string = "myconf.cnf" },
+     { OPENSSL_INIT_SET_END, .value.type_int = 0 }
+ };
+ OPENSSL_INIT_crypto_library_start(OPENSSL_INIT_LOAD_CONFIG,
+                                   (const OPENSSL_INIT_SETTINGS *)&settings);
+
+The B<settings> parameter must be an array of OPENSSL_INIT_SETTINGS values
+terminated with an OPENSSL_INIT_SET_END entry.
+
+The OPENSSL_INIT_library_stop() 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
+L<atexit(3)> 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_INIT_library_stop() 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.
+
+The OPENSSL_INIT_register_stop_handler() function enables the registration of a
+function to be called during OPENSSL_INIT_library_stop(). 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_INIT_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.
+
+=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 libeay32.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_INIT_thread_stop(). Similarly this message will
+also not be sent if OpenSSL is linked statically, and therefore applications
+using static linking should also call OPENSSL_INIT_thread_stop().
+
+=head1 RETURN VALUES
+
+The function OPENSSL_INIT_register_stop_handler() returns 1 on success or 0 on
+error.
+
+=head1 SEE ALSO
+
+L<OPENSSL_INIT_ssl_library_start(3)>
+
+=head1 HISTORY
+
+The OPENSSL_INIT_library_stop, OPENSSL_INIT_crypto_library_start,
+OPENSSL_INIT_register_stop_handler and OPENSSL_INIT_thread_stop functions were
+first added in OpenSSL 1.1.0.
+
+=cut
diff --git a/doc/ssl/OPENSSL_INIT_ssl_library_start.pod b/doc/ssl/OPENSSL_INIT_ssl_library_start.pod
new file mode 100644
index 0000000000..bcd39127f7
--- /dev/null
+++ b/doc/ssl/OPENSSL_INIT_ssl_library_start.pod
@@ -0,0 +1,78 @@
+=pod
+
+=head1 NAME
+
+OPENSSL_INIT_ssl_library_start - OpenSSL (libssl and libcrypto) initialisation
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void OPENSSL_INIT_ssl_library_start(uint64_t opts,
+                                     const OPENSSL_INIT_SETTINGS *settings);
+
+=head1 DESCRIPTION
+
+During normal operation OpenSSL (libssl and 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_ssl_library_start() can be used for this purpose. Calling
+this function will explicitly initialise BOTH libcrypto and libssl. To
+explicitly initialise ONLY libcrypto see the
+L<OPENSSL_INIT_crypto_library_start(3)> function. In order to perform
+non-default initialisation it MUST be called prior to any other calls of this
+function. As numerous internal OpenSSL functions also call this, this usually
+means you should call it prior to ANY other OpenSSL function calls.
+
+The B<opts> parameter specifies which aspects of libssl and libcrypto should be
+initialised. Valid options for libcrypto are described on the
+L<OPENSSL_INIT_crypto_library_start(3)> page. In addition to any libcrypto
+specific option the following libssl options can also be used:
+
+=over 4
+
+=item OPENSSL_INIT_NO_LOAD_SSL_STRINGS
+
+Suppress automatic loading of the libssl error strings. With this option the
+library will not automatically call ERR_load_SSL_strings(). This option is
+not a default option. Once selected subsequent calls to
+OPENSSL_INIT_ssl_library_start() with the option
+B<OPENSSL_INIT_LOAD_SSL_STRINGS> will be ignored. Applications may call
+ERR_load_SSL_strings() directly if they wish even if this option has been
+selected. If they do so then they must also explicitly call ERR_free_strings()
+on application close down.
+
+=item OPENSSL_INIT_LOAD_SSL_STRINGS
+
+Automatic loading of the libssl error strings. With this option the
+library will automatically call ERR_load_SSL_strings(). This option is a
+default option. Once selected subsequent calls to
+OPENSSL_INIT_ssl_library_start() with the option
+B<OPENSSL_INIT_LOAD_SSL_STRINGS> will be ignored.
+
+=back
+
+The B<settings> parameter specifies optional settings values to an option.
+Currently no such settings are available for libssl specific options. However
+these settings will also be passed internally to a call to
+L<OPENSSL_INIT_crypto_library_start(3)>, so this parameter can also be used to
+provide libcrypto settings values.
+
+=head1 SEE ALSO
+
+L<OPENSSL_INIT_crypto_library_start(3)>
+
+=head1 HISTORY
+
+The OPENSSL_INIT_ssl_library_start function was first added in OpenSSL 1.1.0.
+
+=cut