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/libssl/man/OPENSSL_init_ssl.3 | 30 ++++++++++++++++++++++-------- src/lib/libssl/man/SSL_library_init.3 | 32 ++++++++++---------------------- src/lib/libssl/man/ssl.3 | 12 +++++------- 3 files changed, 37 insertions(+), 37 deletions(-) (limited to 'src/lib/libssl/man') 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