Document more env var stuff, fix some typo's

Add openssl-env.pod
Also fix up many other environment page formatting nits.

Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10135)

9 files changed, 129 insertions, 31 deletions

diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod
index 5fa16f4a27..7c61d125cb 100644
--- a/doc/man1/openssl.pod
+++ b/doc/man1/openssl.pod
@@ -44,7 +44,7 @@ It can be used for
 
 =head1 COMMAND SUMMARY
 
-The B<openssl> program provides a rich variety of sub-commands (I<command> in
+The B<openssl> program provides a rich variety of commands (I<command> in
 the SYNOPSIS above), each of which often has a wealth of options and arguments
 (I<command_opts> and I<command_args> in the SYNOPSIS).
 
@@ -53,12 +53,12 @@ Detailed documentation and use cases for most standard subcommands are available
 
 Many commands use an external configuration file for some or all of their
 arguments and have a B<-config> option to specify that file.
+The default name of the file is F<openssl.cnf> in the default certificate
+storage area, which can be determined from the L<openssl-version(1)>
+command.
 The environment variable B<OPENSSL_CONF> can be used to specify
-the location of the file.
-If the environment variable is not specified, then the file is named
-F<openssl.cnf> in the default certificate storage area, whose value
-depends on the configuration flags specified when the OpenSSL
-was built.
+a different location of the file.
+See L<openssl-env(7)>.
 
 The list options B<-standard-commands>, B<-digest-commands>,
 and B<-cipher-commands> output a list (one entry per line) of the names
@@ -85,7 +85,7 @@ availability of ciphers in the B<openssl> program.  (B<no->I<XXX> is
 not able to detect pseudo-commands such as B<quit>,
 B<list>, or B<no->I<XXX> itself.)
 
-=head2 Standard Sub-commands
+=head2 Standard Commands
 
 =over 4
 
@@ -147,7 +147,7 @@ EC parameter manipulation and generation.
 
 =item B<enc>
 
-Encoding with Ciphers.
+Encryption, decryption, and encoding.
 
 =item B<engine>
 
@@ -392,7 +392,7 @@ SM3 Digest
 
 =back
 
-=head2 Encoding and Cipher Commands
+=head2 Encryption, Decryption, and Encoding Commands
 
 The following aliases provide convenient access to the most used encodings
 and ciphers.
@@ -785,6 +785,20 @@ See L<openssl(1)/Format Options> for details.
 
 =head1 ENVIRONMENT
 
+The OpenSSL library can be take some configuration parameters from the
+environment.  Some of these variables are listed below.  For information
+about specific commands, see L<openssl-engine(1)>, L<openssl-provider(1)>,
+L<openssl-rehash(1)>, and L<tsget(1)>.
+
+For information about the use of environment variables in configuration,
+see L<config(5)/ENVIRONMENT>.
+
+For information about querying or specifying CPU architecture flags, see
+L<OPENSSL_ia32cap(3)>, and L<OPENSSL_s390xcap(3)>.
+
+For information about all environment variables used by the OpenSSL libraries,
+see L<openssl-env(7)>.
+
 =over 4
 
 =item B<OPENSSL_TRACE=>I<name>[,...]
@@ -903,6 +917,7 @@ L<openssl-version(1)>,
 L<openssl-x509(1)>,
 L<config(5)>,
 L<crypto(7)>,
+L<openssl-env(7)>.
 L<ssl(7)>,
 L<x509v3_config(5)>
 
diff --git a/doc/man3/CTLOG_STORE_new.pod b/doc/man3/CTLOG_STORE_new.pod
index 5b5d8a1ba6..5fe6775302 100644
--- a/doc/man3/CTLOG_STORE_new.pod
+++ b/doc/man3/CTLOG_STORE_new.pod
@@ -25,8 +25,8 @@ logs). The list can be loaded from one or more files and then searched by LogID
 CTLOG_STORE_new() creates an empty list of CT logs. This is then populated
 by CTLOG_STORE_load_default_file() or CTLOG_STORE_load_file().
 CTLOG_STORE_load_default_file() loads from the default file, which is named
-"ct_log_list.cnf" in OPENSSLDIR (see the output of L<openssl-version(1)>). This can be
-overridden using an environment variable named "CTLOG_FILE".
+F<ct_log_list.cnf> in OPENSSLDIR (see the output of L<version(1)>). This can be
+overridden using an environment variable named B<CTLOG_FILE>.
 CTLOG_STORE_load_file() loads from a caller-specified file path instead.
 Both of these functions append any loaded CT logs to the CTLOG_STORE.
 
diff --git a/doc/man3/OPENSSL_ia32cap.pod b/doc/man3/OPENSSL_ia32cap.pod
index 6c2d4b78ef..d7c40d0b41 100644
--- a/doc/man3/OPENSSL_ia32cap.pod
+++ b/doc/man3/OPENSSL_ia32cap.pod
@@ -69,10 +69,10 @@ executed on SSE2 capable CPU, but under control of OS that does not
 enable XMM registers. Historically address of the capability vector copy
 was exposed to application through OPENSSL_ia32cap_loc(), but not
 anymore. Now the only way to affect the capability detection is to set
