From 1df6e36c9d7eff0320ef36b1b8f08614c168f15f Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Sat, 17 Mar 2018 18:52:42 +0000 Subject: 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. --- src/lib/libcrypto/man/CONF_modules_load_file.3 | 7 ++- src/lib/libcrypto/man/Makefile | 3 +- src/lib/libcrypto/man/OPENSSL_config.3 | 5 +- src/lib/libcrypto/man/OPENSSL_init_crypto.3 | 77 ++++++++++++++++++++++++++ src/lib/libssl/man/Makefile | 3 +- src/lib/libssl/man/OPENSSL_init_ssl.3 | 60 ++++++++++++++++++++ 6 files changed, 148 insertions(+), 7 deletions(-) create mode 100644 src/lib/libcrypto/man/OPENSSL_init_crypto.3 create mode 100644 src/lib/libssl/man/OPENSSL_init_ssl.3 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 . @@ -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 @@ -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 . @@ -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 +.\" +.\" 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 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 +.\" +.\" 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 . -- cgit v1.2.3-55-g6feb