Add FIPS indicator documentation

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/25195)

3 files changed, 268 insertions, 32 deletions

diff --git a/CHANGES.md b/CHANGES.md
index 9db980e142..a762dcb8f6 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -29,6 +29,28 @@ OpenSSL 3.4
 
 ### Changes between 3.3 and 3.4 [xx XXX xxxx]
 
+ * Add FIPS indicators to the FIPS provider.
+   FIPS 140-3 requires indicators to be used if the FIPS provider allows
+   non-approved algorithms. An algorithm is approved if it passes all
+   required checks such as minimum key size. By default an error will
+   occur if any check fails. For backwards compatibility individual
+   algorithms may override the checks by using either an option in the
+   FIPS configuration OR in code using an algorithm context setter.
+   Overriding the check means that the algorithm is not FIPS compliant.
+   OSSL_INDICATOR_set_callback() can be called to register a callback
+   to log unapproved algorithms. At the end of any algorithm operation
+   the approved status can be queried using an algorithm context getter.
+   FIPS provider configuration options are set using 'openssl fipsinstall'.
+
+   Note that new FIPS 140-3 restrictions have been enforced such as
+   RSA Encryption using PKCS1 padding is no longer approved.
+   Documentation related to the changes can be found on the [fips_module(7)]
+   manual page.
+
+   [fips_module(7)]: https://docs.openssl.org/master/man7/fips_module/#FIPS indicators
+
+   *Shane Lontis, Paul Dale and Po-Hsing Wu*
+
  * Add debuginfo Makefile target for unix platforms to produce
    a separate DWARF info file from the corresponding shared libs.
 
@@ -39,12 +61,6 @@ OpenSSL 3.4
 
    *Michael Baentsch*
 
- * Add FIPS provider configuration option to enforce the a minimal
-   MAC length check.  The option '-no_short_mac' can optionally be
-   supplied to 'openssl fipsinstall'.
-
-   *Paul Dale*
-
  * Redesigned Windows use of OPENSSLDIR/ENGINESDIR/MODULESDIR such that
    what were formerly build time locations can now be defined at run time
    with registry keys. See NOTES-WINDOWS.md
diff --git a/doc/man5/fips_config.pod b/doc/man5/fips_config.pod
index cd0012a73a..5d99b80366 100644
--- a/doc/man5/fips_config.pod
+++ b/doc/man5/fips_config.pod
@@ -39,10 +39,6 @@ section, as described in L<config(5)/Provider Configuration Module>.
 If present, the module is activated. The value assigned to this name is not
 significant.
 
-=item B<install-version>
-
-A version number for the fips install process. Should be 1.
-
 =item B<conditional-errors>
 
 The FIPS module normally enters an internal error mode if any self test fails.
@@ -56,18 +52,14 @@ Regardless of the value, the operation (e.g., key generation) that called the
 continuous test will return an error code if its continuous test fails. The
 operation may then be retried if the error mode has not been triggered.
 
-=item B<security-checks>
-
-This indicates if run-time checks related to enforcement of security parameters
-such as minimum security strength of keys and approved curve names are used.
-A value of '1' will perform the checks, otherwise if the value is '0' the checks
-are not performed and FIPS compliance must be done by procedures documented in
-the relevant Security Policy.
-
 =item B<module-mac>
 
 The calculated MAC of the FIPS provider file.
 
+=item B<install-version>
+
+A version number for the fips install process. Should be 1.
+
 =item B<install-status>
 
 An indicator that the self-tests were successfully run.
@@ -84,6 +76,130 @@ It is written-to at the same time as B<install-status> is updated.
 
 =back
 
