From 8b75603cc0ce8f4d9deb7218fbd905d3fc73a4c0 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Tue, 9 Feb 2016 10:17:59 +0000 Subject: [PATCH] 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 --- INSTALL | 17 ++ INSTALL.WIN | 16 ++ .../OPENSSL_INIT_crypto_library_start.pod | 226 ++++++++++++++++++ doc/ssl/OPENSSL_INIT_ssl_library_start.pod | 78 ++++++ 4 files changed, 337 insertions(+) create mode 100644 doc/crypto/OPENSSL_INIT_crypto_library_start.pod create mode 100644 doc/ssl/OPENSSL_INIT_ssl_library_start.pod diff --git a/INSTALL b/INSTALL index f11d7cf22b..5bb720995f 100644 --- a/INSTALL +++ b/INSTALL @@ -51,6 +51,19 @@ --openssldir=DIR Directory for OpenSSL files. If no prefix is specified, the library files and binaries are also installed there. + no-autoalginit Don't automatically load all supported ciphers and digests. + Typically OpenSSL will make available all of its supported + ciphers and digests. For a statically linked application this + may be undesirable if small executable size is an objective. + This only affects libcrypto. Ciphers and digests will have to be + loaded manually using EVP_add_cipher() and EVP_add_digest() if + this option is used. + + no-autoerrinit Don't automatically load all libcrypto/libssl error strings. + Typically OpenSSL will automatically load human readable error + strings. For a statically linked application this may be + undesirable if small executable size is an objective. + no-threads Don't try to build with support for multi-threaded applications. @@ -327,6 +340,10 @@ you can still use "no-threads" to suppress an annoying warning message from the Configure script.) + OpenSSL provides in built support for two threading models: pthreads (found on + most UNIX/Linux systems), and Windows threads. No other threading models are + supported. If your platform does not provide pthreads or Windows threads then + you should Configure with the "no-threads" option. Note on shared libraries ------------------------ diff --git a/INSTALL.WIN b/INSTALL.WIN index d57923886c..ceb8d1ee39 100644 --- a/INSTALL.WIN +++ b/INSTALL.WIN @@ -190,3 +190,19 @@ your application code small "shim" snippet, which provides glue between OpenSSL BIO layer and your compiler run-time. See the OPENSSL_Applink manual page for further details. + + Support for older Windows platforms + ----------------------------------- + + By default OpenSSL will use functions and capabilities of the Windows platform + only available in Windows Vista, Windows Server 2008 or later. It is possible + to enable support for older platforms by defining _WIN32_WINNT at Configure + time. + + > perl Configure VC-WIN32 --prefix=c:\some\openssl\dir -D_WIN32_WINNT=0x0501 + + The value 0x0501 above corresponds to Windows XP which is the oldest supported + platform. The value 0x0600 corresponds to Windows Vista and Windows Server + 2008. Refer to the Windows documentation for other possible values. Note that + by forcing support for an older OpenSSL version this may mean less optimal + approaches are used instead. 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 -- 2.34.1