In crypto.h rev. 1.43 and ssl.h rev. 1.153 2018/03/17 16:20:01, beck@

provided OPENSSL_init_crypto(3) and OPENSSL_init_ssl(3).
Write the documentation from scratch
because the text OpenSSL provides is full of bloat.

6 files changed, 148 insertions, 7 deletions

diff --git a/src/lib/libcrypto/man/CONF_modules_load_file.3 b/src/lib/libcrypto/man/CONF_modules_load_file.3
index 620787b4f1..c3cc89adf3 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.5 2016/12/11 18:06:09 schwarze Exp $
+.\"     $OpenBSD: CONF_modules_load_file.3,v 1.6 2018/03/17 18:52:42 schwarze Exp $
 .\"     OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -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: December 11 2016 $
+.Dd $Mdocdate: March 17 2018 $
 .Dt CONF_MODULES_LOAD_FILE 3
 .Os
 .Sh NAME
@@ -219,7 +219,8 @@ if (fp == NULL) {
 .Sh SEE ALSO
 .Xr CONF_modules_free 3 ,
 .Xr ERR 3 ,
-.Xr OPENSSL_config 3
+.Xr OPENSSL_config 3 ,
+.Xr OPENSSL_init_crypto 3
 .Sh HISTORY
 .Fn CONF_modules_load_file
 and
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 58b3cc2847..8d2e242f31 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.136 2018/03/01 19:20:09 schwarze Exp $
+# $OpenBSD: Makefile,v 1.137 2018/03/17 18:52:42 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -155,6 +155,7 @@ MAN=	\
         OPENSSL_VERSION_NUMBER.3 \
         OPENSSL_cleanse.3 \
         OPENSSL_config.3 \
+        OPENSSL_init_crypto.3 \
         OPENSSL_load_builtin_modules.3 \
         OPENSSL_malloc.3 \
         OPENSSL_sk_new.3 \
diff --git a/src/lib/libcrypto/man/OPENSSL_config.3 b/src/lib/libcrypto/man/OPENSSL_config.3
index a5fd5a8d36..3aa1944dab 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.6 2017/07/06 15:42:04 schwarze Exp $
+.\"     $OpenBSD: OPENSSL_config.3,v 1.7 2018/03/17 18:52:42 schwarze Exp $
 .\"     OpenSSL ab6577a4 May 14 21:07:51 2014 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -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: July 6 2017 $
+.Dd $Mdocdate: March 17 2018 $
 .Dt OPENSSL_CONFIG 3
 .Os
 .Sh NAME
@@ -147,6 +147,7 @@ standard configuration file
 .Sh SEE ALSO
 .Xr CONF_modules_free 3 ,
 .Xr CONF_modules_load 3 ,
+.Xr OPENSSL_init_crypto 3 ,
 .Xr openssl.cnf 5
 .Sh HISTORY
 .Fn OPENSSL_config
diff --git a/src/lib/libcrypto/man/OPENSSL_init_crypto.3 b/src/lib/libcrypto/man/OPENSSL_init_crypto.3
new file mode 100644
index 0000000000..27c60561fe
--- /dev/null
+++ b/src/lib/libcrypto/man/OPENSSL_init_crypto.3
@@ -0,0 +1,77 @@
+.\" $OpenBSD: OPENSSL_init_crypto.3,v 1.1 2018/03/17 18:52:42 schwarze Exp $
+.\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" 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 17 2018 $
+.Dt OPENSSL_INIT_CRYPTO 3
+.Os
+.Sh NAME
+.Nm OPENSSL_init_crypto
+.Nd initialise the crypto library
+.Sh SYNOPSIS
+.In openssl/crypto.h
+.Ft int
+.Fo OPENSSL_init_crypto
+.Fa "uint64_t options"
+.Fa "const void *dummy"
+.Fc
+.Sh DESCRIPTION
+If
+.Fn OPENSSL_init_crypto
+is called before any other crypto or ssl functions, the crypto
+library is initialised by allocating various internal resources.
+Unless the
+.Dv OPENSSL_INIT_NO_LOAD_CONFIG
+bit is set in the
+.Fa options
+argument, the default
+.Xr openssl.cnf 5
+configuration file is also loaded as documented in
+.Xr OPENSSL_config 3 .
+.Pp
+The other
+.Fa options
+flags defined by OpenSSL are all ignored by LibreSSL.
+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
+.Fn OPENSSL_init_crypto
+is intended to return 1 on success or 0 on error.
+.Sh SEE ALSO
+.Xr CONF_modules_load_file 3 ,
+.Xr OPENSSL_init_ssl 3 ,
+.Xr openssl.cnf 5
+.Sh HISTORY
+.Fn OPENSSL_init_crypto
+first appeared in OpenSSL 1.1.0.
+.Sh BUGS
+.Fn OPENSSL_init_crypto
+silently ignores almost all kinds of errors.
+In particular, if memory allocation fails, initialisation is likely
+to remain incomplete, the library may be in an inconsistent internal
+state, but the return value will usually indicate success anyway.
+There is no way for the application program to find out whether
+library initialisation is actually complete, nor to get back to a
+consistent state if it isn't.
diff --git a/src/lib/libssl/man/Makefile b/src/lib/libssl/man/Makefile
index d5141811e7..375e5fba2b 100644
--- a/src/lib/libssl/man/Makefile
+++ b/src/lib/libssl/man/Makefile
@@ -1,9 +1,10 @@
-# $OpenBSD: Makefile,v 1.64 2018/03/17 18:19:49 schwarze Exp $
+# $OpenBSD: Makefile,v 1.65 2018/03/17 18:52:42 schwarze Exp $
 
 .include <bsd.own.mk>
 
 MAN =   BIO_f_ssl.3 \
         DTLSv1_listen.3 \
+        OPENSSL_init_ssl.3 \
         PEM_read_SSL_SESSION.3 \
         SSL_CIPHER_get_name.3 \
         SSL_COMP_add_compression_method.3 \
diff --git a/src/lib/libssl/man/OPENSSL_init_ssl.3 b/src/lib/libssl/man/OPENSSL_init_ssl.3
new file mode 100644
index 0000000000..ae356c9bf5
--- /dev/null
+++ b/src/lib/libssl/man/OPENSSL_init_ssl.3
@@ -0,0 +1,60 @@
+.\" $OpenBSD: OPENSSL_init_ssl.3,v 1.1 2018/03/17 18:52:42 schwarze Exp $
+.\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" 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 17 2018 $
+.Dt OPENSSL_INIT_SSL 3
+.Os
+.Sh NAME
+.Nm OPENSSL_init_ssl
+.Nd initialise the crypto and ssl libraries
+.Sh SYNOPSIS
+.In openssl/ssl.h
+.Ft int
+.Fo OPENSSL_init_ssl
+.Fa "uint64_t options"
+.Fa "const void *dummy"
+.Fc
+.Sh DESCRIPTION
+.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.
+.Pp
+The
+.Fa options
+argument is passed on to
+.Xr OPENSSL_init_crypto 3
+and the
+.Fa dummy
+argument is ignored.
+.Pp
+If this function is called more than once,
+none of the calls except the first one have any effect.
+.Sh RETURN VALUES
+.Fn OPENSSL_init_ssl
+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
+.Sh HISTORY
+.Fn OPENSSL_init_ssl
+first appeared in OpenSSL 1.1.0.
+.Sh BUGS
+.Fn OPENSSL_init_ssl
+silently ignores even more configuration failures than
+.Xr OPENSSL_init_crypto 3 .