From ca17a6ec5632dcae63f408c4bd9acb6d92d03936 Mon Sep 17 00:00:00 2001
From: Rich Salz <rsalz@akamai.com>
Date: Thu, 19 Mar 2020 10:19:41 -0400
Subject: [PATCH] Revise fips_config.pod

Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/11369)
---
 doc/man5/fips_config.pod | 40 +++++++++++++++++++++++++---------------
 1 file changed, 25 insertions(+), 15 deletions(-)

diff --git a/doc/man5/fips_config.pod b/doc/man5/fips_config.pod
index 0fb7e3ef1e..746d68c8ac 100644
--- a/doc/man5/fips_config.pod
+++ b/doc/man5/fips_config.pod
@@ -6,26 +6,36 @@ fips_config - OpenSSL FIPS configuration
 
 =head1 DESCRIPTION
 
-A separate configuration file containing data related to FIPS 'self tests' is
-written to during installation time.
-This data is used for 2 purposes when the fips module is loaded:
+A separate configuration file, using the OpenSSL L<config(5)> syntax,
+is used to hold information about the FIPS module. This includes a digest
+of the shared library file, and status about the self-testing.
+This data is used automatically by the module itself for two
+purposes:
 
 =over 4
 
-=item - Verify the module's checksum each time the fips module loads.
+=item - Run the startup FIPS self-test known answer tests (KATS).
 
-=item - Run the startup FIPS self test KATS (known answer tests).
-This only needs to be run once during installation.
+This is done once, at installation time.
+
+=item - Verify the module's checksum.
+
+This is done each time the module is used.
 
 =back
 
-The supported options are:
+This file is generated by the L<openssl-fipsinstall(1)> program, and
+used internally by the FIPS module during its initialization.
+
+The following options are supported. They should all appear in a section
+whose name is identified by the B<fips> option in the B<providers>
+section, as desribed in L<config(5)/Provider Configuration Module>.
 
 =over 4
 
 =item B<module-checksum>
 
-The calculated MAC of the module file
+The calculated digest of the module file.
 
 =item B<install-version>
 
@@ -33,23 +43,23 @@ A version number for the fips install process. Should be 1.
 
 =item B<install-status>
 
-The install status indicator description that will be verified.
-If this field is not present the FIPS self tests will run when the fips module
-loads.
-This value should only be written to after the FIPS module has
+An indicator that the self-tests were run.
+This should only be written after the module has
 successfully passed its self tests during installation.
+If this field is not present, then the self tests will run when the module
+loads.
 
 =item B<install-checksum>
 
-The calculated MAC of the install status indicator.
-It is initially empty and is written to at the same time as the install_status.
+A MAC on the value of the B<install-status> option, to prevent accidental
+changes to that value.
+It is written-to at the same time as B<install-status> is updated.
 
 =back
 
 For example:
 
  [fips_install]
-
  install-version = 1
  module-checksum = 41:D0:FA:C2:5D:41:75:CD:7D:C3:90:55:6F:A4:DC
  install-checksum = FE:10:13:5A:D3:B4:C7:82:1B:1E:17:4C:AC:84:0C
-- 
2.39.2