From 61150c63123fd35d04d23a0f8879a03f82044004 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Thu, 3 Nov 2016 12:21:50 +0000 Subject: convert configuration manuals from pod to mdoc --- src/lib/libcrypto/man/Makefile | 10 +- src/lib/libcrypto/man/OPENSSL_VERSION_NUMBER.3 | 96 +++++++++++++++++ src/lib/libcrypto/man/OPENSSL_config.3 | 115 +++++++++++++++++++++ .../libcrypto/man/OPENSSL_load_builtin_modules.3 | 53 ++++++++++ src/lib/libcrypto/man/OpenSSL_add_all_algorithms.3 | 71 +++++++++++++ 5 files changed, 340 insertions(+), 5 deletions(-) create mode 100644 src/lib/libcrypto/man/OPENSSL_VERSION_NUMBER.3 create mode 100644 src/lib/libcrypto/man/OPENSSL_config.3 create mode 100644 src/lib/libcrypto/man/OPENSSL_load_builtin_modules.3 create mode 100644 src/lib/libcrypto/man/OpenSSL_add_all_algorithms.3 (limited to 'src/lib/libcrypto/man') diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index 802b34399f..17efba0d08 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.40 2016/11/03 10:24:26 schwarze Exp $ +# $OpenBSD: Makefile,v 1.41 2016/11/03 12:21:50 schwarze Exp $ .include # for NOMAN @@ -118,6 +118,10 @@ MAN= \ HMAC.3 \ MD5.3 \ OBJ_nid2obj.3 \ + OPENSSL_VERSION_NUMBER.3 \ + OPENSSL_config.3 \ + OPENSSL_load_builtin_modules.3 \ + OpenSSL_add_all_algorithms.3 \ UI_new.3 \ bn_dump.3 \ crypto.3 \ @@ -128,10 +132,6 @@ MAN= \ lh_new.3 \ GENMAN= \ - OPENSSL_VERSION_NUMBER.3 \ - OPENSSL_config.3 \ - OPENSSL_load_builtin_modules.3 \ - OpenSSL_add_all_algorithms.3 \ PKCS5_PBKDF2_HMAC.3 \ PEM_read_bio_PrivateKey.3 \ PEM_write_bio_PKCS7_stream.3 \ diff --git a/src/lib/libcrypto/man/OPENSSL_VERSION_NUMBER.3 b/src/lib/libcrypto/man/OPENSSL_VERSION_NUMBER.3 new file mode 100644 index 0000000000..660a964427 --- /dev/null +++ b/src/lib/libcrypto/man/OPENSSL_VERSION_NUMBER.3 @@ -0,0 +1,96 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt OPENSSL_VERSION_NUMBER 3 +.Os +.Sh NAME +.Nm OPENSSL_VERSION_NUMBER , +.Nm SSLeay , +.Nm SSLeay_version +.Nd get OpenSSL version number +.Sh SYNOPSIS +.In openssl/opensslv.h +.Fd #define OPENSSL_VERSION_NUMBER 0xnnnnnnnnnL +.In openssl/crypto.h +.Ft long +.Fn SSLeay void +.Ft const char * +.Fo SSLeay_version +.Fa "int t" +.Fc +.Sh DESCRIPTION +.Dv OPENSSL_VERSION_NUMBER +is a numeric release version identifier. +The first two digits contain the major release number, +the third and fourth digits the minor release number, +the fifth and sixth digits the fix release number, +the seventh and eight digits the patch release number. +The final digit is 0 for development, 1 to e for betas 1 to 14, or f +for release. +.Pp +For example: +.Bd -literal -offset indent +0x000906000 == 0.9.6 dev +0x000906023 == 0.9.6b beta 3 +0x00090605f == 0.9.6e release +.Ed +.Pp +Versions prior to 0.9.3 had identifiers < 0x0930. +For versions between 0.9.3 and 0.9.5, +the seventh digit was 1 for release and 0 otherwise, +and the eighth and ninth digits were the patch release number. +.Pp +For example: +.Bd -literal +0x000904100 == 0.9.4 release +0x000905000 == 0.9.5 dev +.Ed +.Pp +Version 0.9.5a had an interim interpretation that is like the current +one, except the patch level got the highest bit set, to keep continuity. +The number was therefore 0x0090581f. +.Pp +For backward compatibility, SSLEAY_VERSION_NUMBER is also defined. +.Pp +.Fn SSLeay +returns this number. +The return value can be compared to the macro to make sure that the +correct version of the library has been loaded, especially when using +DLLs on Windows systems. +.Pp +.Fn SSLeay_version +returns different strings depending on +.Fa t : +.Bl -tag -width Ds +.It Dv SSLEAY_VERSION +The text variant of the version number and the release date. +For example, "OpenSSL 0.9.5a 1 Apr 2000". +.It Dv SSLEAY_CFLAGS +The compiler flags set for the compilation process in the form +"compiler: ..." if available or "compiler: information not available" +otherwise. +.It Dv SSLEAY_BUILT_ON +The date of the build process in the form "built on: ..." if available +or "built on: date not available" otherwise. +.It Dv SSLEAY_PLATFORM +The "Configure" target of the library build in the form "platform: ..." +if available or "platform: information not available" otherwise. +.It Dv SSLEAY_DIR +The "OPENSSLDIR" setting of the library build in the form "OPENSSLDIR: +"..."" if available or "OPENSSLDIR: N/A" otherwise. +.El +.Pp +For an unknown +.Fa t , +the text "not available" is returned. +.Sh RETURN VALUE +The version number. +.Sh SEE ALSO +.Xr crypto 3 +.Sh HISTORY +.Fn SSLeay +and +.Dv SSLEAY_VERSION_NUMBER +are available in all versions of SSLeay and OpenSSL. +.Dv OPENSSL_VERSION_NUMBER +is available in all versions of OpenSSL. +.Dv SSLEAY_DIR +was added in OpenSSL 0.9.7. diff --git a/src/lib/libcrypto/man/OPENSSL_config.3 b/src/lib/libcrypto/man/OPENSSL_config.3 new file mode 100644 index 0000000000..a944ba7b4e --- /dev/null +++ b/src/lib/libcrypto/man/OPENSSL_config.3 @@ -0,0 +1,115 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt OPENSSL_CONFIG 3 +.Os +.Sh NAME +.Nm OPENSSL_config , +.Nm OPENSSL_no_config +.Nd simple OpenSSL configuration functions +.Sh SYNOPSIS +.In openssl/conf.h +.Ft void +.Fo OPENSSL_config +.Fa "const char *config_name" +.Fc +.Ft void +.Fn OPENSSL_no_config void +.Sh DESCRIPTION +.Fn OPENSSL_config +configures OpenSSL using the standard +.Pa openssl.cnf +configuration file name using +.Fa config_name . +If +.Fa config_name +is +.Dv NULL +then the default name +.Sy openssl_conf +will be used. +Any errors are ignored. +Further calls to +.Fn OPENSSL_config +will have no effect. +.Pp +.Fn OPENSSL_no_config +disables configuration. +If called before +.Fn OPENSSL_config , +no configuration takes place. +.Pp +It is +.Sy strongly +recommended that +.Sy all +new applications call +.Fn OPENSSL_config +or the more sophisticated functions such as +.Xr CONF_modules_load 3 +during initialization (that is before starting any threads). +By doing this, an application does not need to keep track of all +configuration options and some new functionality can be supported +automatically. +.Pp +It is also possible to automatically call +.Fn OPENSSL_config +when an application calls +.Xr OPENSSL_add_all_algorithms 3 +by compiling an application with the preprocessor symbol +.Dv OPENSSL_LOAD_CONF +#define'd. +In this way configuration can be added without source changes. +.Pp +The environment variable +.Ev OPENSSL_CONF +can be set to specify the location of the configuration file. +.Pp +Currently ASN1 OBJECT and ENGINE configuration can be performed. +.Pp +There are several reasons why calling the OpenSSL configuration routines +is advisable. +For example new ENGINE functionality was added to OpenSSL 0.9.7. +In OpenSSL 0.9.7 control functions can be supported by ENGINEs, this can be +used (among other things) to load dynamic ENGINEs from shared libraries +(DSOs). +However very few applications currently support the control interface +and so very few can load and use dynamic ENGINEs. +Equally in future more sophisticated ENGINEs will require certain +control operations to customize them. +If an application calls +.Fn OPENSSL_config +it doesn't need to know or care about ENGINE control operations because +they can be performed by editing a configuration file. +.Pp +Applications should free up configuration at application closedown by +calling +.Xr CONF_modules_free 3 . +.Sh RETURN VALUES +Neither +.Fn OPENSSL_config +nor +.Fn OPENSSL_no_config +return a value. +.Sh SEE ALSO +.Xr CONF_modules_free 3 , +.Xr CONF_modules_load 3 +.Sh HISTORY +.Fn OPENSSL_config +and +.Fn OPENSSL_no_config +first appeared in OpenSSL 0.9.7. +.Sh CAVEATS +The +.Fn OPENSSL_config +function is designed to be a very simple "call it and forget it" +function. +As a result its behaviour is somewhat limited. +It ignores all errors silently and it can only load from the standard +configuration file location for example. +.Pp +It is however +.Sy much +better than nothing. +Applications which need finer control over their configuration +functionality should use the configuration functions such as +.Xr CONF_load_modules 3 +directly. diff --git a/src/lib/libcrypto/man/OPENSSL_load_builtin_modules.3 b/src/lib/libcrypto/man/OPENSSL_load_builtin_modules.3 new file mode 100644 index 0000000000..2a107ab7c4 --- /dev/null +++ b/src/lib/libcrypto/man/OPENSSL_load_builtin_modules.3 @@ -0,0 +1,53 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt OPENSSL_LOAD_BUILTIN_MODULES 3 +.Os +.Sh NAME +.Nm OPENSSL_load_builtin_modules , +.Nm ASN1_add_oid_module , +.Nm ENGINE_add_conf_module +.Nd add standard configuration modules +.Sh SYNOPSIS +.In openssl/conf.h +.Ft void +.Fn OPENSSL_load_builtin_modules void +.Ft void +.Fn ASN1_add_oid_module void +.Ft void +.Fn ENGINE_add_conf_module void +.Sh DESCRIPTION +The function +.Fn OPENSSL_load_builtin_modules +adds all the standard OpenSSL configuration modules to the internal +list. +They can then be used by the OpenSSL configuration code. +.Pp +.Fn ASN1_add_oid_module +adds just the ASN1 OBJECT module. +.Pp +.Fn ENGINE_add_conf_module +adds just the ENGINE configuration module. +.Pp +If the simple configuration function +.Xr OPENSSL_config 3 +is called then +.Fn OPENSSL_load_builtin_modules +is called automatically. +.Pp +Applications which use the configuration functions directly will need to +call +.Fn OPENSSL_load_builtin_modules +themselves +.Em before +any other configuration code. +.Pp +Applications should call +.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 RETURN VALUE +None of the functions return a value. +.Sh SEE ALSO +.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 new file mode 100644 index 0000000000..b6e93a939e --- /dev/null +++ b/src/lib/libcrypto/man/OpenSSL_add_all_algorithms.3 @@ -0,0 +1,71 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt OPENSSL_ADD_ALL_ALGORITHMS 3 +.Os +.Sh NAME +.Nm OpenSSL_add_all_algorithms , +.Nm OpenSSL_add_all_ciphers , +.Nm OpenSSL_add_all_digests , +.Nm EVP_cleanup +.Nd add algorithms to internal table +.Sh SYNOPSIS +.In openssl/evp.h +.Ft void +.Fn OpenSSL_add_all_algorithms void +.Ft void +.Fn OpenSSL_add_all_ciphers void +.Ft void +.Fn OpenSSL_add_all_digests void +.Ft void +.Fn EVP_cleanup void +.Sh DESCRIPTION +OpenSSL keeps an internal table of digest algorithms and ciphers. +It uses this table to lookup ciphers via functions such as +.Xr EVP_get_cipherbyname 3 . +.Pp +.Fn OpenSSL_add_all_algorithms +adds all algorithms to the table (digests and ciphers). +.Pp +.Fn OpenSSL_add_all_digests +adds all digest algorithms to the table. +.Pp +.Fn OpenSSL_add_all_ciphers +adds all encryption algorithms to the table including password based +encryption algorithms. +.Pp +.Fn EVP_cleanup +removes all ciphers and digests from the table. +.Pp +A typical application will call +.Fn OpenSSL_add_all_algorithms +initially and +.Fn EVP_cleanup +before exiting. +.Pp +An application does not need to add algorithms to use them explicitly, +for example by +.Xr EVP_sha1 3 . +It just needs to add them if it (or any of the functions it calls) needs +to lookup algorithms. +.Pp +The cipher and digest lookup functions are used in many parts of the +library. +If the table is not initialized, several functions will misbehave and +complain they cannot find algorithms. +This includes the PEM, PKCS#12, SSL and S/MIME libraries. +This is a common query in the OpenSSL mailing lists. +.Pp +Calling +.Fn OpenSSL_add_all_algorithms +links in all algorithms: as a result a statically linked executable can +be quite large. +If this is important, it is possible to just add the required ciphers and +digests. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_DigestInit 3 , +.Xr EVP_EncryptInit 3 +.Sh BUGS +Although the functions do not return error codes, it is possible for them +to fail. +This will only happen as a result of a memory allocation failure so this +is not too much of a problem in practice. -- cgit v1.2.3-55-g6feb