From 8b75603cc0ce8f4d9deb7218fbd905d3fc73a4c0 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Tue, 9 Feb 2016 10:17:59 +0000 Subject: 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 --- doc/crypto/OPENSSL_INIT_crypto_library_start.pod | 226 +++++++++++++++++++++++ doc/ssl/OPENSSL_INIT_ssl_library_start.pod | 78 ++++++++ 2 files changed, 304 insertions(+) create mode 100644 doc/crypto/OPENSSL_INIT_crypto_library_start.pod create mode 100644 doc/ssl/OPENSSL_INIT_ssl_library_start.pod (limited to 'doc') 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 + + 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 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 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 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 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 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 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 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 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). 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 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 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 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 + +=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 + + 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 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 parameter specifies which aspects of libssl and libcrypto should be +initialised. Valid options for libcrypto are described on the +L 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 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 will be ignored. + +=back + +The B 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, so this parameter can also be used to +provide libcrypto settings values. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +The OPENSSL_INIT_ssl_library_start function was first added in OpenSSL 1.1.0. + +=cut -- cgit v1.2.3