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 section is usually unnamed and spans from the
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
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
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
+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
=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
# 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]
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
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-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2020 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
projects / openssl.git / blobdiff