Expand and clarify SSL_CTX_config(3) docs.

- Document significant limitations in CONF_module_load_file() in OpenSSL 3.x

- Given the limitations, deëmphasise the use of CONF_module_load_file()
  in SSL_CTX_config(3) documentation, showing an example with the default
  config file instead.

Reviewed-by: Saša Nedvědický <sashan@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/28650)

doc/man3/CONF_modules_load_file.pod

@@ -33,11 +33,19 @@ If B<filename> is NULL the standard OpenSSL configuration file is used
 as determined by calling CONF_get1_default_config_file().
 If B<appname> is NULL the standard OpenSSL application name B<openssl_conf> is
 used.
-The behaviour can be customized using B<flags>. Note that, the error suppressing
-can be overridden by B<config_diagnostics> as described in L<config(5)>.
+The behaviour can be customized using B<flags>.
+Note that error handling can be customised via the configuration file's
+default section B<config_diagnostics> parameter as described in L<config(5)>.
 
 CONF_modules_load_file() is the same as CONF_modules_load_file_ex() but
 has a NULL library context.
+The global (NULL) library context is typically initialised just once at
+application startup.
+Library initialisation is typically implicit, but explicit initialisation is
+also supported by calling L<OPENSSL_init_crypto(3)> or L<OPENSSL_init_ssl(3)>,
+sufficiently early in the main program, before implicit OpenSSL library
+initialisation has taken place as a side-effect of other OpenSSL function
+calls.
 
 CONF_modules_load() is identical to CONF_modules_load_file() except it
 reads configuration information from B<cnf>.
@@ -146,6 +154,28 @@ Load and parse configuration file manually, custom error handling:
      NCONF_free(cnf);
  }
 
+=head1 BUGS
+
+In OpenSSL 3.x the CONF_modules_load_file_ex() and CONF_modules_load_file()
+functions affect some shared global state other than the specified library
+context.
+Therefore, even if used with a freshly created library context, the function
+is not thread safe, and should not be used except as part of early application
+initialisation.
+Applications that want to use multiple library contexts may find that the most
+recently loaded configuration file perturbs prior settings in other library
+contexts.
+For example, B<ssl> module settings are not library context specific, and the
+last configuration file loaded that has an C<ssl_config> setting changes the
+SSL settings for all library contexts.
+The L<SSL_CTX_config(3)> and L<SSL_config(3)> functions can be used to perform
+late customisation of SSL contexts and connection handles.
+Here I<late> means that the chosen section's settings are applied in addition
+to any initial settings from the B<ssl> module's B<system_default> section that
+are used during initial construction of the SSL context.
+This sort of fine-tuning does not involve a separate configuration file or
+library context.
+
 =head1 SEE ALSO
 
 L<config(5)>,

doc/man3/OPENSSL_init_crypto.pod

@@ -234,9 +234,9 @@ OPENSSL_thread_stop() is the same as OPENSSL_thread_stop_ex() except that the
 default OSSL_LIB_CTX is always used.
 
 The B<OPENSSL_INIT_LOAD_CONFIG> flag will load a configuration file, as with
-L<CONF_modules_load_file(3)> with NULL filename and application name and the
-B<CONF_MFLAGS_IGNORE_MISSING_FILE>, B<CONF_MFLAGS_IGNORE_RETURN_CODES>  and
-B<CONF_MFLAGS_DEFAULT_SECTION> flags.
+L<CONF_modules_load_file(3)> with, by default, NULL filename and application
+name and the B<CONF_MFLAGS_IGNORE_MISSING_FILE>,
+B<CONF_MFLAGS_IGNORE_RETURN_CODES> and B<CONF_MFLAGS_DEFAULT_SECTION> flags.
 The filename, application name, and flags can be customized by providing a
 non-null B<OPENSSL_INIT_SETTINGS> object.
 The object can be allocated via B<OPENSSL_INIT_new()>.

doc/man3/SSL_CTX_config.pod

@@ -13,8 +13,12 @@ SSL_CTX_config, SSL_config - configure SSL_CTX or SSL structure
 
 =head1 DESCRIPTION
 
-The functions SSL_CTX_config() and SSL_config() configure an B<SSL_CTX> or
-B<SSL> structure using the configuration B<name>.
+The functions SSL_CTX_config() and SSL_config() apply additional configuration
+settings to an B<SSL_CTX> or B<SSL> structure using the configuration B<name>.
+The B<name> must match a parameter in the configuration file's B<ssl> module
+section, whose value is the name of another section with SSL configuration
+commands.
+See L<SSL_CONF_cmd(3)> for a description of the available commands.
 
 By calling SSL_CTX_config() or SSL_config() an application can perform many
 complex tasks based on the contents of the configuration file: greatly
@@ -24,8 +28,10 @@ section can specify settings supported by the run-time version of OpenSSL that
 were not known at the time the application code was written.
 
 A configuration file must have been previously loaded, for example using
-CONF_modules_load_file(). See L<config(5)> for details of the configuration
-file syntax.
+CONF_modules_load_file(3).
+See L<config(5)> for details of the configuration file syntax.
+In most applications the default B<openssl.cnf> file is loaded automatically as
+part of library initialisation.
 
 =head1 RETURN VALUES
 
