Add a .pragma directive for configuration files

[openssl.git] / doc / man5 / config.pod

diff --git a/doc/man5/config.pod b/doc/man5/config.pod
index 24ebafb5332eebb0d1112a5800f2d2b59228c650..4b8465594af2b288edea3c4479c101e4a40fa992 100644 (file)
--- a/doc/man5/config.pod
+++ b/doc/man5/config.pod
@@ -13,12 +13,12 @@ files for the B<x509> utility. OpenSSL applications can also use the
 CONF library for their own purposes.
 
 A configuration file is divided into a number of sections. Each section
 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
 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
 
 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.
 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.


@@ -27,6 +27,32 @@ The environment is mapped onto a section called B<ENV>.
 
 Comments can be included by preceding them with the B<#> character
 
 
 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. 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 mor information.
+

 Each section in a configuration file consists of a number of name and
 value pairs of the form B<name=value>
 
 Each section in a configuration file consists of a number of name and
 value pairs of the form B<name=value>
 


@@ -44,13 +70,51 @@ or B<${section::name}>. By using the form B<$ENV::name> environment
 variables can be substituted. It is also possible to assign values to
 environment variables by using the name B<ENV::name>, this will work
 if the program looks up environment variables using the B<CONF> library
 variables can be substituted. It is also possible to assign values to
 environment variables by using the name B<ENV::name>, this will work
 if the program looks up environment variables using the B<CONF> library

-instead of calling getenv() directly.
+instead of calling getenv() directly. The value string must not exceed 64k in
+length after variable expansion. Otherwise an error will occur.

 
 It is possible to escape certain characters by using any kind of quote
 or the B<\> character. By making the last character of a line a B<\>
 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.
 
 
 It is possible to escape certain characters by using any kind of quote
 or the B<\> character. By making the last character of a line a B<\>
 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 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
 =head1 OPENSSL LIBRARY CONFIGURATION
 
 Applications can automatically configure certain


@@ -63,20 +127,24 @@ file.
 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
 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 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
 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
  openssl_conf = openssl_init
 
  [openssl_init]
 
  oid_section = new_oids
  engines = engine_section

+ providers = provider_section

 
  [new_oids]
 
 
  [new_oids]
 


@@ -86,6 +154,10 @@ section containing configuration module specific information. E.g.
 
  ... engine stuff here ...
 
 
  ... engine stuff here ...
 

+ [provider_section]
+
+ ... provider stuff here ...
+

 The features of each configuration module are described below.
 
 =head2 ASN1 Object Configuration Module
 The features of each configuration module are described below.
 
 =head2 ASN1 Object Configuration Module


@@ -187,14 +259,86 @@ For example:
  # Supply all default algorithms
  default_algorithms = ALL
 
  # 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
 
 =head2 EVP Configuration Module
 

-This modules 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.
 
 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
 
 
 =head2 SSL Configuration Module
 


@@ -225,6 +369,22 @@ For example:
  ECDSA.Certificate = server-ecdsa.pem
  Ciphers = ALL:!RC4
 
  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
 =head1 NOTES
 
 If a configuration file attempts to expand a variable that doesn't exist


@@ -346,6 +506,31 @@ will output:
 
 showing that the OID "newoid1" has been added as "1.2.3.4.1".
 
 
 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>
 =head1 BUGS
 
 Currently there is no way to include characters using the octal B<\nnn>


@@ -359,15 +544,26 @@ Files are loaded in a single pass. This means that an variable expansion
 will only work if the variables referenced are defined earlier in the
 file.
 
 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
 
 =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
 
 
 =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>.
 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>.