From 22bb8c254555036725aacb64c056bd8b3379fc4c Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Wed, 9 Oct 2019 15:45:12 -0400 Subject: [PATCH] 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 Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/10135) --- doc/man1/openssl.pod | 33 ++++++--- doc/man3/CTLOG_STORE_new.pod | 4 +- doc/man3/OPENSSL_ia32cap.pod | 14 ++-- doc/man3/OPENSSL_s390xcap.pod | 12 ++-- doc/man3/OpenSSL_version.pod | 4 +- doc/man3/SSL_CTX_load_verify_locations.pod | 8 +-- doc/man3/UI_new.pod | 2 +- doc/man7/openssl-env.pod | 81 ++++++++++++++++++++++ doc/man7/passphrase-encoding.pod | 2 +- 9 files changed, 129 insertions(+), 31 deletions(-) create mode 100644 doc/man7/openssl-env.pod 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 program provides a rich variety of sub-commands (I in +The B program provides a rich variety of commands (I in the SYNOPSIS above), each of which often has a wealth of options and arguments (I and I 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 in the default certificate +storage area, which can be determined from the L +command. The environment variable B can be used to specify -the location of the file. -If the environment variable is not specified, then the file is named -F 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. 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 program. (BI is not able to detect pseudo-commands such as B, B, or BI itself.) -=head2 Standard Sub-commands +=head2 Standard Commands =over 4 @@ -147,7 +147,7 @@ EC parameter manipulation and generation. =item B -Encoding with Ciphers. +Encryption, decryption, and encoding. =item B @@ -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 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, L, +L, and L. + +For information about the use of environment variables in configuration, +see L. + +For information about querying or specifying CPU architecture flags, see +L, and L. + +For information about all environment variables used by the OpenSSL libraries, +see L. + =over 4 =item BI[,...] @@ -903,6 +917,7 @@ L, L, L, L, +L. L, L 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). This can be -overridden using an environment variable named "CTLOG_FILE". +F in OPENSSLDIR (see the output of L). This can be +overridden using an environment variable named B. 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 environment variable prior target application start. To +give a specific example, on Intel P4 processor +C, or better yet +C 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 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 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, B, B, B, B, B, B, B +and B. =item :: 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, B, +B, B, B, B, B, B, B, B, B +and B. =item stfle::: @@ -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. -Or C if not available, such as when configured with B. +For x86 the string looks like C +or C 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 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 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 in the default OpenSSL directory. -Alternatively the SSL_CERT_FILE environment variable can be defined to +Alternatively the B 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 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 + +Specifies the path to a certificate transparency log list. +See L. + +=item B + +Specifies the path to the B executable. Only used by +the B script. +See L. + +=item B + +Specfies the path to a configuration file. +See L and L. + +=item B + +Specifies the directory from which dynamic engines are loaded. +See L. + +=item B, B + +If built with debugging, this allows memory allocation to fail. +See L. + +=item B + +Specifies the directory from which cryptographic providers are loaded. +See L. + +=item B + +If set, then L returns UTF-8 encoded strings, rather than +ones encoded in the current code page, and +the L 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 + +The state file for the random number generator. +This should not be needed in normal use. +See L. + +=item B, B + +Specify the default directory or file containing CA certificates. +See L. + +=item B + +Additional arguments for the L 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. + +=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 will have anything entered on [Windows] console prompt +B will have anything entered on [Windows] console prompt converted to UTF-8 (command line and separately prompted pass phrases alike). =head2 Opening existing objects