@@ -34,46 +40,71 @@ occurred.
 
 =head1 EXAMPLES
 
-If the file "config.cnf" contains the following:
+If, for example, the loaded configuration file contains the following:
 
- testapp = test_sect
+ # Top level "default" section, if no application name was specified as part
+ # initialisation, it defaults to "openssl_conf".
+ openssl_conf = openssl_init
 
- [test_sect]
- # list of configuration modules
+ [openssl_init]
+ # SSL module initialisation
+ ssl_conf = ssl_init
 
- ssl_conf = ssl_sect
+ [ssl_init]
+ system_default = default_ssl_settings
+ tweaks_for_tls12 = tls12_custom_settings
+ tweaks_for_tls13 = tls13_custom_settings
 
- [ssl_sect]
- server = server_section
+ [default_ssl_settings]
+ MinProtocol = TLSv1.2
+ # Defaults are typically the wisest choice, override only with good cause.
+ MinProtocol = ...
+ Ciphers = ...
+ Groups = ...
+ SignatureAlgorithms = ...
 
- [server_section]
- RSA.Certificate = server-rsa.pem
- ECDSA.Certificate = server-ecdsa.pem
- Ciphers = ALL:!RC4
+ [tls12_custom_settings]
+ # Defaults are typically the wisest choice, override only with good cause.
+ MaxProtocol = TLSv1.2
+ ...
 
-An application could call:
+ [tls13_custom_settings]
+ # Defaults are typically the wisest choice, override only with good cause.
+ MinProtocol = TLSv1.3
+ ...
 
- if (CONF_modules_load_file("config.cnf", "testapp", 0) <= 0) {
-     fprintf(stderr, "Error processing config file\n");
+An application that wants to only use "TLS 1.2" might call:
+
+ /* Initialised per "system_default" settings */
+ if ((ctx = SSL_CTX_new(TLS_server_method())) == NULL) {
+     fprintf(stderr, "Error creating the SSL context.\n");
      goto err;
  }
 
- ctx = SSL_CTX_new(TLS_server_method());
-
- if (SSL_CTX_config(ctx, "server") == 0) {
-     fprintf(stderr, "Error configuring server.\n");
+ /*
+  * Further tweaks per the "ssl" module "tweaks_for_tls12" setting, i.e. the
+  * configuration file's "tls12_custom_settings" section.
+  */
+ if (SSL_CTX_config(ctx, "tweaks_for_tls12") == 0) {
+     fprintf(stderr, "Error applying 'tweaks_for_tls12' context configuration.\n");
      goto err;
  }
 
-In this example two certificates and the cipher list are configured without
-the need for any additional application code.
+The setting of the protocol version ceiling and any other settings relevant to
+TLS 1.2 are in the configuration file, and don't need to be hard-coded in the
+application.
+Similarly, using C<tweaks_for_tls13> as the configuration B<name> applies the
+corresponding settings from the "tls13_custom_settings" section (per the SSL
+module C<tweaks_for_tls13> parameter).
 
 =head1 SEE ALSO
 
 L<ssl(7)>,
 L<config(5)>,
 L<SSL_CONF_cmd(3)>,
-L<CONF_modules_load_file(3)>
+L<SSL_CTX_new(3)>,
+L<CONF_modules_load_file(3)>,
+L<OPENSSL_init_ssl(3)>
 
 =head1 HISTORY
 

doc/man5/config.pod

@@ -162,11 +162,18 @@ I<FIPS module>, for example.
 
 The OpenSSL configuration looks up the value of B<openssl_conf>
 in the default section and takes that as the name of a section that specifies
-how to configure any modules in the library. It is not an error to leave
-any module in its default configuration. An application can specify a
-different name by calling CONF_modules_load_file(), for example, directly.
+how to configure any modules in the library.
+It is not an error to leave any module in its default configuration.
+An application can specify a name other than B<openssl_conf> by, for example,
+directly calling L<CONF_modules_load_file(3)>.
+The same can also be achieved by calling L<OPENSSL_INIT_set_config_appname(3)>
+to set a nondefault application name for use with L<OPENSSL_init_crypto(3)> or
+L<OPENSSL_init_ssl(3)>, sufficiently early in the main program, before implicit
+OpenSSL library initialisation has taken place as a side-effect of other
+OpenSSL function calls.
 
-OpenSSL also looks up the value of B<config_diagnostics>.
+OpenSSL also looks up the value of the default section's B<config_diagnostics>
+parameter.
 If this exists and has a nonzero numeric value, any error suppressing flags
 passed to CONF_modules_load() will be ignored.
 This is useful for diagnosing misconfigurations but its use in
@@ -587,6 +594,9 @@ L<ASN1_generate_nconf(3)>,
 L<EVP_set_default_properties(3)>,
 L<CONF_modules_load(3)>,
 L<CONF_modules_load_file(3)>,
+L<OPENSSL_INIT_set_config_appname(3)>,
+L<OPENSSL_init_crypto(3)>,
+L<OPENSSL_init_ssl(3)>,
 L<RAND_bytes(3)>,
 L<fips_config(5)>, and
 L<x509v3_config(5)>.