=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).
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
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
=item B<enc>
-Encoding with Ciphers.
+Encryption, decryption, and encoding.
=item B<engine>
=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.
=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>[,...]
L<openssl-x509(1)>,
L<config(5)>,
L<crypto(7)>,
+L<openssl-env(7)>.
L<ssl(7)>,
L<x509v3_config(5)>
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.
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.
=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"
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.
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>
=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
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
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
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.
--- /dev/null
+=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
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
projects / oweals / openssl.git / commitdiff