From 1c6dd887ec8f9d6b87ce2f220e839fbe1b78db67 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Fri, 14 Jun 2019 13:41:31 +0000 Subject: Further improve the documentation of library initialization and configuration. Among other improvements: * Use a uniform wording at the top of the DECSRIPTION for obsolete pages. * Better explain how to use a non-standard configuration file. * Remove obsolete functions from SEE ALSO. Triggered by some suggestions from tb@. Tweaks and OK tb@. --- src/lib/libcrypto/man/CONF_modules_load_file.3 | 32 ++++++++++++++++---- src/lib/libcrypto/man/ERR_load_crypto_strings.3 | 29 ++++-------------- src/lib/libcrypto/man/OPENSSL_config.3 | 25 +++++++++------- src/lib/libcrypto/man/OPENSSL_init_crypto.3 | 34 +++++++++++++++------- .../libcrypto/man/OPENSSL_load_builtin_modules.3 | 12 +++++--- src/lib/libcrypto/man/OpenSSL_add_all_algorithms.3 | 14 ++++++--- src/lib/libssl/man/OPENSSL_init_ssl.3 | 30 ++++++++++++++----- src/lib/libssl/man/SSL_library_init.3 | 32 +++++++------------- src/lib/libssl/man/ssl.3 | 12 ++++---- 9 files changed, 126 insertions(+), 94 deletions(-) (limited to 'src') diff --git a/src/lib/libcrypto/man/CONF_modules_load_file.3 b/src/lib/libcrypto/man/CONF_modules_load_file.3 index d0401d520b..972752f7a3 100644 --- a/src/lib/libcrypto/man/CONF_modules_load_file.3 +++ b/src/lib/libcrypto/man/CONF_modules_load_file.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: CONF_modules_load_file.3,v 1.8 2019/03/20 04:02:07 schwarze Exp $ +.\" $OpenBSD: CONF_modules_load_file.3,v 1.9 2019/06/14 13:41:31 schwarze Exp $ .\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 .\" .\" This file was written by Dr. Stephen Henson . @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: March 20 2019 $ +.Dd $Mdocdate: June 14 2019 $ .Dt CONF_MODULES_LOAD_FILE 3 .Os .Sh NAME @@ -95,6 +95,13 @@ is used. The behaviour can be customized using .Fa flags . .Pp +See the +.Sx EXAMPLES +section for additional functions that may need to be called. +Calling configuration functions in the right order for the intended +effect can be tricky because many configuration functions internally +call each other. +.Pp .Fn CONF_modules_load is identical to .Fn CONF_modules_load_file @@ -180,9 +187,12 @@ if (CONF_modules_load_file(NULL, "myapp", } .Ed .Pp -Load custom configuration file and section, only print warnings on -error, missing configuration file ignored: +Load custom configuration file and section instead of the standard one, +only print warnings on error, missing configuration file ignored: .Bd -literal +OPENSSL_no_config(); +ENGINE_load_builtin_engines(); +OPENSSL_load_builtin_modules(); if (CONF_modules_load_file("/something/app.cnf", "myapp", CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) { fprintf(stderr, "WARNING: error loading configuration file\en"); @@ -190,6 +200,17 @@ if (CONF_modules_load_file("/something/app.cnf", "myapp", } .Ed .Pp +In the previous example, the call to +.Xr OPENSSL_no_config 3 +is required first to suppress automatic loading +of the standard configuration file, and the calls to +.Xr ENGINE_load_builtin_engines 3 +and +.Xr OPENSSL_load_builtin_modules 3 +are needed so that the configuration of builtin modules and engines +is also loaded in addition to the configuration of +.Qq myapp . +.Pp Load and parse configuration file manually, custom error handling: .Bd -literal FILE *fp; @@ -218,9 +239,10 @@ if (fp == NULL) { .Ed .Sh SEE ALSO .Xr CONF_modules_free 3 , +.Xr ENGINE_load_builtin_engines 3 , .Xr ERR 3 , .Xr OPENSSL_config 3 , -.Xr OPENSSL_init_crypto 3 +.Xr OPENSSL_load_builtin_modules 3 .Sh HISTORY .Fn CONF_modules_load_file and diff --git a/src/lib/libcrypto/man/ERR_load_crypto_strings.3 b/src/lib/libcrypto/man/ERR_load_crypto_strings.3 index 5421781bcc..e3d60527d7 100644 --- a/src/lib/libcrypto/man/ERR_load_crypto_strings.3 +++ b/src/lib/libcrypto/man/ERR_load_crypto_strings.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ERR_load_crypto_strings.3,v 1.7 2018/03/27 17:35:50 schwarze Exp $ +.\" $OpenBSD: ERR_load_crypto_strings.3,v 1.8 2019/06/14 13:41:31 schwarze Exp $ .\" OpenSSL a528d4f0 Oct 27 13:40:11 2015 -0400 .\" .\" This file is a derived work. @@ -65,13 +65,12 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: March 27 2018 $ +.Dd $Mdocdate: June 14 2019 $ .Dt ERR_LOAD_CRYPTO_STRINGS 3 .Os .Sh NAME .Nm ERR_load_crypto_strings , .Nm ERR_free_strings , -.Nm ERR_load_BN_strings , .Nm SSL_load_error_strings .Nd load and free OpenSSL error strings .Sh SYNOPSIS @@ -80,13 +79,14 @@ .Fn ERR_load_crypto_strings void .Ft void .Fn ERR_free_strings void -.In openssl/bn.h -.Ft void -.Fn ERR_load_BN_strings void .In openssl/ssl.h .Ft void .Fn SSL_load_error_strings void .Sh DESCRIPTION +These functions are deprecated. +It is never useful for any application program to call any of them explicitly. +The library automatically calls them internally whenever needed. +.Pp .Fn ERR_load_crypto_strings registers the error strings for all .Xr crypto 3 @@ -96,23 +96,8 @@ does the same, but also registers the .Xr ssl 3 error strings. .Pp -.Fn ERR_load_BN_strings -only registers the error strings for the -.Vt BIGNUM -part of the library, i.e. the functions documented in -.Xr BN_new 3 -and in the manual pages referenced from there. -That may be useful if no other parts of the crypto library -are used by the program. -Similar functions exist for other parts of the crypto library, -but they are not yet documented. -.Pp If the error strings were already loaded before, no action occurs. .Pp -One of these functions should be called before generating textual error -messages. -However, this is not required when memory usage is an issue. -.Pp .Fn ERR_free_strings frees all previously loaded error strings. .Sh SEE ALSO @@ -124,8 +109,6 @@ and .Fn SSL_load_error_strings first appeared in SSLeay 0.4.4. .Fn ERR_free_strings -and -.Fn ERR_load_BN_strings first appeared in SSLeay 0.5.1. These functions been available since .Ox 2.4 . diff --git a/src/lib/libcrypto/man/OPENSSL_config.3 b/src/lib/libcrypto/man/OPENSSL_config.3 index e74f697dc4..2960e2389a 100644 --- a/src/lib/libcrypto/man/OPENSSL_config.3 +++ b/src/lib/libcrypto/man/OPENSSL_config.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: OPENSSL_config.3,v 1.14 2019/06/10 09:49:48 schwarze Exp $ +.\" $OpenBSD: OPENSSL_config.3,v 1.15 2019/06/14 13:41:31 schwarze Exp $ .\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 .\" .\" This file is a derived work. @@ -65,7 +65,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: June 10 2019 $ +.Dd $Mdocdate: June 14 2019 $ .Dt OPENSSL_CONFIG 3 .Os .Sh NAME @@ -82,12 +82,7 @@ .Fn OPENSSL_no_config void .Sh DESCRIPTION .Fn OPENSSL_config -initializes the crypto library with -.Xr OPENSSL_init_crypto 3 -and then calls -.Xr OPENSSL_load_builtin_modules 3 , -.Xr ENGINE_load_builtin_engines 3 , -and +initializes the crypto library and calls .Xr CONF_modules_load_file 3 with the standard configuration file and the given .Fa appname . @@ -104,7 +99,7 @@ Further calls to have no effect. .Pp .Fn OPENSSL_no_config -suppresses the loading of any configuration file, so that any +suppresses the loading of the standard configuration file, so that any future calls to .Fn OPENSSL_config or to @@ -116,6 +111,17 @@ Calling these functions is optional. All required initialization of the crypto libraries happens automatically when needed. .Pp +To use a non-standard configuration file, refer to +.Xr CONF_modules_load_file 3 . +.Pp +Internally, +.Fn OPENSSL_config +calls +.Xr OPENSSL_init_crypto 3 , +.Xr OPENSSL_load_builtin_modules 3 , +and +.Xr ENGINE_load_builtin_engines 3 . +.Pp If an application is compiled with the preprocessor symbol .Dv OPENSSL_LOAD_CONF #define'd, @@ -135,7 +141,6 @@ standard configuration file .Xr CONF_modules_free 3 , .Xr CONF_modules_load_file 3 , .Xr crypto 3 , -.Xr OPENSSL_init_crypto 3 , .Xr OPENSSL_load_builtin_modules 3 , .Xr OPENSSL_VERSION_NUMBER 3 , .Xr openssl.cnf 5 , diff --git a/src/lib/libcrypto/man/OPENSSL_init_crypto.3 b/src/lib/libcrypto/man/OPENSSL_init_crypto.3 index 3a532550ae..e6dac13fed 100644 --- a/src/lib/libcrypto/man/OPENSSL_init_crypto.3 +++ b/src/lib/libcrypto/man/OPENSSL_init_crypto.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: OPENSSL_init_crypto.3,v 1.3 2018/03/23 23:18:17 schwarze Exp $ +.\" $OpenBSD: OPENSSL_init_crypto.3,v 1.4 2019/06/14 13:41:31 schwarze Exp $ .\" Copyright (c) 2018 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -13,7 +13,7 @@ .\" 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 $ +.Dd $Mdocdate: June 14 2019 $ .Dt OPENSSL_INIT_CRYPTO 3 .Os .Sh NAME @@ -27,10 +27,30 @@ .Fa "const void *dummy" .Fc .Sh DESCRIPTION +This function is deprecated. +It is never useful for any application program to call it explicitly. +The library automatically calls it internally with an +.Fa options +argument of 0 whenever needed. +It is safest to assume that any function may do so. +.Pp +To enable or disable the standard configuration file, instead use +.Xr OPENSSL_config 3 +or +.Xr OPENSSL_no_config 3 , +respectively. +To load a non-standard configuration file, refer to +.Xr CONF_modules_load_file 3 . +.Pp If .Fn OPENSSL_init_crypto is called before any other crypto or ssl functions, the crypto -library is initialised by allocating various internal resources. +library is initialised by allocating various internal resources, +in particular calling +.Xr ERR_load_crypto_strings 3 , +.Xr OpenSSL_add_all_ciphers 3 , +and +.Xr OpenSSL_add_all_digests 3 . .Pp The following .Fa options @@ -54,13 +74,6 @@ 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 @@ -69,7 +82,6 @@ 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 diff --git a/src/lib/libcrypto/man/OPENSSL_load_builtin_modules.3 b/src/lib/libcrypto/man/OPENSSL_load_builtin_modules.3 index fd9e656bce..bcfb363ca4 100644 --- a/src/lib/libcrypto/man/OPENSSL_load_builtin_modules.3 +++ b/src/lib/libcrypto/man/OPENSSL_load_builtin_modules.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: OPENSSL_load_builtin_modules.3,v 1.5 2018/03/22 21:08:22 schwarze Exp $ +.\" $OpenBSD: OPENSSL_load_builtin_modules.3,v 1.6 2019/06/14 13:41:31 schwarze Exp $ .\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 .\" .\" This file was written by Dr. Stephen Henson . @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: March 22 2018 $ +.Dd $Mdocdate: June 14 2019 $ .Dt OPENSSL_LOAD_BUILTIN_MODULES 3 .Os .Sh NAME @@ -83,19 +83,23 @@ is called then .Fn OPENSSL_load_builtin_modules is called automatically. .Pp -Applications which use the configuration functions directly will need to -call +Applications which use configuration functions like +.Xr CONF_modules_load_file 3 +directly need to call .Fn OPENSSL_load_builtin_modules themselves .Em before any other configuration code. .Pp Applications should call +.Xr OPENSSL_config 3 +or .Fn OPENSSL_load_builtin_modules to load all configuration modules instead of adding modules selectively: otherwise functionality may be missing from the application when new modules are added. .Sh SEE ALSO +.Xr CONF_modules_load_file 3 , .Xr OPENSSL_config 3 .Sh HISTORY These functions first appeared in OpenSSL 0.9.7 diff --git a/src/lib/libcrypto/man/OpenSSL_add_all_algorithms.3 b/src/lib/libcrypto/man/OpenSSL_add_all_algorithms.3 index aa884d8eff..9ef19e7163 100644 --- a/src/lib/libcrypto/man/OpenSSL_add_all_algorithms.3 +++ b/src/lib/libcrypto/man/OpenSSL_add_all_algorithms.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: OpenSSL_add_all_algorithms.3,v 1.7 2018/03/27 17:35:50 schwarze Exp $ +.\" $OpenBSD: OpenSSL_add_all_algorithms.3,v 1.8 2019/06/14 13:41:31 schwarze Exp $ .\" full merge up to: OpenSSL b3696a55 Sep 2 09:35:50 2017 -0400 .\" .\" This file was written by Dr. Stephen Henson . @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: March 27 2018 $ +.Dd $Mdocdate: June 14 2019 $ .Dt OPENSSL_ADD_ALL_ALGORITHMS 3 .Os .Sh NAME @@ -79,6 +79,13 @@ It uses this table to look up ciphers via functions such as .Pp .Fn OpenSSL_add_all_algorithms adds all algorithms to the table (digests and ciphers). +If an application is compiled with the preprocessor symbol +.Dv OPENSSL_LOAD_CONF +#define'd, it also calls +.Xr OPENSSL_config 3 +with a +.Dv NULL +argument, loading the default configuration file. .Pp .Fn OpenSSL_add_all_digests adds all digest algorithms to the table. @@ -96,8 +103,7 @@ removes all ciphers and digests from the table. .Xr evp 3 , .Xr EVP_DigestInit 3 , .Xr EVP_EncryptInit 3 , -.Xr OPENSSL_config 3 , -.Xr OPENSSL_init_crypto 3 +.Xr OPENSSL_config 3 .Sh HISTORY .Fn EVP_cleanup and precursor functions diff --git a/src/lib/libssl/man/OPENSSL_init_ssl.3 b/src/lib/libssl/man/OPENSSL_init_ssl.3 index 5c9f51fe49..f37dccfaac 100644 --- a/src/lib/libssl/man/OPENSSL_init_ssl.3 +++ b/src/lib/libssl/man/OPENSSL_init_ssl.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: OPENSSL_init_ssl.3,v 1.3 2019/06/12 09:36:30 schwarze Exp $ +.\" $OpenBSD: OPENSSL_init_ssl.3,v 1.4 2019/06/14 13:41:31 schwarze Exp $ .\" Copyright (c) 2018 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -13,7 +13,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: June 12 2019 $ +.Dd $Mdocdate: June 14 2019 $ .Dt OPENSSL_INIT_SSL 3 .Os .Sh NAME @@ -27,13 +27,27 @@ .Fa "const void *dummy" .Fc .Sh DESCRIPTION +This function is deprecated. +It is never useful for any application program to call it explicitly. +The library automatically calls it internally with an +.Fa options +argument of 0 whenever needed. +It is safest to assume that any function may do so. +.Pp +To enable or disable the standard configuration file, instead use +.Xr OPENSSL_config 3 +or +.Xr OPENSSL_no_config 3 , +respectively. +To load a non-standard configuration file, refer to +.Xr CONF_modules_load_file 3 . +.Pp .Fn OPENSSL_init_ssl calls -.Xr OPENSSL_init_crypto 3 -and also allocates various resources used internally by the ssl library. -.Pp -Calling it is never useful because it is automatically called -internally when needed. +.Xr OPENSSL_init_crypto 3 , +.Xr SSL_load_error_strings 3 , +and +.Xr SSL_library_init 3 . .Pp The .Fa options @@ -50,7 +64,7 @@ none of the calls except the first one have any effect. is intended to return 1 on success or 0 on error. .Sh SEE ALSO .Xr CONF_modules_load_file 3 , -.Xr OPENSSL_init_crypto 3 , +.Xr OPENSSL_config 3 , .Xr ssl 3 .Sh HISTORY .Fn OPENSSL_init_ssl diff --git a/src/lib/libssl/man/SSL_library_init.3 b/src/lib/libssl/man/SSL_library_init.3 index 42f19adc28..053c1e6fcb 100644 --- a/src/lib/libssl/man/SSL_library_init.3 +++ b/src/lib/libssl/man/SSL_library_init.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: SSL_library_init.3,v 1.6 2018/03/27 17:35:50 schwarze Exp $ +.\" $OpenBSD: SSL_library_init.3,v 1.7 2019/06/14 13:41:31 schwarze Exp $ .\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 .\" .\" This file was written by Lutz Jaenicke . @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: March 27 2018 $ +.Dd $Mdocdate: June 14 2019 $ .Dt SSL_LIBRARY_INIT 3 .Os .Sh NAME @@ -65,8 +65,13 @@ .Ft int .Fn SSLeay_add_ssl_algorithms void .Sh DESCRIPTION +These functions are deprecated. +It is never useful for any application program to call any of them explicitly. +The library automatically calls them internally whenever needed. +.Pp .Fn SSL_library_init -registers the available SSL/TLS ciphers and digests. +registers the available ciphers and digests +which are used directly or indirectly by TLS. .Pp .Fn OpenSSL_add_ssl_algorithms and @@ -74,28 +79,11 @@ and are synonyms for .Fn SSL_library_init and are implemented as macros. -.Pp -.Fn SSL_library_init -must be called before any other action takes place. -.Fn SSL_library_init -is not reentrant. -.Pp -.Fn SSL_library_init -adds ciphers and digests used directly and indirectly by SSL/TLS. .Sh RETURN VALUES .Fn SSL_library_init -always returns 1, so it is safe to discard the return value. -.Sh EXAMPLES -A typical TLS/SSL application will start with the library initialization, and -provide readable error messages. -.Bd -literal -SSL_load_error_strings(); /* readable error messages */ -SSL_library_init(); /* initialize library */ -.Ed +always returns 1. .Sh SEE ALSO -.Xr RAND_add 3 , -.Xr ssl 3 , -.Xr SSL_load_error_strings 3 +.Xr ssl 3 .Sh HISTORY .Fn SSLeay_add_ssl_algorithms first appeared in SSLeay 0.8.0 and has been available since diff --git a/src/lib/libssl/man/ssl.3 b/src/lib/libssl/man/ssl.3 index 7683599652..6e7914c8b4 100644 --- a/src/lib/libssl/man/ssl.3 +++ b/src/lib/libssl/man/ssl.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ssl.3,v 1.16 2019/06/12 09:03:43 schwarze Exp $ +.\" $OpenBSD: ssl.3,v 1.17 2019/06/14 13:41:31 schwarze Exp $ .\" full merge up to: OpenSSL e330f55d Nov 11 00:51:04 2016 +0100 .\" selective merge up to: OpenSSL cbade361 Dec 12 13:14:45 2017 +0100 .\" @@ -51,7 +51,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: June 12 2019 $ +.Dd $Mdocdate: June 14 2019 $ .Dt SSL 3 .Os .Sh NAME @@ -62,10 +62,7 @@ The OpenSSL .Nm ssl library implements the Transport Layer Security (TLS v1) protocols. .Pp -At first the library must be initialized; see -.Xr SSL_library_init 3 . -.Pp -Then an +An .Vt SSL_CTX object is created as a framework to establish TLS/SSL enabled connections (see .Xr SSL_CTX_new 3 ) . @@ -354,11 +351,12 @@ To inspect the state during ongoing communication: .Xr OPENSSL_init_ssl 3 , .Xr SSL_COMP_add_compression_method 3 , .Xr SSL_CTX_set_tmp_rsa_callback 3 , +.Xr SSL_library_init 3 , .Xr SSL_set_tmp_ecdh 3 .Sh SEE ALSO .Xr openssl 1 , .Xr crypto 3 , -.Xr SSL_load_error_strings 3 +.Xr tls_init 3 .Sh HISTORY The .Nm -- cgit v1.2.3-55-g6feb