-OPENSSL_ia32cap environment variable prior target application start. To
-give a specific example, on Intel P4 processor 'env
-OPENSSL_ia32cap=0x16980010 apps/openssl', or better yet 'env
-OPENSSL_ia32cap=~0x1000000 apps/openssl' would achieve the desired
+B<OPENSSL_ia32cap> environment variable prior target application start. To
+give a specific example, on Intel P4 processor
+C<env OPENSSL_ia32cap=0x16980010 apps/openssl>, or better yet
+C<env OPENSSL_ia32cap=~0x1000000 apps/openssl> would achieve the desired
 effect. Alternatively you can reconfigure the toolkit with no-sse2
 option and recompile.
 
@@ -116,9 +116,9 @@ a.k.a. AVX512IFMA extension;
 
 =back
 
-To control this extended capability word use ':' as delimiter when
-setting up OPENSSL_ia32cap environment variable. For example assigning
-':~0x20' would disable AVX2 code paths, and ':0' - all post-AVX
+To control this extended capability word use C<:> as delimiter when
+setting up B<OPENSSL_ia32cap> environment variable. For example assigning
+C<:~0x20> would disable AVX2 code paths, and C<:0> - all post-AVX
 extensions.
 
 It should be noted that whether or not some of the most "fancy"
diff --git a/doc/man3/OPENSSL_s390xcap.pod b/doc/man3/OPENSSL_s390xcap.pod
index 172cf60309..6d5326191c 100644
--- a/doc/man3/OPENSSL_s390xcap.pod
+++ b/doc/man3/OPENSSL_s390xcap.pod
@@ -16,7 +16,7 @@ When libcrypto is initialized, the bits returned by the STFLE instruction
 and by the QUERY functions are stored in the vector.
 
 To change the set of instructions available to an application, you can
-set the OPENSSL_s390xcap environment variable before you start the
+set the B<OPENSSL_s390xcap> environment variable before you start the
 application. After initialization, the capability vector is ANDed bitwise
 with a mask which is derived from the environment variable.
 
@@ -34,14 +34,16 @@ There are three types of tokens:
 The name of a processor generation. A bit in the environment variable's
 mask is set to one if and only if the specified processor generation
 implements the corresponding instruction set extension. Possible values
-are z900, z990, z9, z10, z196, zEC12, z13, z14 and z15.
+are B<z900>, B<z990>, B<z9>, B<z10>, B<z196>, B<zEC12>, B<z13>, B<z14>
+and B<z15>.
 
 =item <string>:<mask>:<mask>
 
 The name of an instruction followed by two 64-bit masks. The part of the
 environment variable's mask corresponding to the specified instruction is
-set to the specified 128-bit mask. Possible values are kimd, klmd, km, kmc,
-kmac, kmctr, kmo, kmf, prno, kma, pcc and kdsa.
+set to the specified 128-bit mask. Possible values are B<kimd>, B<klmd>,
+B<km>, B<kmc>, B<kmac>, B<kmctr>, B<kmo>, B<kmf>, B<prno>, B<kma>, B<pcc>
+and B<kdsa>.
 
 =item stfle:<mask>:<mask>:<mask>
 
@@ -52,7 +54,7 @@ instruction is set to the specified 192-bit mask.
 =back
 
 The 64-bit masks are specified in hexadecimal notation. The 0x prefix is
-optional. Prefix a mask with a tilde (~) to denote a bitwise NOT operation.
+optional. Prefix a mask with a tilde, C<~>, to denote a bitwise NOT operation.
 
 The following is a list of significant bits for each instruction. Colon
 rows separate the individual 64-bit masks. The bit numbers in the first
diff --git a/doc/man3/OpenSSL_version.pod b/doc/man3/OpenSSL_version.pod
index 4d6a1fef40..b3d5b72928 100644
--- a/doc/man3/OpenSSL_version.pod
+++ b/doc/man3/OpenSSL_version.pod
@@ -133,8 +133,8 @@ The current OpenSSL cpu settings.
 This is the current setting of the cpu capability flags. It is usually
 automatically configured but may be set via an environment variable.
 The value has the same syntax as the environment variable.
-For x86 the string looks like C<CPUINFO: OPENSSL_ia32cap=0x123:0x456>.
-Or C<CPUINFO: N/A> if not available, such as when configured with B<no-asm>.
+For x86 the string looks like C<CPUINFO: OPENSSL_ia32cap=0x123:0x456>
+or C<CPUINFO: N/A> if not available.
 
 =back
 
