Revise fips_install.pod

Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/11369)

1 files changed, 26 insertions, 22 deletions

diff --git a/doc/man1/openssl-fipsinstall.pod.in b/doc/man1/openssl-fipsinstall.pod.in
index 1d1cdea715..7675e5e397 100644
--- a/doc/man1/openssl-fipsinstall.pod.in
+++ b/doc/man1/openssl-fipsinstall.pod.in
@@ -25,20 +25,26 @@ B<openssl fipsinstall>
 =head1 DESCRIPTION
 
 This command is used to generate a FIPS module configuration file.
+This configuration file can be used each time a FIPS module is loaded
+in order to pass data to the FIPS module self tests. The FIPS module always
+verifies its MAC, but only needs to run the KAT's once,
+at installation.
+
 The generated configuration file consists of:
 
 =over 4
 
-=item - A mac of the FIPS module file.
+=item - A MAC of the FIPS module file.
+
+=item - A test status indicator.
 
-=item - A status indicator that indicates if the known answer Self Tests (KAT's)
-have successfully run.
+This indicates if the Known Answer Self Tests (KAT's) have successfully run.
+
+=item - A MAC of the status indicator.
 
 =back
 
-This configuration file can be used each time a FIPS module is loaded
-in order to pass data to the FIPS modules self tests. The FIPS module always
-verifies the modules MAC, but only needs to run the KATS once during install.
+This file is described in L<fips_config(5)>.
 
 =head1 OPTIONS
 
@@ -50,32 +56,36 @@ Print a usage message.
 
 =item B<-module> I<filename>
 
-Filename of a fips module to perform an integrity check on.
+Filename of the FIPS module to perform an integrity check on.
 
 =item B<-out> I<configfilename>
 
-Filename to output the configuration data to, or standard output by default.
+Filename to output the configuration data to; the default is standard output.
 
 =item B<-in> I<configfilename>
 
-Input filename to load configuration data from. Used with the '-verify' option.
-Standard input is used if the filename is '-'.
+Input filename to load configuration data from. Used with the B<-verify> option.
+Standard input is used if the filename is C<->.
 
 =item B<-verify>
 
-Verify that the input configuration file contains the correct information
+Verify that the input configuration file contains the correct information.
 
 =item B<-provider_name> I<providername>
 
 Name of the provider inside the configuration file.
+This must be specified.
 
 =item B<-section_name> I<sectionname>
 
 Name of the section inside the configuration file.
+This must be specified.
 
 =item B<-mac_name> I<name>
 
 Specifies the name of a supported MAC algorithm which will be used.
+The MAC mechanisms that are available will depend on the options
+used when building OpenSSL.
 To see the list of supported MAC's use the command
 C<openssl list -mac-algorithms>.  The default is B<HMAC>.
 
@@ -122,10 +132,10 @@ Do not output pass/fail messages. Implies B<-noout>.
 =item B<-corrupt_desc> I<selftest_description>,
 B<-corrupt_type> I<selftest_type>
 
-The corrupt options can be used to test failure of one or more self test(s) by
+The corrupt options can be used to test failure of one or more self tests by
 name.
-Either option or both may be used to select the self test(s) to corrupt.
-Refer to the entries for "st-desc" and "st-type" in L<OSSL_PROVIDER-FIPS(7)> for
+Either option or both may be used to select the tests to corrupt.
+Refer to the entries for B<st-desc> and B<st-type> in L<OSSL_PROVIDER-FIPS(7)> for
 values that can be used.
 
 =back
@@ -145,18 +155,12 @@ Verify that the configuration file F<fips.cnf> contains the correct info:
           -section_name fips_install -mac_name HMAC -macopt digest:SHA256 \
           -macopt hexkey:000102030405060708090A0B0C0D0E0F10111213 -verify
 
-Corrupt any self tests which have the description 'SHA1':
+Corrupt any self tests which have the description C<SHA1>:
 
  openssl fipsinstall -module ./fips.so -out fips.cnf -provider_name fips \
          -section_name fipsinstall -mac_name HMAC -macopt digest:SHA256 \
          -macopt hexkey:000102030405060708090A0B0C0D0E0F10111213 \
-         -corrupt_desc', 'SHA1'
-
-=head1 NOTES
-
-The MAC mechanisms that are available will depend on the options
-used when building OpenSSL.
-The command C<openssl list -mac-algorithms> command can be used to list them.
+         -corrupt_desc 'SHA1'
 
 =head1 SEE ALSO