Add support for passing the libctx to the config loader

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

diff --git a/doc/man5/config.pod b/doc/man5/config.pod
index e727a2e22dc7a8c7b1bddcac56eb1f47bb425b58..98b8cd331780e16454c7fcf0083a27e9a8b7e18c 100644 (file)
--- a/doc/man5/config.pod
+++ b/doc/man5/config.pod
@@ -50,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</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>
 
@@ -78,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<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
@@ -379,7 +416,6 @@ mentioned above.
  # This is the default section.
 
  HOME=/temp
- RANDFILE= ${ENV::HOME}/.rnd
  configdir=$ENV::HOME/config
 
  [ section_one ]
@@ -419,7 +455,7 @@ priority and B</tmp> 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]
@@ -433,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]
@@ -524,7 +576,7 @@ 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