alphanumeric characters and underscores.
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.
Comments can be included by preceding them with the B<#> character
+Other files can be included using the B<.include> directive followed
+by a path. If the path points to a directory all files with
+names ending with B<.cnf> or B<.conf> are included from the directory.
+Recursive inclusion of directories from files in such directory is not
+supported. That means the files in the included directory can also contain
+B<.include> directives but only inclusion of regular files is supported
+there. The inclusion of directories is not supported on systems without
+POSIX IO support.
+
+It is strongly recommended to use absolute paths with the B<.include>
+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.
+
+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.
+
Each section in a configuration file consists of a number of name and
value pairs of the form B<name=value>
a B<value> string can be spread across multiple lines. In addition
the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognized.
+All expansion and escape rules as described above that apply to B<value>
+also apply to the path of the B<.include> directive.
+
=head1 OPENSSL LIBRARY CONFIGURATION
Applications can automatically configure certain
To enable library configuration the default section needs to contain an
appropriate line which points to the main configuration section. The default
name is B<openssl_conf> which is used by the B<openssl> utility. Other
-applications may use an alternative name such as B<myapplicaton_conf>.
+applications may use an alternative name such as B<myapplication_conf>.
+All library configuration lines appear in the default section at the start
+of the configuration file.
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
[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 file name, 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
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.
+
+=back
+
=head1 BUGS
Currently there is no way to include characters using the octal B<\nnn>
=head1 COPYRIGHT
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2018 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