diff --git a/doc/man3/SSL_CTX_load_verify_locations.pod b/doc/man3/SSL_CTX_load_verify_locations.pod
index 3ee0f96345..d28ec4c867 100644
--- a/doc/man3/SSL_CTX_load_verify_locations.pod
+++ b/doc/man3/SSL_CTX_load_verify_locations.pod
@@ -40,13 +40,13 @@ trusted.
 SSL_CTX_set_default_verify_paths() specifies that the default locations from
 which CA certificates are loaded should be used. There is one default directory,
 one default file and one default store.
-The default CA certificates directory is called "certs" in the default OpenSSL
+The default CA certificates directory is called F<certs> in the default OpenSSL
 directory, and this is also the default store.
-Alternatively the SSL_CERT_DIR environment variable can be defined to
+Alternatively the B<SSL_CERT_DIR> environment variable can be defined to
 override this location.
-The default CA certificates file is called "cert.pem" in the default
+The default CA certificates file is called F<cert.pem> in the default
 OpenSSL directory.
-Alternatively the SSL_CERT_FILE environment variable can be defined to
+Alternatively the B<SSL_CERT_FILE> environment variable can be defined to
 override this location.
 
 SSL_CTX_set_default_verify_dir() is similar to
diff --git a/doc/man3/UI_new.pod b/doc/man3/UI_new.pod
index 83cda2e251..0615e2766c 100644
--- a/doc/man3/UI_new.pod
+++ b/doc/man3/UI_new.pod
@@ -205,7 +205,7 @@ are assumed to be encoded according to the current locale or (for
 Windows) code page.
 For applications having different demands, these strings need to be
 converted appropriately by the caller.
-For Windows, if the OPENSSL_WIN32_UTF8 environment variable is set,
+For Windows, if the B<OPENSSL_WIN32_UTF8> environment variable is set,
 the built-in method UI_OpenSSL() will produce UTF-8 encoded strings
 instead.
 
diff --git a/doc/man7/openssl-env.pod b/doc/man7/openssl-env.pod
new file mode 100644
index 0000000000..afad2bdfd2
--- /dev/null
+++ b/doc/man7/openssl-env.pod
@@ -0,0 +1,81 @@
+=pod
+
+=head1 NAME
+
+openssl-env - OpenSSL environment variables
+
+=head1 DESCRIPTION
+
+The OpenSSL libraries use environment variables to override the
+compiled-in default paths for various data.
+To avoid security risks, the environment is usually not consulted when
+the executable is set-user-ID or set-group-ID.
+
+=over 4
+
+=item B<CTLOG_FILE>
+
+Specifies the path to a certificate transparency log list.
+See L<CTLOG_STORE_new(3)>.
+
+=item B<OPENSSL>
+
+Specifies the path to the B<openssl> executable. Only used by
+the B<rehash> script.
+See L<openssl-rehash(1)/Script Configuration>.
+
+=item B<OPENSSL_CONF>
+
+Specfies the path to a configuration file.
+See L<openssl(1)> and L<config(5)>.
+
+=item B<OPENSSL_ENGINES>
+
+Specifies the directory from which dynamic engines are loaded.
+See L<openssl-engine(1)>.
+
+=item B<OPENSSL_MALLOC_FD>, B<OPENSSL_MALLOC_FAILURES>
+
+If built with debugging, this allows memory allocation to fail.
+See L<OPENSSSL_malloc(3)>.
+
+=item B<OPENSSL_MODULES>
+
+Specifies the directory from which cryptographic providers are loaded.
+See L<openssl-provider(1)>.
+
+=item B<OPENSSL_WIN32_UTF8>
+
+If set, then L<UI_OpenSSL(3)> returns UTF-8 encoded strings, rather than
+ones encoded in the current code page, and
+the L<openssl(1)> program also transcodes the command-line parameters
+from the current code page to UTF-8.
+This environment variable is only checked on Microsoft Windows platforms.
+
+=item B<RANDFILE>
+
+The state file for the random number generator.
+This should not be needed in normal use.
+See L<RAND_load_file(3)>.
+
+=item B<SSL_CERT_DIR>, B<SSL_CERT_FILE>
+
+Specify the default directory or file containing CA certificates.
+See L<SSL_CTX_load_verify_locations(3)>.
+
+=item B<TSGET>
+
+Additional arguments for the L<tsget(1)> command.
+
+=back
+
+=head1 COPYRIGHT
+
+Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/passphrase-encoding.pod b/doc/man7/passphrase-encoding.pod
index 7f2c2a2f80..4b4732faf2 100644
--- a/doc/man7/passphrase-encoding.pod
+++ b/doc/man7/passphrase-encoding.pod
@@ -116,7 +116,7 @@ encoded using UTF-8.
 This is default on most modern Unixes, but may involve an effort on other
 platforms.
 Specifically for Windows, setting the environment variable
-C<OPENSSL_WIN32_UTF8> will have anything entered on [Windows] console prompt
+B<OPENSSL_WIN32_UTF8> will have anything entered on [Windows] console prompt
 converted to UTF-8 (command line and separately prompted pass phrases alike).
 
 =head2 Opening existing objects