From 8e7f39e8830ccafb41e52fbea895cb9740cebaec Mon Sep 17 00:00:00 2001 From: slontis Date: Thu, 15 Aug 2024 16:20:26 +1000 Subject: [PATCH] Cleanups for FIPS indicator documentation Reviewed-by: Tomas Mraz Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/25195) --- doc/man3/EVP_EncryptInit.pod | 8 +++- doc/man7/EVP_ASYM_CIPHER-RSA.pod | 26 +++++++++---- doc/man7/EVP_KDF-HKDF.pod | 15 +++++--- doc/man7/EVP_KDF-KB.pod | 15 +++++--- doc/man7/EVP_KDF-PBKDF2.pod | 11 +++--- doc/man7/EVP_KDF-SS.pod | 15 +++++--- doc/man7/EVP_KDF-SSHKDF.pod | 15 +++++--- doc/man7/EVP_KDF-TLS13_KDF.pod | 63 +++++++++++++++++-------------- doc/man7/EVP_KDF-TLS1_PRF.pod | 19 ++++++---- doc/man7/EVP_KDF-X963.pod | 15 +++++--- doc/man7/EVP_KEYEXCH-ECDH.pod | 13 +++++-- doc/man7/EVP_MAC-CMAC.pod | 11 ++++-- doc/man7/EVP_PKEY-DSA.pod | 22 ++++++++++- doc/man7/EVP_RAND-HASH-DRBG.pod | 6 +++ doc/man7/EVP_RAND-HMAC-DRBG.pod | 6 +++ doc/man7/EVP_SIGNATURE-DSA.pod | 8 ++++ doc/man7/EVP_SIGNATURE-RSA.pod | 24 ++++++++---- doc/man7/provider-asym_cipher.pod | 11 ++++-- doc/man7/provider-kem.pod | 10 ++--- doc/man7/provider-keyexch.pod | 15 +++++--- doc/man7/provider-keymgmt.pod | 29 ++++++++------ doc/man7/provider-mac.pod | 22 +++++------ doc/man7/provider-rand.pod | 11 ++++-- doc/man7/provider-signature.pod | 23 +++++++---- 24 files changed, 274 insertions(+), 139 deletions(-) diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod index 8e1e0e9e31..3a09ab4434 100644 --- a/doc/man3/EVP_EncryptInit.pod +++ b/doc/man3/EVP_EncryptInit.pod @@ -901,6 +901,8 @@ Used to pass the TLS MAC data. =item "fips-indicator" (B) +This option is used by the OpenSSL FIPS provider. + A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling a cipher final operation such as EVP_EncryptFinal_ex(). It may return 0 if the "encrypt-check" option is set to 0. @@ -1063,13 +1065,15 @@ The default value is "GB". =item "encrypt-check" (B) +This option is used by the OpenSSL FIPS provider. + If required this parameter should be set early via an cipher encrypt init function such as EVP_EncryptInit_ex2(). The default value of 1 causes an error when an encryption operation is triggered. Setting this to 0 will ignore the error and set the approved "fips-indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =back diff --git a/doc/man7/EVP_ASYM_CIPHER-RSA.pod b/doc/man7/EVP_ASYM_CIPHER-RSA.pod index 91de46d80d..d26fb93a7a 100644 --- a/doc/man7/EVP_ASYM_CIPHER-RSA.pod +++ b/doc/man7/EVP_ASYM_CIPHER-RSA.pod @@ -65,10 +65,6 @@ See L for further details. =item "oaep-label" (B) -=item "fips-indicator" (B) - -=item "key-check" (B) - =item "tls-client-version" (B) See B on the page L. @@ -79,10 +75,26 @@ See B on the page L See L for more information. -=item "pkcs15-padding-disabled" (B) +=back -If nonzero, PKCS#1 version 1.5 padding is disabled. -This option is used by the OpenSSL FIPS provider. +The OpenSSL FIPS provider also supports the following parameters: + +=over 4 + +=item "fips-indicator" (B) + +=item "key-check" (B) + +See L for more information. + +=item "pkcs15-pad-disabled" (B) + +The default value of 1 causes an error during encryption if the RSA padding +mode is set to "pkcs1". +Setting this to zero will ignore the error and set the approved +"fips-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =back diff --git a/doc/man7/EVP_KDF-HKDF.pod b/doc/man7/EVP_KDF-HKDF.pod index 15171e8299..0778ba04f9 100644 --- a/doc/man7/EVP_KDF-HKDF.pod +++ b/doc/man7/EVP_KDF-HKDF.pod @@ -80,12 +80,17 @@ an error will occur. =back +=back + +The OpenSSL FIPS provider also supports the following parameters: + +=over 4 + =item "fips-indicator" (B) A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. -This may be used after calling EVP_KDF_derive. It returns 0 if any "***-check" -related parameter is set to 0 and the check fails. -This option is used by the OpenSSL FIPS provider. +This may be used after calling EVP_KDF_derive. It returns 0 if "key-check" +is set to 0 and the check fails. =item "key-check" (B) @@ -94,8 +99,8 @@ length of used key-derivation key (B) is shorter than 112 bits. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =back diff --git a/doc/man7/EVP_KDF-KB.pod b/doc/man7/EVP_KDF-KB.pod index e698175941..af75c7ac02 100644 --- a/doc/man7/EVP_KDF-KB.pod +++ b/doc/man7/EVP_KDF-KB.pod @@ -65,12 +65,17 @@ Set the fixed value 'r', indicating the length of the counter in bits. Supported values are B<8>, B<16>, B<24>, and B<32>. The default value of B<32> will be used if unspecified. +=back + +The OpenSSL FIPS provider also supports the following parameters: + +=over 4 + =item "fips-indicator" (B) A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. -This may be used after calling EVP_KDF_derive. It returns 0 if any "***-check" -related parameter is set to 0 and the check fails. -This option is used by the OpenSSL FIPS provider. +This may be used after calling EVP_KDF_derive. It returns 0 if "key-check" +is set to 0 and the check fails. =item "key-check" (B) @@ -79,8 +84,8 @@ length of used key-derivation key (B) is shorter than 112 bits. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =back diff --git a/doc/man7/EVP_KDF-PBKDF2.pod b/doc/man7/EVP_KDF-PBKDF2.pod index a1ad3b088f..d9c73c35e2 100644 --- a/doc/man7/EVP_KDF-PBKDF2.pod +++ b/doc/man7/EVP_KDF-PBKDF2.pod @@ -57,18 +57,17 @@ The checks performed are: The default provider uses a default mode of 1 for backwards compatibility, and the FIPS provider uses a default mode of 0. - -The value string is expected to be a decimal number 0 or 1. -Setting this to zero will ignore the error and set the approved "fips-indicator" -to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =item "fips-indicator" (B) +This option is used by the OpenSSL FIPS provider. + A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. -This may be used after calling EVP_KDF_derive. It returns 0 if the "pkcs5" +This may be used after calling EVP_KDF_derive. It returns 0 if "pkcs5" is set to 1 and the derived key length, salt length or iteration count test fails. -This option is used by the OpenSSL FIPS provider. =back diff --git a/doc/man7/EVP_KDF-SS.pod b/doc/man7/EVP_KDF-SS.pod index bd9059778f..ac19c07fa9 100644 --- a/doc/man7/EVP_KDF-SS.pod +++ b/doc/man7/EVP_KDF-SS.pod @@ -61,12 +61,17 @@ This parameter set the shared secret that is used for key derivation. This parameter sets an optional value for fixedinfo, also known as otherinfo. +=back + +The OpenSSL FIPS provider also supports the following parameters: + +=over 4 + =item "fips-indicator" (B) A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. -This may be used after calling EVP_KDF_derive. It returns 0 if any "***-check" -related parameter is set to 0 and the check fails. -This option is used by the OpenSSL FIPS provider. +This may be used after calling EVP_KDF_derive. It returns 0 if "key-check" +is set to 0 and the check fails. =item "key-check" (B) @@ -75,8 +80,8 @@ length of used key-derivation key (B) is shorter than 112 bits. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =back diff --git a/doc/man7/EVP_KDF-SSHKDF.pod b/doc/man7/EVP_KDF-SSHKDF.pod index 4acc2c90a8..3336b09fe8 100644 --- a/doc/man7/EVP_KDF-SSHKDF.pod +++ b/doc/man7/EVP_KDF-SSHKDF.pod @@ -80,12 +80,17 @@ A single char of value 70 (ASCII char 'F'). =back +=back + +The OpenSSL FIPS provider also supports the following parameters: + +=over 4 + =item "fips-indicator" (B) A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling EVP_KDF_derive. It returns 0 if any "***-check" related parameter is set to 0 and the check fails. -This option is used by the OpenSSL FIPS provider. =item "digest-check" (B) @@ -93,8 +98,8 @@ The default value of 1 causes an error during EVP_KDF_CTX_set_params() if used digest is not approved. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. According to SP 800-135r1, the following are approved digest algorithms: SHA-1, SHA2-224, SHA2-256, SHA2-384, SHA2-512. @@ -106,8 +111,8 @@ length of used key-derivation key (B) is shorter than 112 bits. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =back diff --git a/doc/man7/EVP_KDF-TLS13_KDF.pod b/doc/man7/EVP_KDF-TLS13_KDF.pod index 1b13e2f947..a3bcc277b1 100644 --- a/doc/man7/EVP_KDF-TLS13_KDF.pod +++ b/doc/man7/EVP_KDF-TLS13_KDF.pod @@ -54,35 +54,6 @@ Refer to RFC 8446 section 7.1 "Key Schedule" for details. This parameter sets the mode for the TLS 1.3 KDF operation. There are two modes that are currently defined: -=item "fips-indicator" (B) - -A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. -This may be used after calling EVP_KDF_derive. It returns 0 if any "***-check" -related parameter is set to 0 and the check fails. -This option is used by the OpenSSL FIPS provider. - -=item "digest-check" (B) - -The default value of 1 causes an error during EVP_KDF_CTX_set_params() if -used digest is not approved. -Setting this to zero will ignore the error and set the approved -"fips-indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. - -According to RFC 8446, the following are approved digest algorithms: SHA2-256, -SHA2-384. - -=item "key-check" (B) - -The default value of 1 causes an error during EVP_KDF_CTX_set_params() if the -length of used key-derivation key (B) is shorter than 112 -bits. -Setting this to zero will ignore the error and set the approved -"fips-indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. - =over 4 =item "EXTRACT_ONLY" or B @@ -108,6 +79,40 @@ an error will occur. =back +The OpenSSL FIPS provider also supports the following parameters: + +=over 4 + +=item "fips-indicator" (B) + +A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. +This may be used after calling EVP_KDF_derive. It returns 0 if any "***-check" +related parameter is set to 0 and the check fails. + +=item "digest-check" (B) + +The default value of 1 causes an error during EVP_KDF_CTX_set_params() if +used digest is not approved. +Setting this to zero will ignore the error and set the approved +"fips-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. + +According to RFC 8446, the following are approved digest algorithms: SHA2-256, +SHA2-384. + +=item "key-check" (B) + +The default value of 1 causes an error during EVP_KDF_CTX_set_params() if the +length of used key-derivation key (B) is shorter than 112 +bits. +Setting this to zero will ignore the error and set the approved +"fips-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. + +=back + =head1 NOTES This KDF is intended for use by the TLS 1.3 implementation in libssl. diff --git a/doc/man7/EVP_KDF-TLS1_PRF.pod b/doc/man7/EVP_KDF-TLS1_PRF.pod index b3eb5286db..38edcc35aa 100644 --- a/doc/man7/EVP_KDF-TLS1_PRF.pod +++ b/doc/man7/EVP_KDF-TLS1_PRF.pod @@ -44,20 +44,25 @@ This parameter sets the context seed. The length of the context seed cannot exceed 1024 bytes; this should be more than enough for any normal use of the TLS PRF. +=back + +The OpenSSL FIPS provider also supports the following parameters: + +=over 4 + =item "fips-indicator" (B) A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling EVP_KDF_derive. It returns 0 if any "***-check" related parameter is set to 0 and the check fails. -This option is used by the OpenSSL FIPS provider. =item "ems_check" (B) The default value of 1 causes an error during EVP_KDF_derive() if "master secret" is used instead of "extended master secret" Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =item "digest-check" (B) @@ -65,8 +70,8 @@ The default value of 1 causes an error during EVP_KDF_CTX_set_params() if used digest is not approved. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. According to SP 800-135r1, the following are approved digest algorithms: SHA2-256, SHA2-384, SHA2-512. @@ -78,8 +83,8 @@ length of used key-derivation key (B) is shorter than 112 bits. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =back diff --git a/doc/man7/EVP_KDF-X963.pod b/doc/man7/EVP_KDF-X963.pod index 17de2fc69f..c0ea3fe9ff 100644 --- a/doc/man7/EVP_KDF-X963.pod +++ b/doc/man7/EVP_KDF-X963.pod @@ -36,12 +36,17 @@ This parameter sets the secret. This parameter specifies an optional value for shared info. +=back + +The OpenSSL FIPS provider also supports the following parameters: + +=over 4 + =item "fips-indicator" (B) A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling EVP_KDF_derive. It returns 0 if any "***-check" related parameter is set to 0 and the check fails. -This option is used by the OpenSSL FIPS provider. =item "digest-check" (B) @@ -49,8 +54,8 @@ The default value of 1 causes an error during EVP_KDF_CTX_set_params() if used digest is not approved. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. According to ANSI X9.63-2001, the following are approved digest algorithms: SHA2-224, SHA2-256, SHA2-384, SHA2-512, SHA2-512/224, SHA2-512/256, SHA3-224, @@ -63,8 +68,8 @@ length of used key-derivation key (B) is shorter than 112 bits. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =back diff --git a/doc/man7/EVP_KEYEXCH-ECDH.pod b/doc/man7/EVP_KEYEXCH-ECDH.pod index 9b592c0f99..97794bec7c 100644 --- a/doc/man7/EVP_KEYEXCH-ECDH.pod +++ b/doc/man7/EVP_KEYEXCH-ECDH.pod @@ -41,6 +41,12 @@ per-key basis. =item "kdf-ukm" (B) +=back + +The OpenSSL FIPS provider also supports the following parameters: + +=over 4 + =item "fips-indicator" (B) =item "key-check" (B) @@ -54,9 +60,10 @@ See L. If required this parameter should before OSSL_FUNC_keyexch_derive(). The default value of 1 causes an error during the OSSL_FUNC_keyexch_derive if the EC curve has a cofactor that is not 1, and the cofactor is not used. -Setting this to 0 will ignore the error and set the approved "fips-indicator" to -0. This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance -if set to 0. +Setting this to 0 will ignore the error and set the approved +"fips-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =back diff --git a/doc/man7/EVP_MAC-CMAC.pod b/doc/man7/EVP_MAC-CMAC.pod index 0610d050f4..0fb84d604a 100644 --- a/doc/man7/EVP_MAC-CMAC.pod +++ b/doc/man7/EVP_MAC-CMAC.pod @@ -49,14 +49,15 @@ valid. =item "encrypt-check" (B) +This option is used by the OpenSSL FIPS provider. If required this parameter should be set before EVP_MAC_init() The default value of 1 causes an error when a unapproved Triple-DES encryption operation is triggered. -Setting this to 0 will ignore the error and set the approved "fips-indicator" to -0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. +Setting this to 0 will ignore the error and set the approved +"fips-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =back @@ -78,6 +79,8 @@ EVP_MAC_CTX_get_block_size(). =item "fips-indicator" (B) +This option is used by the OpenSSL FIPS provider. + A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling EVP_MAC_final(). It may return 0 if the "encrypt-check" option is set to 0. diff --git a/doc/man7/EVP_PKEY-DSA.pod b/doc/man7/EVP_PKEY-DSA.pod index f51b43b2a6..8bc0032bce 100644 --- a/doc/man7/EVP_PKEY-DSA.pod +++ b/doc/man7/EVP_PKEY-DSA.pod @@ -6,18 +6,33 @@ EVP_PKEY-DSA, EVP_KEYMGMT-DSA - EVP_PKEY DSA keytype and algorithm support =head1 DESCRIPTION -For B the FIPS186-4 standard specifies that the values used for FFC +For B the FIPS 186-4 standard specifies that the values used for FFC parameter generation are also required for parameter validation. This means that optional FFC domain parameter values for I, I and I may need to be stored for validation purposes. For B these fields are not stored in the ASN1 data so they need to be stored externally if validation is required. +As part of FIPS 140-3 DSA is not longer FIPS approved for key generation and +signature validation, but is still allowed for signature verification. + =head2 DSA parameters The B key type supports the FFC parameters (see L). +It also supports the following parameters: + +=over 4 + +=item "sign-check" (B) ) + +See L for more information. + +=back + =head2 DSA key generation parameters The B key type supports the FFC key generation parameters (see @@ -111,6 +126,11 @@ L, L, L +=head1 HISTORY + +DSA Key generation and signature generation are no longer FIPS approved in +OpenSSL 3.4. See L for more information. + =head1 COPYRIGHT Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man7/EVP_RAND-HASH-DRBG.pod b/doc/man7/EVP_RAND-HASH-DRBG.pod index 3333018794..5561ecbdeb 100644 --- a/doc/man7/EVP_RAND-HASH-DRBG.pod +++ b/doc/man7/EVP_RAND-HASH-DRBG.pod @@ -50,6 +50,12 @@ The supported parameters are: These parameters work as described in L. +=item "fips-indicator" (B) + +=item "digest-check" (B) + +These parameters work as described in L. + =back =head1 NOTES diff --git a/doc/man7/EVP_RAND-HMAC-DRBG.pod b/doc/man7/EVP_RAND-HMAC-DRBG.pod index d685f509f9..42ed12ac20 100644 --- a/doc/man7/EVP_RAND-HMAC-DRBG.pod +++ b/doc/man7/EVP_RAND-HMAC-DRBG.pod @@ -52,6 +52,12 @@ The supported parameters are: These parameters work as described in L. +=item "fips-indicator" (B) + +=item "digest-check" (B) + +These parameters work as described in L. + =back =head1 NOTES diff --git a/doc/man7/EVP_SIGNATURE-DSA.pod b/doc/man7/EVP_SIGNATURE-DSA.pod index ca33f5f751..711be32854 100644 --- a/doc/man7/EVP_SIGNATURE-DSA.pod +++ b/doc/man7/EVP_SIGNATURE-DSA.pod @@ -10,6 +10,9 @@ EVP_SIGNATURE-DSA Support for computing DSA signatures. See L for information related to DSA keys. +As part of FIPS 140-3 DSA is not longer FIPS approved for key generation and +signature validation, but is still allowed for signature verification. + =head2 Signature Parameters The following signature parameters can be set using EVP_PKEY_CTX_set_params(). @@ -59,6 +62,11 @@ L, L, L, +=head1 HISTORY + +DSA Key generation and signature generation are no longer FIPS approved in +OpenSSL 3.4. See L for more information. + =head1 COPYRIGHT Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man7/EVP_SIGNATURE-RSA.pod b/doc/man7/EVP_SIGNATURE-RSA.pod index b33b0728fa..cbecf30050 100644 --- a/doc/man7/EVP_SIGNATURE-RSA.pod +++ b/doc/man7/EVP_SIGNATURE-RSA.pod @@ -63,12 +63,6 @@ using EVP_PKEY_sign_init_ex() or EVP_PKEY_verify_init_ex(). These are not supported with the RSA signature schemes that already include a message digest algorithm, See L above. -=item "key-check" (B) - -=item "digest-check" (B) - -=item "sign-x931-pad-check" (B) - These common parameters are described in L. =item "pad-mode" (B) @@ -126,6 +120,20 @@ digest size when signing to comply with FIPS 186-4 section 5.5. =back +=back + +The OpenSSL FIPS provider also supports the following parameters: + +=over 4 + +=item "key-check" (B) + +=item "digest-check" (B) + +=item "sign-x931-pad-check" (B) + +These parameters are described in L. + =item "rsa-pss-saltlen-check" (B) The default value of 1 causes an error during signature generation or @@ -133,8 +141,8 @@ verification if salt length (B) is not between zero and the output block size of the digest function (inclusive). Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =back diff --git a/doc/man7/provider-asym_cipher.pod b/doc/man7/provider-asym_cipher.pod index e2a981e860..5a4ba9dda9 100644 --- a/doc/man7/provider-asym_cipher.pod +++ b/doc/man7/provider-asym_cipher.pod @@ -243,12 +243,17 @@ This makes exploitation of the Bleichenbacher significantly harder, even if the code using the RSA decryption API is not implemented in side-channel free manner. Set by default. Requires provider support. +=back + +The OpenSSL FIPS provider also supports the following parameters: + +=over 4 + =item "fips-indicator" (B) A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling either OSSL_FUNC_asym_cipher_encrypt() or OSSL_FUNC_asym_cipher_decrypt(). It may return 0 if "key-check" is set to 0. -This option is used by the OpenSSL FIPS provider. =item "key-check" (B) @@ -257,8 +262,8 @@ OSSL_FUNC_asym_cipher_encrypt_init() or OSSL_FUNC_asym_cipher_decrypt_init(). The default value of 1 causes an error during the init if the key is not FIPS approved (e.g. The key has a security strength of less than 112 bits). Setting this to 0 will ignore the error and set the approved "fips-indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =back diff --git a/doc/man7/provider-kem.pod b/doc/man7/provider-kem.pod index 57c2ca916b..dfb470e9de 100644 --- a/doc/man7/provider-kem.pod +++ b/doc/man7/provider-kem.pod @@ -186,8 +186,7 @@ See L for further details on the parameters structure used by the OSSL_FUNC_kem_get_ctx_params() and OSSL_FUNC_kem_set_ctx_params() functions. -Common parameters currently recognised by built-in key encapsulation algorithms -are as follows. +The OpenSSL FIPS provider also supports the following parameters: =over 4 @@ -196,7 +195,6 @@ are as follows. A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling either OSSL_FUNC_kem_encapsulate() or OSSL_FUNC_kem_decapsulate(). It may return 0 if the "key-check" is set to 0. -This option is used by the OpenSSL FIPS provider. =item "key-check" (B) @@ -205,11 +203,13 @@ or OSSL_FUNC_kem_decapsulate_init(). The default value of 1 causes an error during the init if the key is not FIPS approved (e.g. The key has a security strength of less than 112 bits). Setting this to 0 will ignore the error and set the approved "fips-indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =back +=head2 Asymmetric Key Encapsulation Parameter Functions + OSSL_FUNC_kem_get_ctx_params() gets asymmetric KEM parameters associated with the given provider side asymmetric kem context I and stores them in I. diff --git a/doc/man7/provider-keyexch.pod b/doc/man7/provider-keyexch.pod index 69feb52772..b67588f572 100644 --- a/doc/man7/provider-keyexch.pod +++ b/doc/man7/provider-keyexch.pod @@ -204,12 +204,17 @@ usually do not need to support this gettable parameter as its sole purpose is to support functionality of the deprecated EVP_PKEY_CTX_get0_ecdh_kdf_ukm() and EVP_PKEY_CTX_get0_dh_kdf_ukm() functions. +=back + +The OpenSSL FIPS provider also supports the following parameters: + +=over 4 + =item "fips-indicator" (B) A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling OSSL_FUNC_keyexch_derive(). It may return 0 if either the "digest-check" or the "key-check" are set to 0. -This option is used by the OpenSSL FIPS provider. =item "key-check" (B) @@ -217,8 +222,8 @@ If required this parameter should be set using OSSL_FUNC_keyexch_init(). The default value of 1 causes an error during the init if the key is not FIPS approved (e.g. The key has a security strength of less than 112 bits). Setting this to 0 will ignore the error and set the approved "fips-indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =item "digest-check" (B) @@ -226,8 +231,8 @@ If required this parameter should be set before any optional digest is set. The default value of 1 causes an error when the digest is set if the digest is not FIPS approved. Setting this to 0 will ignore the error and set the approved "fips-indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =back diff --git a/doc/man7/provider-keymgmt.pod b/doc/man7/provider-keymgmt.pod index 0f4e0edd31..1fed9faf35 100644 --- a/doc/man7/provider-keymgmt.pod +++ b/doc/man7/provider-keymgmt.pod @@ -436,6 +436,18 @@ its argument I. This signifies that no digest has to be specified with the corresponding signature operation, but may be specified as an option. +=back + +The OpenSSL FIPS provider also supports the following parameters: + +=over 4 + +=item "fips-indicator" (B) + +A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. +This may be used after calling OSSL_FUNC_keymgmt_gen() function. It may +return 0 if either the "key-check", or "sign-check" are set to 0. + =item "key-check" (B) If required this parameter should be set using OSSL_FUNC_keymgmt_gen_set_params() @@ -443,25 +455,18 @@ or OSSL_FUNC_keymgmt_gen_init(). The default value of 1 causes an error during the init if the key is not FIPS approved (e.g. The key has a security strength of less than 112 bits). Setting this to 0 will ignore the error and set the approved "fips-indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. -=item "sign-check" (B) +=item "sign-check" (B) If required this parameter should be set before the OSSL_FUNC_keymgmt_gen() function. This value is not supported by all keygen algorithms. The default value of 1 will cause an error if the generated key is not allowed to be used for signing. Setting this to 0 will ignore the error and set the approved "fips-indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. - -=item "fips-indicator" (B) - -A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. -This may be used after calling OSSL_FUNC_keymgmt_gen() function. It may -return 0 if either the "key-check", or "sign-check" are set to 0. -This option is used by the OpenSSL FIPS provider. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =back diff --git a/doc/man7/provider-mac.pod b/doc/man7/provider-mac.pod index a7643e7c85..a65a37873f 100644 --- a/doc/man7/provider-mac.pod +++ b/doc/man7/provider-mac.pod @@ -191,6 +191,10 @@ Can be used to get the MAC block size (if supported by the algorithm). =back +=back + +The OpenSSL FIPS provider may support the following parameters: + =over 4 =item "fips-indicator" (B) @@ -198,29 +202,24 @@ Can be used to get the MAC block size (if supported by the algorithm). A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling the final function. It may return 0 if either "no-short-mac" or "key-check" are set to 0. -This option is used by the OpenSSL FIPS provider. - -=back - -=over 4 =item "no-short-mac" (B) If required this parameter should be set early via an init function. The default value of 1 causes an error when too short MAC output is asked for. Setting this to 0 will ignore the error and set the approved -"fips-indicator" to 0. This option is used by the OpenSSL FIPS provider, -and breaks FIPS compliance if set to 0. +"fips-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =item "key-check" (B) If required this parameter should be set before OSSL_FUNC_mac_init. The default value of 1 causes an error when small key sizes are asked for. Setting this to 0 will ignore the error and set the approved -"fips-indicator" to 0. This option is used by the OpenSSL FIPS provider, -and breaks FIPS compliance if set to 0. - -=back +"fips-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =back @@ -254,6 +253,7 @@ L, L =head1 HISTORY The provider MAC interface was introduced in OpenSSL 3.0. +The parameters "no-short-mac" and "fips-indicator" were added in OpenSSL 3.4. =head1 COPYRIGHT diff --git a/doc/man7/provider-rand.pod b/doc/man7/provider-rand.pod index b6310df3a9..5934a46ef1 100644 --- a/doc/man7/provider-rand.pod +++ b/doc/man7/provider-rand.pod @@ -260,12 +260,17 @@ Sets the properties to be queried when trying to fetch an underlying algorithm. This must be given together with the algorithm naming parameter to be considered valid. +=back + +The OpenSSL FIPS provider also supports the following parameters: + +=over 4 + =item "fips-indicator" (B) A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling OSSL_FUNC_rand_generate(). It may return 0 if the "digest-check" is set to 0. -This option is used by the OpenSSL FIPS provider. =item "digest-check" (B) @@ -273,8 +278,8 @@ If required this parameter should be set before the digest is set. The default value of 1 causes an error when the digest is set if the digest is not FIPS approved (e.g. truncated digests). Setting this to 0 will ignore the error and set the approved "fips-indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =back diff --git a/doc/man7/provider-signature.pod b/doc/man7/provider-signature.pod index ce14c4c705..cb26a1c75d 100644 --- a/doc/man7/provider-signature.pod +++ b/doc/man7/provider-signature.pod @@ -388,12 +388,17 @@ was successful. Known answer tests can be performed if the random generator is overridden to supply known values that either pass or fail. +=back + +The following parameters are used by the OpenSSL FIPS provider: + +=over 4 + =item "fips-indicator" (B) A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling either the sign or verify final functions. It may return 0 if either the "digest-check", "key-check", or "sign-check" are set to 0. -This option is used by the OpenSSL FIPS provider. =item "verify-message" (B @@ -411,8 +416,8 @@ If required this parameter should be set early via an init function The default value of 1 causes an error during the init if the key is not FIPS approved (e.g. The key has a security strength of less than 112 bits). Setting this to 0 will ignore the error and set the approved "indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =item "digest-check" (B) @@ -420,8 +425,8 @@ If required this parameter should be set before the signature digest is set. The default value of 1 causes an error when the digest is set if the digest is not FIPS approved (e.g. SHA1 is used for signing). Setting this to 0 will ignore the error and set the approved "fips-indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =item "sign-check" (B) @@ -429,15 +434,17 @@ If required this parameter should be set early via an init function. The default value of 1 causes an error when a signing algorithm is used. (This is triggered by deprecated signing algorithms). Setting this to 0 will ignore the error and set the approved "fips-indicator" to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" to +return 0. =item "sign-x931-pad-check" (B) -If required this parameter should be set before the padding mode is set +If required this parameter should be set before the padding mode is set. The default value of 1 causes an error if the padding mode is set to X9.31 padding for a RSA signing operation. Setting this to 0 will ignore the error and set the approved "fips-indicator" to 0. -This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if -set to 0. +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =back