X-Git-Url: https://git.openssl.org/?p=openssl.git;a=blobdiff_plain;f=doc%2Fman5%2Fconfig.pod;h=98b8cd331780e16454c7fcf0083a27e9a8b7e18c;hp=cac4ef6742ec7d5e37088fb1a4106ae320618a2f;hb=22e27978b29b2cdc1db79659ed653d6cf31834ab;hpb=de3955f66225e42bfae710c50b51c98aa4616ac1 diff --git a/doc/man5/config.pod b/doc/man5/config.pod index cac4ef6742..98b8cd3317 100644 --- a/doc/man5/config.pod +++ b/doc/man5/config.pod @@ -13,9 +13,9 @@ files for the B 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 -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 section. This section is usually unnamed and spans from the @@ -40,7 +40,8 @@ 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. +work as expected. The environment variable B 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 @@ -49,6 +50,9 @@ 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 for more information. + Each section in a configuration file consists of a number of name and value pairs of the form B @@ -77,6 +81,40 @@ 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 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:I + +I 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 will be considered +a name instead of C followed by the expansion of the variable +C. +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 will be interpreted as C +followed by the expansion of the variable C. + +=back + +By default, this pragma is turned off. + +=back + =head1 OPENSSL LIBRARY CONFIGURATION Applications can automatically configure certain @@ -262,7 +300,7 @@ The command B is used to give the provider name. For example: identity = myfoo The parameter B 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 determines whether to activate the @@ -378,7 +416,6 @@ mentioned above. # This is the default section. HOME=/temp - RANDFILE= ${ENV::HOME}/.rnd configdir=$ENV::HOME/config [ section_one ] @@ -418,7 +455,7 @@ priority and B used if neither is defined: 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] @@ -432,10 +469,26 @@ Simple OpenSSL library configuration example to enter FIPS mode: 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] @@ -487,6 +540,10 @@ Ignored in set-user-ID and set-group-ID programs. The path to the directory with OpenSSL modules, such as providers. Ignored in set-user-ID and set-group-ID programs. +=item B + +The optional path to prepend to all .include paths. + =back =head1 BUGS @@ -502,13 +559,24 @@ 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. +=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, L, L +L, L, L, L =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