doc: document that config_diagnostics is sensible but involves risk

Also:

- add this option to the sample configurations in the documentation.
- note that it is a sensible choice when using FIPS via config

Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/16172)

diff --git a/doc/man5/config.pod b/doc/man5/config.pod
index ad7d7e1e01e10e178b474adb7b6ccd6b029f1755..7bd603a2cc80c885a8733ff94090841217010b0f 100644 (file)
--- a/doc/man5/config.pod
+++ b/doc/man5/config.pod
@@ -169,10 +169,14 @@ different name by calling CONF_modules_load_file(), for example, directly.
 OpenSSL also looks up the value of B<config_diagnostics>.
 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 and should not be used in
-production.
-
- # This must be in the default section
+This is useful for diagnosing misconfigurations but its use in
+production requires additional consideration.  With this option enabled,
+a configuration error will completely prevent access to a service.
+Without this option and in the presence of a configuration error, access
+will be allowed but the desired configuration will B<not> be used.
+
+ # These must be in the default section
+ config_diagnostics = 1
  openssl_conf = openssl_init
 
  [openssl_init]

diff --git a/doc/man5/fips_config.pod b/doc/man5/fips_config.pod
index ff1b97e9626f46744ebb41781d73cadc3079b12e..50eefba6ef52912ffcb278ca1b448d25bb208a23 100644 (file)
--- a/doc/man5/fips_config.pod
+++ b/doc/man5/fips_config.pod
@@ -95,6 +95,13 @@ For example:
  install-mac = FE:10:13:5A:D3:B4:C7:82:1B:1E:17:4C:AC:84:0C
  install-status = INSTALL_SELF_TEST_KATS_RUN
 
+=head1 NOTES
+
+When using the FIPS provider, it is recommended that the
+B<config_diagnostics> option is enabled to prevent accidental use of
+non-FIPS validated algorithms via broken or mistaken configuration.
+See L<config(5)>.
+
 =head1 SEE ALSO
 
 L<config(5)>

diff --git a/doc/man7/fips_module.pod b/doc/man7/fips_module.pod
index 1d709be513e73ed9b7ccb4f6b85af46c45996d3d..b47ed279f6025e34be668b9d02a4c28c6d2c4a4f 100644 (file)
--- a/doc/man7/fips_module.pod
+++ b/doc/man7/fips_module.pod
@@ -73,6 +73,7 @@ F</usr/local/ssl/openssl.cnf>.
 
 Edit the config file to add the following lines near the beginning:
 
+    config_diagnostics = 1
     openssl_conf = openssl_init
 
     .include /usr/local/ssl/fipsmodule.cnf
@@ -91,6 +92,10 @@ Obviously the include file location above should match the path and name of the
 FIPS module config file that you installed earlier.
 See L<https://github.com/openssl/openssl/blob/master/README-FIPS.md>.
 
+For FIPS usage, it is recommened that the B<config_diagnostics> option is
+enabled to prevent accidental use of non-FIPS validated algorithms via broken
+or mistaken configuration.  See L<config(5)>.
+
 Any applications that use OpenSSL 3.0 and are started after these changes are
 made will start using only the FIPS module unless those applications take
 explicit steps to avoid this default behaviour. Note that this configuration
@@ -273,6 +278,7 @@ sets the default property value to be C<fips=yes>. Note that this config file
 does not load the "base" provider. All supporting algorithms that are in "base"
 are also in "default", so it is unnecessary in this case:
 
+    config_diagnostics = 1
     openssl_conf = openssl_init
 
     .include /usr/local/ssl/fipsmodule.cnf

diff --git a/doc/man7/provider-base.pod b/doc/man7/provider-base.pod
index f1d9f3cce3bfb2b567eabe8764fd2c4444d5cc19..92c167638b867510cf4e9fa7422c8637ff1cab03 100644 (file)
--- a/doc/man7/provider-base.pod
+++ b/doc/man7/provider-base.pod
@@ -475,6 +475,7 @@ config command name separated by periods.
 
 For example, let's say we have the following config example:
 
+ config_diagnostics = 1
  openssl_conf = openssl_init
 
  [openssl_init]