[openssl] master update
tmraz at fedoraproject.org
tmraz at fedoraproject.org
Thu Nov 28 12:59:38 UTC 2019
The branch master has been updated
via d86925e6bdaf3544615860e932d66207662d335e (commit)
via 22bb8c254555036725aacb64c056bd8b3379fc4c (commit)
from b7f491cbd65116761da0565895069431b6cb8ef3 (commit)
- Log -----------------------------------------------------------------
commit d86925e6bdaf3544615860e932d66207662d335e
Author: Rich Salz <rsalz at akamai.com>
Date: Thu Nov 21 18:14:12 2019 -0500
Use option/parameter consistently.
Reviewed-by: Richard Levitte <levitte at openssl.org>
Reviewed-by: Tomas Mraz <tmraz at fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10135)
commit 22bb8c254555036725aacb64c056bd8b3379fc4c
Author: Rich Salz <rsalz at akamai.com>
Date: Wed Oct 9 15:45:12 2019 -0400
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 at openssl.org>
Reviewed-by: Tomas Mraz <tmraz at fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10135)
-----------------------------------------------------------------------
Summary of changes:
doc/man1/openssl.pod | 47 +++++++++++------
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, 136 insertions(+), 38 deletions(-)
create mode 100644 doc/man7/openssl-env.pod
diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod
index 5fa16f4a27..4ff5784124 100644
--- a/doc/man1/openssl.pod
+++ b/doc/man1/openssl.pod
@@ -8,8 +8,8 @@ openssl - OpenSSL command line tool
B<openssl>
I<command>
-[ I<command_opts> ... ]
-[ I<command_args> ... ]
+[ I<options> ... ]
+[ I<parameters> ... ]
B<openssl>
B<list>
@@ -21,7 +21,7 @@ B<-digest-algorithms> |
B<-mac-algorithms> |
B<-public-key-algorithms>
-B<openssl> B<no->I<XXX> [ I<arbitrary options> ]
+B<openssl> B<no->I<XXX> [ I<options> ]
=head1 DESCRIPTION
@@ -44,21 +44,22 @@ It can be used for
=head1 COMMAND SUMMARY
-The B<openssl> program provides a rich variety of sub-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).
+The B<openssl> program provides a rich variety of commands (I<command> in
+the L</SYNOPSIS> above).
+Each command can have many options and argument parameters, shown above as
+I<options> and I<parameters>.
Detailed documentation and use cases for most standard subcommands are available
(e.g., L<openssl-x509(1)>).
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 +86,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 +148,7 @@ EC parameter manipulation and generation.
=item B<enc>
-Encoding with Ciphers.
+Encryption, decryption, and encoding.
=item B<engine>
@@ -392,14 +393,13 @@ 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.
Depending on how OpenSSL was configured and built, not all ciphers listed
-here may be present. See L<openssl-enc(1)> for more information and command
-usage.
+here may be present. See L<openssl-enc(1)> for more information.
=over 4
@@ -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..f4a21e4b56 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<openssl-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
More information about the openssl-commits
mailing list