+=head2 FIPS indicator options
+
+The following FIPS configuration options indicate if run-time checks related to
+enforcement of FIPS security parameters such as minimum security strength of
+keys and approved curve names are used.
+A value of '1' will perform the checks, otherwise if the value is '0' the checks
+are not performed and FIPS compliance must be done by procedures documented in
+the relevant Security Policy.
+
+See L<openssl-fipsinstall(1)/OPTIONS> for further information related to these
+options.
+
+=over 4
+
+=item B<security-checks>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-no_security_checks>
+
+=item B<tls1-prf-ems-check>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-ems_check>
+
+=item B<no-short-mac>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-no_short_mac>
+
+=item B<drbg-no-trunc-md>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-no_drbg_truncated_digests>
+
+=item B<signature-digest-check>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-signature_digest_check>
+
+=item B<hkdf-digest-check>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-hkdf_digest_check>
+
+=item B<tls13-kdf-digest-check>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-tls13_kdf_digest_check>
+
+=item B<tls1-prf-digest-check>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-tls1_prf_digest_check>
+
+=item B<sshkdf-digest-check>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-sshkdf_digest_check>
+
+=item B<sskdf-digest-check>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-sskdf_digest_check>
+
+=item B<x963kdf-digest-check>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-x963kdf_digest_check>
+
+=item B<dsa-sign-disabled>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-dsa_sign_disabled>
+
+=item B<tdes-encrypt-disabled>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-tdes_encrypt_disabled>
+
+=item B<rsa-pkcs15-pad-disabled>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-rsa_pkcs15_pad_disabled>
+
+=item B<rsa-pss-saltlen-check>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-rsa_pss_saltlen_check>
+
+=item B<rsa-sign-x931-pad-disabled>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-rsa_sign_x931_disabled>
+
+=item B<hkdf-key-check>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-hkdf_key_check>
+
+=item B<kbkdf-key-check>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-kbkdf_key_check>
+
+=item B<tls13-kdf-key-check>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-tls13_kdf_key_check>
+
+=item B<tls1-prf-key-check>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-tls1_prf_key_check>
+
+=item B<sshkdf-key-check>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-sshkdf_key_check>
+
+=item B<sskdf-key-check>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-sskdf_key_check>
+
+=item B<x963kdf-key-check>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-x963kdf_key_check>
+
+=item B<pbkdf2-lower-bound-check>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-no_pbkdf2_lower_bound_check>
+
+=item B<ecdh-cofactor-check>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-ecdh_cofactor_check>
+
+=item B<hmac-key-check>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-hmac_key_check>
+
+=item B<kmac-key-check>
+
+See L<openssl-fipsinstall(1)/OPTIONS> B<-kmac_key_check>
+
+=back
+
 For example:
 
  [fips_sect]
diff --git a/doc/man7/fips_module.pod b/doc/man7/fips_module.pod
index 249588598b..fc89f89e00 100644
--- a/doc/man7/fips_module.pod
+++ b/doc/man7/fips_module.pod
@@ -471,6 +471,119 @@ use L<EVP_MD_get0_provider(3)>.
 To extract the name from the B<OSSL_PROVIDER>, use
 L<OSSL_PROVIDER_get0_name(3)>.
 
