From: slontis Date: Thu, 15 Aug 2024 06:20:26 +0000 (+1000) Subject: Cleanups for FIPS indicator documentation X-Git-Tag: openssl-3.4.0-alpha1~53 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=8e7f39e8830ccafb41e52fbea895cb9740cebaec;p=thirdparty%2Fopenssl.git Cleanups for FIPS indicator documentation Reviewed-by: Tomas Mraz Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/25195) --- diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod index 8e1e0e9e313..3a09ab44348 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 91de46d80da..d26fb93a7a0 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 + +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) -If nonzero, PKCS#1 version 1.5 padding is disabled. -This option is used by the OpenSSL FIPS provider. +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 15171e82990..0778ba04f98 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 e6981759413..af75c7ac029 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 a1ad3b088f5..d9c73c35e27 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 bd9059778f8..ac19c07fa97 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 4acc2c90a89..3336b09fe80 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 1b13e2f9477..a3bcc277b1d 100644 --- a/doc/man7/EVP_KDF-TLS13_KDF.pod +++ b/doc/man7/EVP_KDF-TLS13_KDF.pod @@ -54,12 +54,40 @@ 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: +=over 4 + +=item "EXTRACT_ONLY" or B + +In this mode calling L will just perform the extract +operation. The value returned will be the intermediate fixed-length pseudorandom +key K. The I parameter must match the size of K, which can be looked +up by calling EVP_KDF_CTX_get_kdf_size() after setting the mode and digest. + +The digest, key and salt values must be set before a key is derived otherwise +an error will occur. + +=item "EXPAND_ONLY" or B + +In this mode calling L will just perform the expand +operation. The input key should be set to the intermediate fixed-length +pseudorandom key K returned from a previous extract operation. + +The digest, key and info values must be set before a key is derived otherwise +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. =item "digest-check" (B) @@ -67,8 +95,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 RFC 8446, the following are approved digest algorithms: SHA2-256, SHA2-384. @@ -80,31 +108,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. - -=over 4 - -=item "EXTRACT_ONLY" or B - -In this mode calling L will just perform the extract -operation. The value returned will be the intermediate fixed-length pseudorandom -key K. The I parameter must match the size of K, which can be looked -up by calling EVP_KDF_CTX_get_kdf_size() after setting the mode and digest. - -The digest, key and salt values must be set before a key is derived otherwise -an error will occur. - -=item "EXPAND_ONLY" or B - -In this mode calling L will just perform the expand -operation. The input key should be set to the intermediate fixed-length -pseudorandom key K returned from a previous extract operation. - -The digest, key and info values must be set before a key is derived otherwise -an error will occur. - -=back +This option breaks FIPS compliance if it causes the approved "fips-indicator" +to return 0. =back diff --git a/doc/man7/EVP_KDF-TLS1_PRF.pod b/doc/man7/EVP_KDF-TLS1_PRF.pod index b3eb5286db9..38edcc35aa2 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 17de2fc69fb..c0ea3fe9ffe 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 9b592c0f99a..97794bec7cb 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 0610d050f4c..0fb84d604ae 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 f51b43b2a61..8bc0032bce6 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 33330187941..5561ecbdeb0 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 d685f509f9f..42ed12ac201 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 ca33f5f7513..711be328541 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 b33b0728fac..cbecf30050b 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 e2a981e860f..5a4ba9dda90 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 57c2ca916b5..dfb470e9de2 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 69feb527724..b67588f5726 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 0f4e0edd31e..1fed9faf35f 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 a7643e7c851..a65a37873fc 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 b6310df3a97..5934a46ef12 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 ce14c4c705c..cb26a1c75db 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