From: Pauli <pauli@openssl.org>
Date: Thu, 29 Jul 2021 01:39:01 +0000 (+1000)
Subject: doc: document that config_diagnostics is sensible but involves risk
X-Git-Tag: openssl-3.0.0~172
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=5540855bda5e58f4b33f2306feb6ff4e93c0af81;p=thirdparty%2Fopenssl.git

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 ad7d7e1e01e..7bd603a2cc8 100644
--- 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 ff1b97e9626..50eefba6ef5 100644
--- 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 1d709be513e..b47ed279f60 100644
--- 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 f1d9f3cce3b..92c167638b8 100644
--- 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]