+=head2 FIPS indicators
+
+FIPS indicators have been added to the FIPS provider in OpenSSL 3.4.
+FIPS 140-3 requires indicators to be used if the FIPS provider allows non
+approved algorithms. An algorithm is approved if it passes all required checks
+such as minimum key size. By default an error will occur if any check fails.
+For backwards compatibility individual algorithms may override the checks by
+using either an option in the FIPS configuration (See
+L<fips_config(5)/FIPS indicator options>) OR in code using an algorithm context
+setter. Overriding the check means that the algorithm is not FIPS compliant.
+L<OSSL_INDICATOR_set_callback(3)> can be called to register a callback to log
+unapproved algorithms. At the end of any algorithm operation the approved status
+can be queried using an algorithm context getter to retrieve the indicator
+(e.g. "fips-indicator").
+An example of an algorithm context setter is "key-check"
+in L<EVP_KDF-HKDF(7)/Supported parameters>.
+
+The following algorithms use "fips-indicator" to query if the algorithm
+is approved:
+
+=over 4
+
+=item DSA Key generation
+
+DSA Key generation is no longer approved.
+See L<EVP_PKEY-DSA(7)/DSA parameters>
+
+=item DSA Signatures
+
+DSA Signature generation is no longer approved.
+See L<EVP_SIGNATURE-DSA(7)/Signature Parameters>
+
+=item ECDSA Signatures
+
+See L<EVP_SIGNATURE-ECDSA(7)/ECDSA Signature Parameters>
+
+=item EC Key Generation
+
+See L<EVP_PKEY-EC(7)/Common EC parameters>
+
+=item RSA Encryption
+
+"pkcs1" padding is no longer approved.
+
+See L<EVP_ASYM_CIPHER-RSA(7)/RSA Asymmetric Cipher parameters> and 
+L<EVP_KEM-RSA(7)/RSA KEM parameters>
+
+=item RSA Signatures
+
+See L<EVP_SIGNATURE-RSA(7)/Signature Parameters>
+
+=item DRBGS
+
+See L<EVP_RAND-HASH-DRBG(7)/Supported parameters> and
+EVP_RAND-HMAC-DRBG(7)/Supported parameters>
+
+=item DES
+
+Triple-DES is not longer approved for encryption.
+See L<EVP_CIPHER-DES(7)/Parameters>
+
+=item DH
+
+See L<EVP_KEYEXCH-DH(7)/DH and DHX key exchange parameters>
+
+=item ECDH
+
+See L<EVP_KEYEXCH-ECDH(7)/ECDH Key Exchange parameters>
+
+=item KDFS
+
+See relevant KDF documentation e.g. L<EVP_KDF-HKDF(7)/Supported parameters>
+
+=item CMAC and KMAC
+
+See L<EVP_MAC-CMAC(7)/Supported parameters> and
+L<EVP_MAC-KMAC(7)/Supported parameters>
+
+=back
+
+The following FIPS algorithms are unapproved and use the "fips-indicator".
+
+=over 4
+
+=item RAND-TEST-RAND
+
+See L<EVP_RAND-TEST-RAND(7)/Supported parameters>
+The indicator callback is NOT triggered for this algorithm since it is used
+internally for non security purposes.
+
+=item X25519 and X448 Key Generation and Key Exchange
+
+=back
+
+The unapproved (non FIPS validated) algorithms have a property query value of
+"fips=no".
+
+The following algorithms use a unique indicator and do not trigger the
+indicator callback.
+
+=over 4
+
+=item AES-GCM ciphers support the indicator "iv-generated"
+
+See L<EVP_EncryptInit(3)/PARAMETERS> for further information.
+
+=item ECDSA and RSA Signatures support the indicator "verify-message".
+
+See L<EVP_SIGNATURE-ECDSA(7)/ECDSA Signature Parameters> and
+L<EVP_SIGNATURE-RSA(7)/Signature Parameters> /for further information.
+
+=back
+
 =head1 NOTES
 
 Some released versions of OpenSSL do not include a validated
@@ -484,19 +597,9 @@ validated versions alongside F<libcrypto> and F<libssl> compiled from any
 release within the same major release series.  This flexibility enables
 you to address bug fixes and CVEs that fall outside the FIPS boundary.
 
-The FIPS provider in OpenSSL 3.1 includes some non-FIPS validated algorithms,
-consequently the property query C<fips=yes> is mandatory for applications that
-want to operate in a FIPS approved manner.  The algorithms are:
-
-=over 4
-
-=item Triple DES ECB
-
-=item Triple DES CBC
-
-=item EdDSA
-
-=back
+As the FIPS provider still supports non-FIPS validated algorithms,
+The property query C<fips=yes> is mandatory for applications that
+want to operate in a FIPS approved manner.
 
 =head1 SEE ALSO
 
@@ -507,10 +610,11 @@ L<https://www.openssl.org/source/>
 
 The FIPS module guide was created for use with the new FIPS provider
 in OpenSSL 3.0.
+FIPS indicators were added in OpenSSL 3.4.
 
 =head1 COPYRIGHT
 
-Copyright 2021-2023 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2021-2024 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy