CONF library for their own purposes.
A configuration file is divided into a number of sections. Each section
-starts with a line B<[ section_name ]> and ends when a new section is
+starts with a line C<[section_name]> and ends when a new section is
started or end of file is reached. A section name can consist of
-alphanumeric characters and underscores.
+alphanumeric characters and underscores. The brackets are required.
The first section of a configuration file is special and is referred
-to as the B<default> section this is usually unnamed and is from the
+to as the B<default> section. This section is usually unnamed and spans from the
start of file until the first named section. When a name is being looked up
it is first looked up in a named section (if any) and then the
default section.
directive. Relative paths are evaluated based on the application current
working directory so unless the configuration file containing the
B<.include> directive is application specific the inclusion will not
-work as expected.
+work as expected. The environment variable B<OPENSSL_CONF_INCLUDE> can also be
+used to specify the path to prepend to all .include paths.
+
+There can be optional B<=> character and whitespace characters between
+B<.include> directive and the path which can be useful in cases the
+configuration file needs to be loaded by old OpenSSL versions which do
+not support the B<.include> syntax. They would bail out with error
+if the B<=> character is not present but with it they just ignore
+the include.
+
+Pragmas can be specified with the B<.pragma> directive.
+See L</PRAGMAS> for more information.
Each section in a configuration file consists of a number of name and
value pairs of the form B<name=value>
All expansion and escape rules as described above that apply to B<value>
also apply to the path of the B<.include> directive.
+=head1 PRAGMAS
+
+Pragmas can be used to change the behavior of the configuration file
+parser, among others. Currently supported pragmas are:
+
+=over 4
+
+=item B<.pragma> B<dollarid>:I<value>
+
+I<value> can be one of:
+
+=over 4
+
+=item B<"on"> or B<"true">
+
+this signifies that dollar signs are considered an identity character
+from this point on and that variable expansion requires the use of
+braces or parentheses. In other words, C<foo$bar> will be considered
+a name instead of C<foo> followed by the expansion of the variable
+C<bar>.
+This is suitable for platforms where the dollar sign is commonly used
+as part of names.
+
+=item B<"off"> or B<"false">
+
+Turns this pragma off, i.e. C<foo$bar> will be interpreted as C<foo>
+followed by the expansion of the variable C<bar>.
+
+=back
+
+By default, this pragma is turned off.
+
+=back
+
=head1 OPENSSL LIBRARY CONFIGURATION
Applications can automatically configure certain
The configuration section should consist of a set of name value pairs which
contain specific module configuration information. The B<name> represents
-the name of the I<configuration module> the meaning of the B<value> is
+the name of the I<configuration module>. The meaning of the B<value> is
module specific: it may, for example, represent a further configuration
-section containing configuration module specific information. E.g.
+section containing configuration module specific information. E.g.:
# This must be in the default section
openssl_conf = openssl_init
oid_section = new_oids
engines = engine_section
+ providers = provider_section
[new_oids]
... engine stuff here ...
+ [provider_section]
+
+ ... provider stuff here ...
+
The features of each configuration module are described below.
=head2 ASN1 Object Configuration Module
# Supply all default algorithms
default_algorithms = ALL
+=head2 Provider Configuration Module
+
+This provider configuration module has the name B<providers>. The
+value of this variable points to a section containing further provider
+configuration information.
+
+The section pointed to by B<providers> is a table of provider names
+(though see B<identity> below) and further sections containing
+configuration information specific to each provider module.
+
+Each provider specific section is used to load its module, perform
+activation and set parameters to pass to the provider on demand. The
+actual operation performed depends on the name of the name value pair.
+The currently supported commands are listed below.
+
+For example:
+
+ [provider_section]
+
+ # Configure provider named "foo"
+ foo = foo_section
+ # Configure provider named "bar"
+ bar = bar_section
+
+ [foo_section]
+ ... "foo" provider specific parameters ...
+
+ [bar_section]
+ ... "bar" provider specific parameters ...
+
+The command B<identity> is used to give the provider name. For example:
+
+ [provider_section]
+ # This would normally handle a provider named "foo"
+ foo = foo_section
+
+ [foo_section]
+ # Override default name and use "myfoo" instead.
+ identity = myfoo
+
+The parameter B<module> loads and adds a provider module from the
+given module path. That path may be a simple filename, a relative
+path or an absolute path.
+
+The parameter B<activate> determines whether to activate the
+provider. The value has no importance, the presence of the parameter
+is enough for activation to take place.
+
+All parameters in the section as well as sub-sections are made
+available to the provider.
+
=head2 EVP Configuration Module
-This module
s has the name B<alg_section> which points to a section containing
+This module has the name B<alg_section> which points to a section containing
algorithm commands.
-Currently the only algorithm command supported is B<fips_mode> whose
-value can only be the boolean string B<off>. If B<fips_mode> is set to B<on>,
-an error occurs as this library version is not FIPS capable.
+The supported algorithm commands are:
+
+=over 4
+
+=item B<default_properties>
+
+The value may be anything that is acceptable as a property query
+string for EVP_set_default_properties().
+
+=item B<fips_mode> (deprecated)
+
+The value is a boolean that can be B<yes> or B<no>. If the value is
+B<yes>, this is exactly equivalent to:
+
+ default_properties = fips=yes
+
+If the value is B<no>, nothing happens.
+
+=back
+
+These two commands should not be used together, as there is no control
+over how they affect each other.
+The use of B<fips_mode> is strongly discouraged and is only present
+for backward compatibility with earlier OpenSSL FIPS modules.
=head2 SSL Configuration Module
ECDSA.Certificate = server-ecdsa.pem
Ciphers = ALL:!RC4
+The system default configuration with name B<system_default> if present will
+be applied during any creation of the B<SSL_CTX> structure.
+
+Example of a configuration with the system default:
+
+ ssl_conf = ssl_sect
+
+ [ssl_sect]
+
+ system_default = system_default_sect
+
+ [system_default_sect]
+
+ MinProtocol = TLSv1.2
+
+
=head1 NOTES
If a configuration file attempts to expand a variable that doesn't exist
# This is the default section.
HOME=/temp
- RANDFILE= ${ENV::HOME}/.rnd
configdir=$ENV::HOME/config
[ section_one ]
Simple OpenSSL library configuration example to enter FIPS mode:
# Default appname: should match "appname" parameter (if any)
- # supplied to CONF_modules_load_file et al.
+ # supplied to CONF_modules_load_file_with_libctx et al.
openssl_conf = openssl_conf_section
[openssl_conf_section]
Note: in the above example you will get an error in non FIPS capable versions
of OpenSSL.
+Simple OpenSSL library configuration to make TLS 1.3 the system-default
+minimum TLS version:
+
+ # Toplevel section for openssl (including libssl)
+ openssl_conf = default_conf_section
+
+ [default_conf_section]
+ # We only specify configuration for the "ssl module"
+ ssl_conf = ssl_section
+
+ [ssl_section]
+ system_default = system_default_section
+
+ [system_default_section]
+ MinProtocol = TLSv1.3
+
More complex OpenSSL library configuration. Add OID and don't enter FIPS mode:
# Default appname: should match "appname" parameter (if any)
- # supplied to CONF_modules_load_file et al.
+ # supplied to CONF_modules_load_file_with_libctx et al.
openssl_conf = openssl_conf_section
[openssl_conf_section]
showing that the OID "newoid1" has been added as "1.2.3.4.1".
+=head1 ENVIRONMENT
+
+=over 4
+
+=item B<OPENSSL_CONF>
+
+The path to the config file.
+Ignored in set-user-ID and set-group-ID programs.
+
+=item B<OPENSSL_ENGINES>
+
+The path to the engines directory.
+Ignored in set-user-ID and set-group-ID programs.
+
+=item B<OPENSSL_MODULES>
+
+The path to the directory with OpenSSL modules, such as providers.
+Ignored in set-user-ID and set-group-ID programs.
+
+=item B<OPENSSL_CONF_INCLUDE>
+
+The optional path to prepend to all .include paths.
+
+=back
+
=head1 BUGS
Currently there is no way to include characters using the octal B<\nnn>
will only work if the variables referenced are defined earlier in the
file.
+=head1 HISTORY
+
+An undocumented API, NCONF_WIN32(), used a slightly different set
+of parsing rules there were intended to be tailored to
+the Microsoft Windows platform.
+Specifically, the backslash character was not an escape character and
+could be used in pathnames, only the double-quote character was recognized,
+and comments began with a semi-colon.
+This function was deprecated in OpenSSL 3.0; applications with
+configuration files using that syntax will have to be modified.
+
=head1 SEE ALSO
-L<x509(1)>, L<req(1)>, L<ca(1)>
+L<openssl-x509(1)>, L<openssl-req(1)>, L<openssl-ca(1)>, L<fips_config(5)>
=head1 COPYRIGHT
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
-Licensed under the OpenSSL license (the "License"). You may not use
+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>.
projects / openssl.git / blobdiff