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>.
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)>,
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()>.
=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
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
=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
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.
-
-OpenSSL also looks up the value of B<config_diagnostics>.
+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 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
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)>.
projects / thirdparty / openssl.git / commitdiff
