From: Viktor Dukhovni Date: Mon, 17 Nov 2025 08:04:58 +0000 (+1100) Subject: Expand and clarify SSL_CTX_config(3) docs. X-Git-Tag: 4.0-PRE-CLANG-FORMAT-WEBKIT~145 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fb43a0ac5a520e55c481bfdfab07c9b01bd60df2;p=thirdparty%2Fopenssl.git 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ý Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/28650) --- diff --git a/doc/man3/CONF_modules_load_file.pod b/doc/man3/CONF_modules_load_file.pod index ce9aa9cf944..86de1678019 100644 --- a/doc/man3/CONF_modules_load_file.pod +++ b/doc/man3/CONF_modules_load_file.pod @@ -33,11 +33,19 @@ If B is NULL the standard OpenSSL configuration file is used as determined by calling CONF_get1_default_config_file(). If B is NULL the standard OpenSSL application name B is used. -The behaviour can be customized using B. Note that, the error suppressing -can be overridden by B as described in L. +The behaviour can be customized using B. +Note that error handling can be customised via the configuration file's +default section B parameter as described in L. 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 or L, +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. @@ -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 module settings are not library context specific, and the +last configuration file loaded that has an C setting changes the +SSL settings for all library contexts. +The L and L functions can be used to perform +late customisation of SSL contexts and connection handles. +Here I means that the chosen section's settings are applied in addition +to any initial settings from the B module's B 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, diff --git a/doc/man3/OPENSSL_init_crypto.pod b/doc/man3/OPENSSL_init_crypto.pod index 1363693c779..c06e81500e5 100644 --- a/doc/man3/OPENSSL_init_crypto.pod +++ b/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 flag will load a configuration file, as with -L with NULL filename and application name and the -B, B and -B flags. +L with, by default, NULL filename and application +name and the B, +B and B flags. The filename, application name, and flags can be customized by providing a non-null B object. The object can be allocated via B. diff --git a/doc/man3/SSL_CTX_config.pod b/doc/man3/SSL_CTX_config.pod index 9b1eb3e3267..8d79b7d7315 100644 --- a/doc/man3/SSL_CTX_config.pod +++ b/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 or -B structure using the configuration B. +The functions SSL_CTX_config() and SSL_config() apply additional configuration +settings to an B or B structure using the configuration B. +The B must match a parameter in the configuration file's B module +section, whose value is the name of another section with SSL configuration +commands. +See L 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 for details of the configuration -file syntax. +CONF_modules_load_file(3). +See L for details of the configuration file syntax. +In most applications the default B 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 as the configuration B applies the +corresponding settings from the "tls13_custom_settings" section (per the SSL +module C parameter). =head1 SEE ALSO L, L, L, -L +L, +L, +L =head1 HISTORY diff --git a/doc/man5/config.pod b/doc/man5/config.pod index e24ea0c5954..7a8480bd102 100644 --- a/doc/man5/config.pod +++ b/doc/man5/config.pod @@ -162,11 +162,18 @@ I, for example. The OpenSSL configuration looks up the value of B 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. - -OpenSSL also looks up the value of B. +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 by, for example, +directly calling L. +The same can also be achieved by calling L +to set a nondefault application name for use with L or +L, 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 the default section's B +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, L, L, L, +L, +L, +L, L, L, and L.