1 files changed, 172 insertions, 0 deletions
diff --git a/doc/man1/openssl-fipsinstall.pod.in b/doc/man1/openssl-fipsinstall.pod.in
new file mode 100644
index 0000000000..6ea3fca4d9
--- /dev/null
+++ b/doc/man1/openssl-fipsinstall.pod.in
@@ -0,0 +1,172 @@
+=pod
+{- OpenSSL::safe::output_do_not_edit_headers(); -}
+
+=head1 NAME
+
+openssl-fipsinstall - perform FIPS configuration installation
+
+=head1 SYNOPSIS
+
+B<openssl fipsinstall>
+[B<-help>]
+[B<-in> I<configfilename>]
+[B<-out> I<configfilename>]
+[B<-module> I<modulefilename>]
+[B<-provider_name> I<providername>]
+[B<-section_name> I<sectionname>]
+[B<-verify>]
+[B<-mac_name> I<macname>]
+[B<-macopt> I<nm>:I<v>]
+[B<-noout>]
+[B<-corrupt_desc> I<selftest_description>]
+[B<-corrupt_type> I<selftest_type>]
+
+=head1 DESCRIPTION
+
+This command is used to generate a FIPS module configuration file.
+The generated configuration file consists of:
+
+=over 4
+
+=item - A mac of the FIPS module file.
+
+=item - A status indicator that indicates if the known answer Self Tests (KAT's)
+have successfully run.
+
+=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.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Print a usage message.
+
+=item B<-module> I<filename>
+
+Filename of a 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.
+
+=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 '-'.
+
+=item B<-verify>
+
+Verify that the input configuration file contains the correct information
+
+=item B<-provider_name> I<providername>
+
+Name of the provider inside the configuration file.
+
+=item B<-section_name> I<sectionname>
+
+Name of the section inside the configuration file.
+
+=item B<-mac_name> I<name>
+
+Specifies the name of a supported MAC algorithm which will be used.
+To see the list of supported MAC's use the command
+C<openssl list -mac-algorithms>.  The default is B<HMAC>.
+
+=item B<-macopt> I<nm>:I<v>
+
+Passes options to the MAC algorithm.
+A comprehensive list of controls can be found in the EVP_MAC implementation
+documentation.
+Common control strings used for fipsinstall are:
+
+=over 4
+
+=item B<key>:I<string>
+
+Specifies the MAC key as an alphanumeric string (use if the key contains
+printable characters only).
+The string length must conform to any restrictions of the MAC algorithm.
+A key must be specified for every MAC algorithm.
+
+=item B<hexkey>:I<string>
+
+Specifies the MAC key in hexadecimal form (two hex digits per byte).
+The key length must conform to any restrictions of the MAC algorithm.
+A key must be specified for every MAC algorithm.
+
+=item B<digest>:I<string>
+
+Used by HMAC as an alphanumeric string (use if the key contains printable
+characters only).
+The string length must conform to any restrictions of the MAC algorithm.
+To see the list of supported digests, use the command
+C<openssl list -digest-commands>.
+
+=back
+
+=item B<-noout>
+
+Disable logging of the self tests.
+
+=item B<-corrupt_desc> I<selftest_description>
+
+=item B<-corrupt_type> I<selftest_type>
+
+The corrupt options can be used to test failure of one or more self test(s) 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
+values that can be used.
+
+=back
+
+=head1 EXAMPLES
+
+Calculate the mac of a FIPS module F<fips.so> and run a FIPS self test
+for the module, and save the F<fips.cnf> configuration file:
+
+ openssl fipsinstall -module ./fips.so -out fips.cnf -provider_name fips \
+         -section_name fipsinstall -mac_name HMAC -macopt digest:SHA256 \
+         -macopt hexkey:000102030405060708090A0B0C0D0E0F10111213
+
+Verify that the configuration file F<fips.cnf> contains the correct info:
+
+ openssl fipsinstall -module ./fips.so -in fips.cnf  -provider_name fips \
+          -section_name fips_install -mac_name HMAC -macopt digest:SHA256 \
+          -macopt hexkey:000102030405060708090A0B0C0D0E0F10111213 -verify
+
+Corrupt any self tests which have the description '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.
+
+=head1 SEE ALSO
+
+L<fips_config(5)>,
+L<OSSL_PROVIDER-FIPS(7)>,
+L<EVP_MAC(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut