5 files changed, 340 insertions, 5 deletions

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 <bsd.own.mk>           # 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.