From e59df020366b9e249097a0d1ab137ec792326c57 Mon Sep 17 00:00:00 2001 From: slontis Date: Fri, 16 Feb 2024 14:21:11 +1000 Subject: [PATCH 01/14] Add fips indicator requirements doc --- doc/designs/fips_indicator.md | 291 ++++++++++++++++++++++++++++++++++ 1 file changed, 291 insertions(+) create mode 100644 doc/designs/fips_indicator.md diff --git a/doc/designs/fips_indicator.md b/doc/designs/fips_indicator.md new file mode 100644 index 0000000000000..d71df81c292e3 --- /dev/null +++ b/doc/designs/fips_indicator.md @@ -0,0 +1,291 @@ +# OpenSSL FIPS Indicators + +## References +- [1] FIPS 140-3 Standards: https://csrc.nist.gov/projects/cryptographic-module-validation-program/fips-140-3-standards +- [2] Approved Security Functions: https://csrc.nist.gov/projects/cryptographic-module-validation-program/sp-800-140-series-supplemental-information/sp800-140c +- [3] Approved SSP generation and Establishment methods: https://csrc.nist.gov/projects/cryptographic-module-validation-program/sp-800-140-series-supplemental-information/sp800-140d +- [4] Key transitions: https://csrc.nist.gov/pubs/sp/800/131/a/r2/final +- [5] FIPS 140-3 Implementation Guidance: https://csrc.nist.gov/csrc/media/Projects/cryptographic-module-validation-program/documents/fips 140-3/FIPS 140-3 IG.pdf + +## Requirements + +The following information was extracted from the FIPS 140-3 IG [5] “2.4.C Approved Security Service Indicator” + +- A module must have an approved mode of operation that requires at least one service to use an approved security function (defined by [2] and [3]). +- A FIPS 140-3 compliant module requires a built-in service indicator capable of indicating the use of approved security services +- If a module only supports approved services in an approved manner an explicit indicator can be used (e.g. successful completion of a service is an indicator). +- An approved algorithm is not considered to be an approved implementation if it does not have a CAVP certificate or does not include its required self-tests. +(i.e. My interpretation of this is that if the CAVP certificate lists an algorithm with only a subset of key sizes, digests, and/or ciphers compared to the implementation, the differences ARE NOT APPROVED. In many places we have no restrictions on the digest or cipher selected. +- Documentation is required to demonstrate how to use indicators for each approved cryptographic algorithm. +- Testing is required to execute all services and verify that the indicator provides an unambiguous indication of whether the service utilizes an approved cryptographic algorithm, security function or process in an approved manner or not. +- The Security Policy may require updates related to indicators. +AWS/google have added a table in their security policy called +‘Non-Approved Algorithms not allowed in the approved mode of operation’. +An example is RSA with a keysize of < 2048 bits (which has been enforced by [4]). + +### Legacy Support + +Due to key transitions [4] we may have some legacy algorithms that are in a state of only being approved for processing (verification, decryption, validation), and not for protection (signing, encrypting, keygen). +For example DSA. + +The options are: +- Completely remove the algorithm from the FIPS provider. + This is simple but means older applications can no longer process existing data, which is not ideal. +- Allow the algorithm but make it not approved with an context specific indicator. +It is safer to make the protection operations fail rather than use an indicator. +The processing operation for DSA would set the indicator to approved. + + +### Security Checks + +OpenSSL currently defines configurable FIPS options. +These options are supplied via the FIPS configuration file - which is normally setup via fipsinstall. + +- FIPS_FEATURE_CHECK(FIPS_security_check_enabled, fips_security_checks, 1) +- FIPS_FEATURE_CHECK(FIPS_tls_prf_ems_check, fips_tls1_prf_ems_check, 0) +- FIPS_FEATURE_CHECK(FIPS_restricted_drbg_digests_enabled, 0) +- OSSL_PROV_FIPS_PARAM_CONDITIONAL_ERRORS selftest_params.conditional_error_check + +The following functions are available in providers/common/security_check.c. + +- ossl_rsa_check_key() +- ossl_ec_check_key() +- ossl_dsa_check_key() +- ossl_dh_check_key() +- ossl_digest_get_approved_nid_with_sha1() +- ossl_digest_is_allowed() + +Anywhere where these functions are called an indicator MAY be required. +Because these options are available I do not think it is sufficient to +document this in the security policy. + +Each of these functions contains code of the following form: +~~~ +#if !defined(OPENSSL_NO_FIPS_SECURITYCHECKS) + if (ossl_securitycheck_enabled(ctx)) { + // Do some checks, and maybe return 0 for a hard failure + ... + } +} +~~~ + +OPENSSL_NO_FIPS_SECURITYCHECKS is also a configurable option +If the security checks are not enabled then it is unapproved? + + +## Implementation options + +The above requirements indicate 2 options. + +### Option 1 +- Dont allow ANY non approved algorithms and then a indicator is not required. + +#### Pros +- Simple + +#### Cons +- Problematic since we already have configurable options that are used for security checks etc. +- We would need to return errors anywhere where an algorithm is not approved, which would cause + compatability issues + +### Preferred Option +- Add an indicator everywhere that it is required. + +#### Pros +- Flexible solution +#### Cons +- Requires a lot more effort to add the indicator to all the required places. + + +Note that in order for a service to be ‘fips approved’ the following requirments would need to be met. +- Any algorithms are fetched using “fips=yes” +- A service is a series of one or more API calls that must all succeed +- A extra API call is needed after the service succeeds, that should return 1 if the service is approved. + +#### Solution 1 (Using an indicator everywhere) + +Use a per thread global counter that is incremented when an algorithm is approved. AWS/google have added this in places where a service is at the point of completing its output (e.g. digest_final). This design is complicated by the fact that a service may call another service (e.g HMAC using SHA256) that also wants to increment the approved counter. To get around this issue they have a second variable that is used for nesting. If the variable is non zero then the approved counter doesnt increment. This also allows non security relevant functions to not increment the approved count. Another variation of this would be to use flags instead of a counter. + +##### Cons +- At the fips provider level this would require some plumbing to go from the core to the fips provider, which seems overly complex. +- The query can only be done after the output is set. +- The indicator code would end up having to be set in different places depending on the algorithm after the output +is finalized. This would be fairly messy as the point where it is called is set could be different for different algorithms. +- The locking increment seems messy. + + +#### Proposed Solution (Using an indicator everywhere) + +Add a OSSL_PARAM getter to each provider algorithm. +By default if the getter is not handled then it would return not approved. + +##### Pros +- The code is easier to find since it is part of the get_ctx_params function. +- The getter can be called at any point after all the setting is done. + +Any fips algorithm that is approved would then need a setter that at a minimum contains code similar to the following + +~~~ +int ossl_xxx_fips_approved(void) +{ +#ifdef FIPS_MODULE + return 1; /* conditional code would go here for each algorithm if required * +#else + return 0; +#endif +} +~~~ + +and in the algorithms get_ctx() function + +~~~ +int xxx_get_fips_approved(OSSL_PARAM params[]) +{ + p = OSSL_PARAM_locate(params, OSSL_FIPS_PARAM_APPROVED); + if (p != NULL && !OSSL_PARAM_set_int(p, ossl_xxx_fips_approved())) + return 0; + return 1; +} +~~~ + +#### API’s that would be used to support this are + +- EVP_PKEY Keygen, Encryption, Signatures, Key Exchange, KEM +~~~ +EVP_PKEY_CTX_get_params(ctx, ); +~~~ +(Note that this would mean you couldnt use functions that hide the ctx such as EVP_PKEY_Q_keygen()!) + +- Ciphers +~~~ +EVP_CIPHER_CTX_get_params() +~~~ + +- Digests +~~~ +EVP_MD_CTX_get_params() +~~~ + +- KDF’s +~~~ +EVP_KDF_CTX_get_params() +~~~ + +- MAC’s +~~~ +EVP_MAC_CTX_get_params() +~~~ + +- RAND +~~~ +EVP_RAND_CTX_get_params() +~~~ + +#### Backwards Compatability.. + +Previous providers do not support this operation, so they will return not approved if they are not handled. + +#### Alternate Solution + +If we had different kinds of compliance requirements (something other than FIPS) either a seperate getter could be added or the getter could return a int type instead of a 0 or 1.. +(e.g 1 = fips approved, 2 = some other compliance approved) + + +## Changes Required for indicators + +### key size >= 112 bits + +There are a few places where we do not enforce key size that need to be addressed. + +- HMAC +Which applies to all algorithms that use HMAC also. +- CMAC + +### Algorithm Transitions + +Should we remove these algorithms completely from the fips provider, or use indicators? + +- DES_EDE3_ECB +Disallowed for encryption, allowed for legacy decryption + +- DSA +Keygen and Signing are no longer approved, not sure if verify is still approved. + +- RSA Signing using PKCSV15 + +Rsa self test for sign may need to change as the default pad_mode is PKCSV15 +Check if saltlen needs a indicator +Padding mode updates required in rsa_check_padding(). +Check if sha1 is allowed? + +- ECDSA B & K curves are deprecated +It looks like these are still allowed. Are the approved? + +- ED25519/ED448 is now approved + +- X25519/X448 is not approved currently. keygen would need an indicator if we allow it? + +- RSA Key transport +Padding need to be changed to either not allow padding modes other than OEAP or use an indicator. + +- RSA +It looks like SP800-131Ar2 specifies that RSA >= 2048 is approved. +Can we check with the labs what to do for the legacy verification cases +since we allow >=1024. Would this now be unapproved? +This would apply to rsa_kem also? +rsa_keygen_pairwise_test() may need to change to do a sign/verify PCT? + +- TLS1_PRF +If we are only trying to support TLS1.2 here then we should remove the tls1.0/1.1 code from the FIPS MODULE. + + +### Digest Checks + +Any algorithms that use a digest need to make sure that the CAVP certificate lists all supported FIPS digests otherwise an indicator is required. +This applies to the following algorithms +- SSKDF +- TLS_1_3_KDF +- SSHKDF +- X963KDF +- X942KDF +- PBKDF2 +- HKDF +- TLS1_PRF +- HMAC +- KBKDF +- KMAC + +Note this includes SHAKE +Do we need to check which algorithms allow SHA1 also? + + +### Cipher Checks + +- CMAC +- KBKDF CMAC +- GMAC +Should only allow AES. We currently just check the mode. + + +### Configurable options + +- PBKDF2 +'lower_bound_checks' needs to be part of the indicator check + +- See the "security checks" Section. +Anywhere using ossl_securitycheck_enabled() may need an indicator + +## Other Changes + +- AES-GCM +Security Policy must list AES GCM IV generation scenarios +- TEST_RAND +is not approved. +- SSKDF +The security policy needs to be specific about what it supports i.e. +hash, kmac 128/256, hmac-hash. +There are also currently no limitations on the digest for hash and hmac + +- KBKDF +Security policy should list +KMAC-128, KMAC-256 otherwise an indicator is required. \ No newline at end of file From 3b8b2dcff8eb94e822ce31c71d5bab308829f9e3 Mon Sep 17 00:00:00 2001 From: slontis Date: Mon, 19 Feb 2024 15:34:58 +1100 Subject: [PATCH 02/14] fixup! Add fips indicator requirements doc --- doc/designs/fips_indicator.md | 60 +++++++++++++++++++---------------- 1 file changed, 32 insertions(+), 28 deletions(-) diff --git a/doc/designs/fips_indicator.md b/doc/designs/fips_indicator.md index d71df81c292e3..5800a3b2ee9c6 100644 --- a/doc/designs/fips_indicator.md +++ b/doc/designs/fips_indicator.md @@ -1,11 +1,12 @@ # OpenSSL FIPS Indicators ## References -- [1] FIPS 140-3 Standards: https://csrc.nist.gov/projects/cryptographic-module-validation-program/fips-140-3-standards -- [2] Approved Security Functions: https://csrc.nist.gov/projects/cryptographic-module-validation-program/sp-800-140-series-supplemental-information/sp800-140c -- [3] Approved SSP generation and Establishment methods: https://csrc.nist.gov/projects/cryptographic-module-validation-program/sp-800-140-series-supplemental-information/sp800-140d -- [4] Key transitions: https://csrc.nist.gov/pubs/sp/800/131/a/r2/final -- [5] FIPS 140-3 Implementation Guidance: https://csrc.nist.gov/csrc/media/Projects/cryptographic-module-validation-program/documents/fips 140-3/FIPS 140-3 IG.pdf + +- [1] FIPS 140-3 Standards: +- [2] Approved Security Functions: +- [3] Approved SSP generation and Establishment methods: +- [4] Key transitions: +- [5] FIPS 140-3 Implementation Guidance: ## Requirements @@ -13,7 +14,7 @@ The following information was extracted from the FIPS 140-3 IG [5] “2.4.C Appr - A module must have an approved mode of operation that requires at least one service to use an approved security function (defined by [2] and [3]). - A FIPS 140-3 compliant module requires a built-in service indicator capable of indicating the use of approved security services -- If a module only supports approved services in an approved manner an explicit indicator can be used (e.g. successful completion of a service is an indicator). +- If a module only supports approved services in an approved manner an implicit indicator can be used (e.g. successful completion of a service is an indicator). - An approved algorithm is not considered to be an approved implementation if it does not have a CAVP certificate or does not include its required self-tests. (i.e. My interpretation of this is that if the CAVP certificate lists an algorithm with only a subset of key sizes, digests, and/or ciphers compared to the implementation, the differences ARE NOT APPROVED. In many places we have no restrictions on the digest or cipher selected. - Documentation is required to demonstrate how to use indicators for each approved cryptographic algorithm. @@ -29,13 +30,13 @@ Due to key transitions [4] we may have some legacy algorithms that are in a stat For example DSA. The options are: + - Completely remove the algorithm from the FIPS provider. This is simple but means older applications can no longer process existing data, which is not ideal. - Allow the algorithm but make it not approved with an context specific indicator. It is safer to make the protection operations fail rather than use an indicator. The processing operation for DSA would set the indicator to approved. - ### Security Checks OpenSSL currently defines configurable FIPS options. @@ -60,6 +61,7 @@ Because these options are available I do not think it is sufficient to document this in the security policy. Each of these functions contains code of the following form: + ~~~ #if !defined(OPENSSL_NO_FIPS_SECURITYCHECKS) if (ossl_securitycheck_enabled(ctx)) { @@ -72,32 +74,38 @@ Each of these functions contains code of the following form: OPENSSL_NO_FIPS_SECURITYCHECKS is also a configurable option If the security checks are not enabled then it is unapproved? - ## Implementation options The above requirements indicate 2 options. ### Option 1 + - Dont allow ANY non approved algorithms and then a indicator is not required. #### Pros + - Simple #### Cons + - Problematic since we already have configurable options that are used for security checks etc. - We would need to return errors anywhere where an algorithm is not approved, which would cause compatability issues ### Preferred Option + - Add an indicator everywhere that it is required. #### Pros + - Flexible solution + #### Cons + - Requires a lot more effort to add the indicator to all the required places. +Note that in order for a service to be ‘fips approved’ the following requirements would need to be met. -Note that in order for a service to be ‘fips approved’ the following requirments would need to be met. - Any algorithms are fetched using “fips=yes” - A service is a series of one or more API calls that must all succeed - A extra API call is needed after the service succeeds, that should return 1 if the service is approved. @@ -107,19 +115,20 @@ Note that in order for a service to be ‘fips approved’ the following requirm Use a per thread global counter that is incremented when an algorithm is approved. AWS/google have added this in places where a service is at the point of completing its output (e.g. digest_final). This design is complicated by the fact that a service may call another service (e.g HMAC using SHA256) that also wants to increment the approved counter. To get around this issue they have a second variable that is used for nesting. If the variable is non zero then the approved counter doesnt increment. This also allows non security relevant functions to not increment the approved count. Another variation of this would be to use flags instead of a counter. ##### Cons + - At the fips provider level this would require some plumbing to go from the core to the fips provider, which seems overly complex. - The query can only be done after the output is set. - The indicator code would end up having to be set in different places depending on the algorithm after the output is finalized. This would be fairly messy as the point where it is called is set could be different for different algorithms. - The locking increment seems messy. - #### Proposed Solution (Using an indicator everywhere) -Add a OSSL_PARAM getter to each provider algorithm. +Add a OSSL_PARAM getter to each provider algorithm context. By default if the getter is not handled then it would return not approved. ##### Pros + - The code is easier to find since it is part of the get_ctx_params function. - The getter can be called at any point after all the setting is done. @@ -151,46 +160,52 @@ int xxx_get_fips_approved(OSSL_PARAM params[]) #### API’s that would be used to support this are - EVP_PKEY Keygen, Encryption, Signatures, Key Exchange, KEM + ~~~ EVP_PKEY_CTX_get_params(ctx, ); ~~~ + (Note that this would mean you couldnt use functions that hide the ctx such as EVP_PKEY_Q_keygen()!) - Ciphers + ~~~ EVP_CIPHER_CTX_get_params() ~~~ - Digests + ~~~ EVP_MD_CTX_get_params() ~~~ - KDF’s + ~~~ EVP_KDF_CTX_get_params() ~~~ - MAC’s + ~~~ EVP_MAC_CTX_get_params() ~~~ - RAND + ~~~ EVP_RAND_CTX_get_params() ~~~ -#### Backwards Compatability.. +#### Backwards Compatability Previous providers do not support this operation, so they will return not approved if they are not handled. #### Alternate Solution -If we had different kinds of compliance requirements (something other than FIPS) either a seperate getter could be added or the getter could return a int type instead of a 0 or 1.. +If we had different kinds of compliance requirements (something other than FIPS) either a separate getter could be added or the getter could return a int type instead of a 0 or 1.. (e.g 1 = fips approved, 2 = some other compliance approved) - ## Changes Required for indicators ### key size >= 112 bits @@ -207,42 +222,33 @@ Should we remove these algorithms completely from the fips provider, or use indi - DES_EDE3_ECB Disallowed for encryption, allowed for legacy decryption - - DSA Keygen and Signing are no longer approved, not sure if verify is still approved. - - RSA Signing using PKCSV15 - Rsa self test for sign may need to change as the default pad_mode is PKCSV15 Check if saltlen needs a indicator Padding mode updates required in rsa_check_padding(). Check if sha1 is allowed? - - ECDSA B & K curves are deprecated It looks like these are still allowed. Are the approved? - -- ED25519/ED448 is now approved - +- ED25519/ED448 is now approved. - X25519/X448 is not approved currently. keygen would need an indicator if we allow it? - - RSA Key transport Padding need to be changed to either not allow padding modes other than OEAP or use an indicator. - - RSA It looks like SP800-131Ar2 specifies that RSA >= 2048 is approved. Can we check with the labs what to do for the legacy verification cases since we allow >=1024. Would this now be unapproved? This would apply to rsa_kem also? rsa_keygen_pairwise_test() may need to change to do a sign/verify PCT? - - TLS1_PRF If we are only trying to support TLS1.2 here then we should remove the tls1.0/1.1 code from the FIPS MODULE. - ### Digest Checks Any algorithms that use a digest need to make sure that the CAVP certificate lists all supported FIPS digests otherwise an indicator is required. This applies to the following algorithms + - SSKDF - TLS_1_3_KDF - SSHKDF @@ -258,14 +264,13 @@ This applies to the following algorithms Note this includes SHAKE Do we need to check which algorithms allow SHA1 also? - ### Cipher Checks - CMAC - KBKDF CMAC - GMAC -Should only allow AES. We currently just check the mode. +We should only allow AES. We currently just check the mode. ### Configurable options @@ -285,7 +290,6 @@ is not approved. The security policy needs to be specific about what it supports i.e. hash, kmac 128/256, hmac-hash. There are also currently no limitations on the digest for hash and hmac - - KBKDF Security policy should list KMAC-128, KMAC-256 otherwise an indicator is required. \ No newline at end of file From 16de85afbdb0fbd2b31b8e377151505addb73372 Mon Sep 17 00:00:00 2001 From: slontis Date: Mon, 19 Feb 2024 17:53:55 +1100 Subject: [PATCH 03/14] fixup! Add fips indicator requirements doc --- doc/designs/fips_indicator.md | 111 +++++++++++++--------------------- 1 file changed, 41 insertions(+), 70 deletions(-) diff --git a/doc/designs/fips_indicator.md b/doc/designs/fips_indicator.md index 5800a3b2ee9c6..3ff2c80f29bd3 100644 --- a/doc/designs/fips_indicator.md +++ b/doc/designs/fips_indicator.md @@ -15,14 +15,10 @@ The following information was extracted from the FIPS 140-3 IG [5] “2.4.C Appr - A module must have an approved mode of operation that requires at least one service to use an approved security function (defined by [2] and [3]). - A FIPS 140-3 compliant module requires a built-in service indicator capable of indicating the use of approved security services - If a module only supports approved services in an approved manner an implicit indicator can be used (e.g. successful completion of a service is an indicator). -- An approved algorithm is not considered to be an approved implementation if it does not have a CAVP certificate or does not include its required self-tests. -(i.e. My interpretation of this is that if the CAVP certificate lists an algorithm with only a subset of key sizes, digests, and/or ciphers compared to the implementation, the differences ARE NOT APPROVED. In many places we have no restrictions on the digest or cipher selected. +- An approved algorithm is not considered to be an approved implementation if it does not have a CAVP certificate or does not include its required self-tests. (i.e. My interpretation of this is that if the CAVP certificate lists an algorithm with only a subset of key sizes, digests, and/or ciphers compared to the implementation, the differences ARE NOT APPROVED. In many places we have no restrictions on the digest or cipher selected). - Documentation is required to demonstrate how to use indicators for each approved cryptographic algorithm. - Testing is required to execute all services and verify that the indicator provides an unambiguous indication of whether the service utilizes an approved cryptographic algorithm, security function or process in an approved manner or not. -- The Security Policy may require updates related to indicators. -AWS/google have added a table in their security policy called -‘Non-Approved Algorithms not allowed in the approved mode of operation’. -An example is RSA with a keysize of < 2048 bits (which has been enforced by [4]). +- The Security Policy may require updates related to indicators. AWS/google have added a table in their security policy called ‘Non-Approved Algorithms not allowed in the approved mode of operation’. An example is RSA with a keysize of < 2048 bits (which has been enforced by [4]). ### Legacy Support @@ -31,9 +27,9 @@ For example DSA. The options are: -- Completely remove the algorithm from the FIPS provider. - This is simple but means older applications can no longer process existing data, which is not ideal. +- Completely remove the algorithm from the FIPS provider. This is simple but means older applications can no longer process existing data, which is not ideal. - Allow the algorithm but make it not approved with an context specific indicator. + It is safer to make the protection operations fail rather than use an indicator. The processing operation for DSA would set the indicator to approved. @@ -62,14 +58,14 @@ document this in the security policy. Each of these functions contains code of the following form: -~~~ +``` c #if !defined(OPENSSL_NO_FIPS_SECURITYCHECKS) if (ossl_securitycheck_enabled(ctx)) { // Do some checks, and maybe return 0 for a hard failure ... } } -~~~ +``` OPENSSL_NO_FIPS_SECURITYCHECKS is also a configurable option If the security checks are not enabled then it is unapproved? @@ -118,8 +114,7 @@ Use a per thread global counter that is incremented when an algorithm is approve - At the fips provider level this would require some plumbing to go from the core to the fips provider, which seems overly complex. - The query can only be done after the output is set. -- The indicator code would end up having to be set in different places depending on the algorithm after the output -is finalized. This would be fairly messy as the point where it is called is set could be different for different algorithms. +- The indicator code would end up having to be set in different places depending on the algorithm after the output is finalized. This would be fairly messy as the point where it is called is set could be different for different algorithms. - The locking increment seems messy. #### Proposed Solution (Using an indicator everywhere) @@ -134,20 +129,20 @@ By default if the getter is not handled then it would return not approved. Any fips algorithm that is approved would then need a setter that at a minimum contains code similar to the following -~~~ + int ossl_xxx_fips_approved(void) { #ifdef FIPS_MODULE - return 1; /* conditional code would go here for each algorithm if required * + return 1; // conditional code would go here for each algorithm if required * #else return 0; #endif } -~~~ +``` and in the algorithms get_ctx() function -~~~ +``` c int xxx_get_fips_approved(OSSL_PARAM params[]) { p = OSSL_PARAM_locate(params, OSSL_FIPS_PARAM_APPROVED); @@ -155,49 +150,49 @@ int xxx_get_fips_approved(OSSL_PARAM params[]) return 0; return 1; } -~~~ +``` #### API’s that would be used to support this are - EVP_PKEY Keygen, Encryption, Signatures, Key Exchange, KEM -~~~ +``` c EVP_PKEY_CTX_get_params(ctx, ); -~~~ +``` -(Note that this would mean you couldnt use functions that hide the ctx such as EVP_PKEY_Q_keygen()!) +(Note that this would mean you could not use functions that hide the ctx such as EVP_PKEY_Q_keygen()!) - Ciphers -~~~ +``` c EVP_CIPHER_CTX_get_params() -~~~ +``` - Digests -~~~ +``` c EVP_MD_CTX_get_params() -~~~ +``` - KDF’s -~~~ +``` c EVP_KDF_CTX_get_params() -~~~ +``` - MAC’s -~~~ +``` c EVP_MAC_CTX_get_params() -~~~ +``` - RAND -~~~ +``` c EVP_RAND_CTX_get_params() -~~~ +``` -#### Backwards Compatability +#### Backwards Compatibility Previous providers do not support this operation, so they will return not approved if they are not handled. @@ -212,42 +207,27 @@ If we had different kinds of compliance requirements (something other than FIPS) There are a few places where we do not enforce key size that need to be addressed. -- HMAC -Which applies to all algorithms that use HMAC also. +- HMAC Which applies to all algorithms that use HMAC also. - CMAC ### Algorithm Transitions Should we remove these algorithms completely from the fips provider, or use indicators? -- DES_EDE3_ECB -Disallowed for encryption, allowed for legacy decryption -- DSA -Keygen and Signing are no longer approved, not sure if verify is still approved. -- RSA Signing using PKCSV15 -Rsa self test for sign may need to change as the default pad_mode is PKCSV15 -Check if saltlen needs a indicator -Padding mode updates required in rsa_check_padding(). -Check if sha1 is allowed? -- ECDSA B & K curves are deprecated -It looks like these are still allowed. Are the approved? +- DES_EDE3_ECB. Disallowed for encryption, allowed for legacy decryption +- DSA. Keygen and Signing are no longer approved, not sure if verify is still approved. +- RSA Signing using PKCSV15. Rsa self test for sign may need to change as the default pad_mode is PKCSV15. Check if saltlen needs a indicator. Padding mode updates required in rsa_check_padding(). Check if sha1 is allowed? +- ECDSA B & K curves are deprecated It looks like these are still allowed. Are the approved? - ED25519/ED448 is now approved. - X25519/X448 is not approved currently. keygen would need an indicator if we allow it? -- RSA Key transport -Padding need to be changed to either not allow padding modes other than OEAP or use an indicator. -- RSA -It looks like SP800-131Ar2 specifies that RSA >= 2048 is approved. -Can we check with the labs what to do for the legacy verification cases -since we allow >=1024. Would this now be unapproved? -This would apply to rsa_kem also? -rsa_keygen_pairwise_test() may need to change to do a sign/verify PCT? -- TLS1_PRF -If we are only trying to support TLS1.2 here then we should remove the tls1.0/1.1 code from the FIPS MODULE. +- RSA Key transport Padding need to be changed to either not allow padding modes other than OEAP or use an indicator. +- RSA - It looks like SP800-131Ar2 specifies that RSA >= 2048 is approved. Can we check with the labs what to do for the legacy verification cases since we allow >=1024. Would this now be unapproved? This would apply to rsa_kem also? rsa_keygen_pairwise_test() may need to change to do a sign/verify PCT? +- TLS1_PRF If we are only trying to support TLS1.2 here then we should remove the tls1.0/1.1 code from the FIPS MODULE. ### Digest Checks Any algorithms that use a digest need to make sure that the CAVP certificate lists all supported FIPS digests otherwise an indicator is required. -This applies to the following algorithms +This applies to the following algorithms: - SSKDF - TLS_1_3_KDF @@ -274,22 +254,13 @@ We should only allow AES. We currently just check the mode. ### Configurable options -- PBKDF2 -'lower_bound_checks' needs to be part of the indicator check +- PBKDF2 'lower_bound_checks' needs to be part of the indicator check -- See the "security checks" Section. -Anywhere using ossl_securitycheck_enabled() may need an indicator +- See the "security checks" Section. Anywhere using ossl_securitycheck_enabled() may need an indicator ## Other Changes -- AES-GCM -Security Policy must list AES GCM IV generation scenarios -- TEST_RAND -is not approved. -- SSKDF -The security policy needs to be specific about what it supports i.e. -hash, kmac 128/256, hmac-hash. -There are also currently no limitations on the digest for hash and hmac -- KBKDF -Security policy should list -KMAC-128, KMAC-256 otherwise an indicator is required. \ No newline at end of file +- AES-GCM Security Policy must list AES GCM IV generation scenarios +- TEST_RAND is not approved. +- SSKDF The security policy needs to be specific about what it supports i.e. hash, kmac 128/256, hmac-hash. There are also currently no limitations on the digest for hash and hmac +- KBKDF Security policy should list KMAC-128, KMAC-256 otherwise an indicator is required. From 0c8620c689b11b0378b1d167e426eba2d8b3d992 Mon Sep 17 00:00:00 2001 From: slontis Date: Mon, 19 Feb 2024 18:21:57 +1100 Subject: [PATCH 04/14] fixup! Add fips indicator requirements doc --- doc/designs/fips_indicator.md | 105 +++++++++++++++++----------------- 1 file changed, 51 insertions(+), 54 deletions(-) diff --git a/doc/designs/fips_indicator.md b/doc/designs/fips_indicator.md index 3ff2c80f29bd3..54b22a1b6b998 100644 --- a/doc/designs/fips_indicator.md +++ b/doc/designs/fips_indicator.md @@ -1,6 +1,8 @@ -# OpenSSL FIPS Indicators +OpenSSL FIPS Indicators +======================= -## References +References +---------- - [1] FIPS 140-3 Standards: - [2] Approved Security Functions: @@ -8,7 +10,8 @@ - [4] Key transitions: - [5] FIPS 140-3 Implementation Guidance: -## Requirements +Requirements +------------ The following information was extracted from the FIPS 140-3 IG [5] “2.4.C Approved Security Service Indicator” @@ -20,7 +23,8 @@ The following information was extracted from the FIPS 140-3 IG [5] “2.4.C Appr - Testing is required to execute all services and verify that the indicator provides an unambiguous indication of whether the service utilizes an approved cryptographic algorithm, security function or process in an approved manner or not. - The Security Policy may require updates related to indicators. AWS/google have added a table in their security policy called ‘Non-Approved Algorithms not allowed in the approved mode of operation’. An example is RSA with a keysize of < 2048 bits (which has been enforced by [4]). -### Legacy Support +Legacy Support +-------------- Due to key transitions [4] we may have some legacy algorithms that are in a state of only being approved for processing (verification, decryption, validation), and not for protection (signing, encrypting, keygen). For example DSA. @@ -33,7 +37,8 @@ The options are: It is safer to make the protection operations fail rather than use an indicator. The processing operation for DSA would set the indicator to approved. -### Security Checks +Security Checks +--------------- OpenSSL currently defines configurable FIPS options. These options are supplied via the FIPS configuration file - which is normally setup via fipsinstall. @@ -70,35 +75,25 @@ Each of these functions contains code of the following form: OPENSSL_NO_FIPS_SECURITYCHECKS is also a configurable option If the security checks are not enabled then it is unapproved? -## Implementation options +Implementation options +---------------------- The above requirements indicate 2 options. ### Option 1 -- Dont allow ANY non approved algorithms and then a indicator is not required. +Dont allow ANY non approved algorithms and then a indicator is not required. -#### Pros - -- Simple - -#### Cons - -- Problematic since we already have configurable options that are used for security checks etc. -- We would need to return errors anywhere where an algorithm is not approved, which would cause - compatability issues +- Pros: Simple +- Cons: Problematic since we already have configurable options that are used for security checks etc. +- Cons: We would need to return errors anywhere where an algorithm is not approved, which would cause compatibility issues ### Preferred Option -- Add an indicator everywhere that it is required. - -#### Pros - -- Flexible solution +Add an indicator everywhere that it is required. -#### Cons - -- Requires a lot more effort to add the indicator to all the required places. +- Pros: Flexible solution +- Cons: Requires a lot more effort to add the indicator to all the required places. Note that in order for a service to be ‘fips approved’ the following requirements would need to be met. @@ -106,57 +101,56 @@ Note that in order for a service to be ‘fips approved’ the following require - A service is a series of one or more API calls that must all succeed - A extra API call is needed after the service succeeds, that should return 1 if the service is approved. -#### Solution 1 (Using an indicator everywhere) +Solutions for the preferred Option +---------------------------------- -Use a per thread global counter that is incremented when an algorithm is approved. AWS/google have added this in places where a service is at the point of completing its output (e.g. digest_final). This design is complicated by the fact that a service may call another service (e.g HMAC using SHA256) that also wants to increment the approved counter. To get around this issue they have a second variable that is used for nesting. If the variable is non zero then the approved counter doesnt increment. This also allows non security relevant functions to not increment the approved count. Another variation of this would be to use flags instead of a counter. +### Solution 1 (Using an indicator everywhere) -##### Cons +Use a per thread global counter that is incremented when an algorithm is approved. AWS/google have added this in places where a service is at the point of completing its output (e.g. digest_final). This design is complicated by the fact that a service may call another service (e.g HMAC using SHA256) that also wants to increment the approved counter. To get around this issue they have a second variable that is used for nesting. If the variable is non zero then the approved counter doesnt increment. This also allows non security relevant functions to not increment the approved count. Another variation of this would be to use flags instead of a counter. -- At the fips provider level this would require some plumbing to go from the core to the fips provider, which seems overly complex. -- The query can only be done after the output is set. -- The indicator code would end up having to be set in different places depending on the algorithm after the output is finalized. This would be fairly messy as the point where it is called is set could be different for different algorithms. -- The locking increment seems messy. +- Cons: At the fips provider level this would require some plumbing to go from the core to the fips provider, which seems overly complex. +- Cons: The query can only be done after the output is set. +- Cons: The indicator code would end up having to be set in different places depending on the algorithm after the output is finalized. This would be fairly messy as the point where it is called is set could be different for different algorithms. +- Cons: The locking increment seems messy. -#### Proposed Solution (Using an indicator everywhere) +### Proposed Solution (Using an indicator everywhere) Add a OSSL_PARAM getter to each provider algorithm context. By default if the getter is not handled then it would return not approved. -##### Pros - -- The code is easier to find since it is part of the get_ctx_params function. -- The getter can be called at any point after all the setting is done. +- Pros: The code is easier to find since it is part of the get_ctx_params function. +- Pros: The getter can be called at any point after the setting is done. Any fips algorithm that is approved would then need a setter that at a minimum contains code similar to the following - +``` C int ossl_xxx_fips_approved(void) { -#ifdef FIPS_MODULE +ifdef FIPS_MODULE return 1; // conditional code would go here for each algorithm if required * -#else +else return 0; -#endif +endif } ``` and in the algorithms get_ctx() function -``` c +``` C int xxx_get_fips_approved(OSSL_PARAM params[]) { p = OSSL_PARAM_locate(params, OSSL_FIPS_PARAM_APPROVED); if (p != NULL && !OSSL_PARAM_set_int(p, ossl_xxx_fips_approved())) return 0; - return 1; + return 1; } ``` -#### API’s that would be used to support this are +### API’s that would be used to support this are - EVP_PKEY Keygen, Encryption, Signatures, Key Exchange, KEM -``` c +``` C EVP_PKEY_CTX_get_params(ctx, ); ``` @@ -164,44 +158,46 @@ EVP_PKEY_CTX_get_params(ctx, ); - Ciphers -``` c +``` C EVP_CIPHER_CTX_get_params() ``` - Digests -``` c +``` C EVP_MD_CTX_get_params() ``` - KDF’s -``` c +``` C EVP_KDF_CTX_get_params() ``` - MAC’s -``` c +``` C EVP_MAC_CTX_get_params() ``` - RAND -``` c +``` C EVP_RAND_CTX_get_params() ``` -#### Backwards Compatibility +### Backwards Compatibility Previous providers do not support this operation, so they will return not approved if they are not handled. -#### Alternate Solution +### Alternate Solution If we had different kinds of compliance requirements (something other than FIPS) either a separate getter could be added or the getter could return a int type instead of a 0 or 1.. (e.g 1 = fips approved, 2 = some other compliance approved) -## Changes Required for indicators + +Changes Required for indicators +------------------------------- ### key size >= 112 bits @@ -212,7 +208,7 @@ There are a few places where we do not enforce key size that need to be addresse ### Algorithm Transitions -Should we remove these algorithms completely from the fips provider, or use indicators? +Should we remove these algorithms completely from the fips provider, or use indicators? - DES_EDE3_ECB. Disallowed for encryption, allowed for legacy decryption - DSA. Keygen and Signing are no longer approved, not sure if verify is still approved. @@ -258,7 +254,8 @@ We should only allow AES. We currently just check the mode. - See the "security checks" Section. Anywhere using ossl_securitycheck_enabled() may need an indicator -## Other Changes +Other Changes +------------- - AES-GCM Security Policy must list AES GCM IV generation scenarios - TEST_RAND is not approved. From f41832881a0f3f59e50fa3136135d8519ff9f08d Mon Sep 17 00:00:00 2001 From: slontis Date: Mon, 19 Feb 2024 18:23:58 +1100 Subject: [PATCH 05/14] fixup! Add fips indicator requirements doc --- doc/designs/fips_indicator.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/designs/fips_indicator.md b/doc/designs/fips_indicator.md index 54b22a1b6b998..04033552c96fc 100644 --- a/doc/designs/fips_indicator.md +++ b/doc/designs/fips_indicator.md @@ -195,7 +195,6 @@ Previous providers do not support this operation, so they will return not approv If we had different kinds of compliance requirements (something other than FIPS) either a separate getter could be added or the getter could return a int type instead of a 0 or 1.. (e.g 1 = fips approved, 2 = some other compliance approved) - Changes Required for indicators ------------------------------- From 2e5eb842337bfd46de4fe36952082a5e57776fe1 Mon Sep 17 00:00:00 2001 From: slontis Date: Wed, 21 Feb 2024 13:12:36 +1100 Subject: [PATCH 06/14] fixup! Add fips indicator requirements doc --- doc/designs/fips_indicator.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/doc/designs/fips_indicator.md b/doc/designs/fips_indicator.md index 04033552c96fc..6bfafd61b2b6c 100644 --- a/doc/designs/fips_indicator.md +++ b/doc/designs/fips_indicator.md @@ -97,9 +97,9 @@ Add an indicator everywhere that it is required. Note that in order for a service to be ‘fips approved’ the following requirements would need to be met. -- Any algorithms are fetched using “fips=yes” +- Any algorithms come from FIPS provider. - A service is a series of one or more API calls that must all succeed -- A extra API call is needed after the service succeeds, that should return 1 if the service is approved. +- A extra API call is needed after the service succeeds, that should return 1 if the service is FIPS approved. Solutions for the preferred Option ---------------------------------- @@ -202,8 +202,9 @@ Changes Required for indicators There are a few places where we do not enforce key size that need to be addressed. -- HMAC Which applies to all algorithms that use HMAC also. +- HMAC Which applies to all algorithms that use HMAC also (e.g. HKDF, SSKDF, KBKDF) - CMAC +- KMAC ### Algorithm Transitions @@ -211,12 +212,13 @@ Should we remove these algorithms completely from the fips provider, or use indi - DES_EDE3_ECB. Disallowed for encryption, allowed for legacy decryption - DSA. Keygen and Signing are no longer approved, not sure if verify is still approved. -- RSA Signing using PKCSV15. Rsa self test for sign may need to change as the default pad_mode is PKCSV15. Check if saltlen needs a indicator. Padding mode updates required in rsa_check_padding(). Check if sha1 is allowed? -- ECDSA B & K curves are deprecated It looks like these are still allowed. Are the approved? +- ECDSA B & K curves are deprecated, but still approved according to (IG C.K Resolution 4). Should we remove these? If not we need to check that OSSL_PKEY_PARAM_USE_COFACTOR_ECDH is set for key agreement if the cofactor is not 1. - ED25519/ED448 is now approved. -- X25519/X448 is not approved currently. keygen would need an indicator if we allow it? -- RSA Key transport Padding need to be changed to either not allow padding modes other than OEAP or use an indicator. -- RSA - It looks like SP800-131Ar2 specifies that RSA >= 2048 is approved. Can we check with the labs what to do for the legacy verification cases since we allow >=1024. Would this now be unapproved? This would apply to rsa_kem also? rsa_keygen_pairwise_test() may need to change to do a sign/verify PCT? +- X25519/X448 is not approved currently. keygen and keyexchange would also need an indicator if we allow it? +- RSA encryption(transport) using PKCSV15 is no longer allowed. (Note that this break TLS 1.2 using RSA for KeyAgreement), Padding mode updates required. Check RSA KEM also. +- RSA signing using X931 is no longer allowed. (Still allowed for verification). Check if PSS saltlen needs a indicator (Note FIPS 186-4 Section 5.5 bullet(e). Padding mode updates required in rsa_check_padding(). Check if sha1 is allowed? +- RSA - (From SP800-131Ar2) RSA >= 2048 is approved for keygen, signatures and key transport. Verification allows 1024 also. Note also that according to the (IG section C.F) that fips 186-2 verification is also allowed (So this may need either testing OR an indicator). Check that rsa_keygen_pairwise_test() and RSA self tests are all compliant with the above RSA restrictions. + - TLS1_PRF If we are only trying to support TLS1.2 here then we should remove the tls1.0/1.1 code from the FIPS MODULE. ### Digest Checks @@ -225,7 +227,7 @@ Any algorithms that use a digest need to make sure that the CAVP certificate lis This applies to the following algorithms: - SSKDF -- TLS_1_3_KDF +- TLS_1_3_KDF (Only SHA256 and SHA384 Are allowed due to RFC 8446 Appendix B.4) - SSHKDF - X963KDF - X942KDF @@ -237,6 +239,7 @@ This applies to the following algorithms: - KMAC Note this includes SHAKE +KECCAK-KMAC-128 and KECCAK-KMAC-256 should not be allowed for anything other than KMAC. Do we need to check which algorithms allow SHA1 also? ### Cipher Checks @@ -250,7 +253,7 @@ We should only allow AES. We currently just check the mode. ### Configurable options - PBKDF2 'lower_bound_checks' needs to be part of the indicator check - +- KMAC may need a lower bound check on the output size (SP800-185 Section 8.4.2) - See the "security checks" Section. Anywhere using ossl_securitycheck_enabled() may need an indicator Other Changes From 61f02510211ee6745d3946ef9bdce23a55279d1b Mon Sep 17 00:00:00 2001 From: slontis Date: Wed, 21 Feb 2024 13:15:01 +1100 Subject: [PATCH 07/14] fixup! Add fips indicator requirements doc --- doc/designs/fips_indicator.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/designs/fips_indicator.md b/doc/designs/fips_indicator.md index 6bfafd61b2b6c..a105c23933a64 100644 --- a/doc/designs/fips_indicator.md +++ b/doc/designs/fips_indicator.md @@ -253,7 +253,6 @@ We should only allow AES. We currently just check the mode. ### Configurable options - PBKDF2 'lower_bound_checks' needs to be part of the indicator check -- KMAC may need a lower bound check on the output size (SP800-185 Section 8.4.2) - See the "security checks" Section. Anywhere using ossl_securitycheck_enabled() may need an indicator Other Changes @@ -263,3 +262,4 @@ Other Changes - TEST_RAND is not approved. - SSKDF The security policy needs to be specific about what it supports i.e. hash, kmac 128/256, hmac-hash. There are also currently no limitations on the digest for hash and hmac - KBKDF Security policy should list KMAC-128, KMAC-256 otherwise an indicator is required. +- KMAC may need a lower bound check on the output size (SP800-185 Section 8.4.2) From 1af9e644cd8ba209a67a79bd7028b2a1dbc26267 Mon Sep 17 00:00:00 2001 From: slontis Date: Wed, 21 Feb 2024 14:30:23 +1100 Subject: [PATCH 08/14] fixup! Add fips indicator requirements doc --- doc/designs/fips_indicator.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/designs/fips_indicator.md b/doc/designs/fips_indicator.md index a105c23933a64..a405092a41fd2 100644 --- a/doc/designs/fips_indicator.md +++ b/doc/designs/fips_indicator.md @@ -237,8 +237,9 @@ This applies to the following algorithms: - HMAC - KBKDF - KMAC +- Any signature algorithms such as RSA, DSA, ECDSA. -Note this includes SHAKE +Note many of these (such as KDF's will not support SHAKE). KECCAK-KMAC-128 and KECCAK-KMAC-256 should not be allowed for anything other than KMAC. Do we need to check which algorithms allow SHA1 also? From 21399d4749c0ca3dfa2b9cd8551cd2068e8d41ea Mon Sep 17 00:00:00 2001 From: slontis Date: Thu, 22 Feb 2024 12:18:58 +1100 Subject: [PATCH 09/14] fixup! Add fips indicator requirements doc --- doc/designs/fips_indicator.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/doc/designs/fips_indicator.md b/doc/designs/fips_indicator.md index a405092a41fd2..33f4a6d3d54e5 100644 --- a/doc/designs/fips_indicator.md +++ b/doc/designs/fips_indicator.md @@ -211,13 +211,13 @@ There are a few places where we do not enforce key size that need to be addresse Should we remove these algorithms completely from the fips provider, or use indicators? - DES_EDE3_ECB. Disallowed for encryption, allowed for legacy decryption -- DSA. Keygen and Signing are no longer approved, not sure if verify is still approved. +- DSA. Keygen and Signing are no longer approved, verify is still allowed. - ECDSA B & K curves are deprecated, but still approved according to (IG C.K Resolution 4). Should we remove these? If not we need to check that OSSL_PKEY_PARAM_USE_COFACTOR_ECDH is set for key agreement if the cofactor is not 1. - ED25519/ED448 is now approved. - X25519/X448 is not approved currently. keygen and keyexchange would also need an indicator if we allow it? - RSA encryption(transport) using PKCSV15 is no longer allowed. (Note that this break TLS 1.2 using RSA for KeyAgreement), Padding mode updates required. Check RSA KEM also. - RSA signing using X931 is no longer allowed. (Still allowed for verification). Check if PSS saltlen needs a indicator (Note FIPS 186-4 Section 5.5 bullet(e). Padding mode updates required in rsa_check_padding(). Check if sha1 is allowed? -- RSA - (From SP800-131Ar2) RSA >= 2048 is approved for keygen, signatures and key transport. Verification allows 1024 also. Note also that according to the (IG section C.F) that fips 186-2 verification is also allowed (So this may need either testing OR an indicator). Check that rsa_keygen_pairwise_test() and RSA self tests are all compliant with the above RSA restrictions. +- RSA - (From SP800-131Ar2) RSA >= 2048 is approved for keygen, signatures and key transport. Verification allows 1024 also. Note also that according to the (IG section C.F) that fips 186-2 verification is also allowed (So this may need either testing OR an indicator - it also mentions the modulus size must be 1024 * 256*s). Check that rsa_keygen_pairwise_test() and RSA self tests are all compliant with the above RSA restrictions. - TLS1_PRF If we are only trying to support TLS1.2 here then we should remove the tls1.0/1.1 code from the FIPS MODULE. @@ -239,10 +239,14 @@ This applies to the following algorithms: - KMAC - Any signature algorithms such as RSA, DSA, ECDSA. -Note many of these (such as KDF's will not support SHAKE). +The FIPS 140-3 IG Section C.B & C.C have notes related to Vendor affirmation. + +Note many of these (such as KDF's will not support SHAKE). ECDSA and RSA-PSS Signatures allow use of SHAKE. KECCAK-KMAC-128 and KECCAK-KMAC-256 should not be allowed for anything other than KMAC. Do we need to check which algorithms allow SHA1 also? +Test that Deterministic ECDSA does not allow SHAKE (IG C.K Additional Comments 6) + ### Cipher Checks - CMAC @@ -264,3 +268,4 @@ Other Changes - SSKDF The security policy needs to be specific about what it supports i.e. hash, kmac 128/256, hmac-hash. There are also currently no limitations on the digest for hash and hmac - KBKDF Security policy should list KMAC-128, KMAC-256 otherwise an indicator is required. - KMAC may need a lower bound check on the output size (SP800-185 Section 8.4.2) +- HMAC (FIPS 140-3 IG Section C.D has notes about the output length when using a Truncated HMAC) From fc4ec34e12328dec5a0eba2738c9aeb410ad80d5 Mon Sep 17 00:00:00 2001 From: slontis Date: Tue, 12 Mar 2024 17:56:57 +1100 Subject: [PATCH 10/14] fixup! Add fips indicator requirements doc --- doc/designs/fips_indicator.md | 32 +++++++++++++++++++++++--------- 1 file changed, 23 insertions(+), 9 deletions(-) diff --git a/doc/designs/fips_indicator.md b/doc/designs/fips_indicator.md index 33f4a6d3d54e5..50fdeadc7e75e 100644 --- a/doc/designs/fips_indicator.md +++ b/doc/designs/fips_indicator.md @@ -146,6 +146,11 @@ int xxx_get_fips_approved(OSSL_PARAM params[]) } ``` +### Questions ### + +- Do we want to use 3 states? (Approved, Not Approved, Undetermined) +- Do we want this to apply this only to the FIPS provider? + ### API’s that would be used to support this are - EVP_PKEY Keygen, Encryption, Signatures, Key Exchange, KEM @@ -208,40 +213,49 @@ There are a few places where we do not enforce key size that need to be addresse ### Algorithm Transitions -Should we remove these algorithms completely from the fips provider, or use indicators? - - DES_EDE3_ECB. Disallowed for encryption, allowed for legacy decryption - DSA. Keygen and Signing are no longer approved, verify is still allowed. - ECDSA B & K curves are deprecated, but still approved according to (IG C.K Resolution 4). Should we remove these? If not we need to check that OSSL_PKEY_PARAM_USE_COFACTOR_ECDH is set for key agreement if the cofactor is not 1. - ED25519/ED448 is now approved. - X25519/X448 is not approved currently. keygen and keyexchange would also need an indicator if we allow it? -- RSA encryption(transport) using PKCSV15 is no longer allowed. (Note that this break TLS 1.2 using RSA for KeyAgreement), Padding mode updates required. Check RSA KEM also. +- RSA encryption(for key agreement/key transport) using PKCSV15 is no longer allowed. (Note that this breaks TLS 1.2 using RSA for KeyAgreement), + Padding mode updates required. Check RSA KEM also. +- RSA signing using PKCS1 is still allowed (i.e. signature uses shaXXXWithRSAEncryption) - RSA signing using X931 is no longer allowed. (Still allowed for verification). Check if PSS saltlen needs a indicator (Note FIPS 186-4 Section 5.5 bullet(e). Padding mode updates required in rsa_check_padding(). Check if sha1 is allowed? - RSA - (From SP800-131Ar2) RSA >= 2048 is approved for keygen, signatures and key transport. Verification allows 1024 also. Note also that according to the (IG section C.F) that fips 186-2 verification is also allowed (So this may need either testing OR an indicator - it also mentions the modulus size must be 1024 * 256*s). Check that rsa_keygen_pairwise_test() and RSA self tests are all compliant with the above RSA restrictions. - TLS1_PRF If we are only trying to support TLS1.2 here then we should remove the tls1.0/1.1 code from the FIPS MODULE. +### Questions ### + +- Should we remove algorithms completely from the fips provider, or use indicators? +- Do we prefer returning errors over using indicators? +- Should we have the behavior configurable? + ### Digest Checks Any algorithms that use a digest need to make sure that the CAVP certificate lists all supported FIPS digests otherwise an indicator is required. This applies to the following algorithms: -- SSKDF - TLS_1_3_KDF (Only SHA256 and SHA384 Are allowed due to RFC 8446 Appendix B.4) -- SSHKDF -- X963KDF +- TLS1_PRF (Only SHA256,SHA384,SHA512 are allowed) +- X963KDF (SHA1 is not allowed) - X942KDF - PBKDF2 - HKDF -- TLS1_PRF -- HMAC - KBKDF +- SSKDF +- SSHKDF +- HMAC - KMAC - Any signature algorithms such as RSA, DSA, ECDSA. The FIPS 140-3 IG Section C.B & C.C have notes related to Vendor affirmation. -Note many of these (such as KDF's will not support SHAKE). ECDSA and RSA-PSS Signatures allow use of SHAKE. +Note many of these (such as KDF's will not support SHAKE). +See +ECDSA and RSA-PSS Signatures allow use of SHAKE. + KECCAK-KMAC-128 and KECCAK-KMAC-256 should not be allowed for anything other than KMAC. Do we need to check which algorithms allow SHA1 also? From 66393d8bf008455828b26b3f96f3f28458f179b9 Mon Sep 17 00:00:00 2001 From: slontis Date: Mon, 18 Mar 2024 13:08:51 +1100 Subject: [PATCH 11/14] fixup! fixup! Add fips indicator requirements doc --- doc/designs/fips_indicator.md | 38 +++++++++++++++++++++++++++++++---- 1 file changed, 34 insertions(+), 4 deletions(-) diff --git a/doc/designs/fips_indicator.md b/doc/designs/fips_indicator.md index 50fdeadc7e75e..83b0cc81a0c16 100644 --- a/doc/designs/fips_indicator.md +++ b/doc/designs/fips_indicator.md @@ -82,26 +82,56 @@ The above requirements indicate 2 options. ### Option 1 -Dont allow ANY non approved algorithms and then a indicator is not required. +Dont allow ANY non approved algorithms (an indicator is not required). - Pros: Simple - Cons: Problematic since we already have configurable options that are used for security checks etc. - Cons: We would need to return errors anywhere where an algorithm is not approved, which would cause compatibility issues -### Preferred Option +### Option 2 Add an indicator everywhere that it is required. - Pros: Flexible solution - Cons: Requires a lot more effort to add the indicator to all the required places. +- Cons: It is difficult to determine what should use an indicator, and what should just + return an error. +- Cons: We end up with potentially an undetermined state if the check is done early. Note that in order for a service to be ‘fips approved’ the following requirements would need to be met. -- Any algorithms come from FIPS provider. +- Any algorithms come from a FIPS provider. - A service is a series of one or more API calls that must all succeed - A extra API call is needed after the service succeeds, that should return 1 if the service is FIPS approved. -Solutions for the preferred Option +### Option 3 + +Have a hybrid solution that behaves like Option 1 normally that can optionally be turned off. + +This could have a per ctx 'pendantic' flag that is enabled by default which could be switched off +via a ctx setter. + +The indicator is then just a ctx getter that returns whether the pendantic flag is set or not. + +The fips configurable options (See Security Checks) would then only be enabled in non pendantic mode? + +Anywhere where we were thinking of adding an indicator (In Option 2) will need code such as + +```` C + +if (pendant && some_conditions) + return 0; + +```` + +- Pros: When Pendantic mode is on, only strict FIPS approved algorithms will be selected - which seems like the most useful mode. +- Pros: For legacy cases The pendantic mode can be switched off if required. +- Pros: The non approved check is simple. +- Cons: Requires same effort to add indicator checks as option 2 does. +- Cons: pendantic state needs to be either stored in or passed to the provider algorithm. + + +Solutions for the Option 2 ---------------------------------- ### Solution 1 (Using an indicator everywhere) From 157686bf5a4ddaf4261efc97f848f2b99d26e4c8 Mon Sep 17 00:00:00 2001 From: slontis Date: Wed, 10 Apr 2024 15:26:42 +1000 Subject: [PATCH 12/14] Update FIPS indicator document based on OTC discussions. --- doc/designs/fips_indicator.md | 270 +++++++--------------------------- 1 file changed, 57 insertions(+), 213 deletions(-) diff --git a/doc/designs/fips_indicator.md b/doc/designs/fips_indicator.md index 83b0cc81a0c16..56c7f4ba0e533 100644 --- a/doc/designs/fips_indicator.md +++ b/doc/designs/fips_indicator.md @@ -1,6 +1,9 @@ OpenSSL FIPS Indicators ======================= +The following document refers to behaviour required by the OpenSSL FIPS provider, +the changes should not affect the default provider. + References ---------- @@ -23,215 +26,62 @@ The following information was extracted from the FIPS 140-3 IG [5] “2.4.C Appr - Testing is required to execute all services and verify that the indicator provides an unambiguous indication of whether the service utilizes an approved cryptographic algorithm, security function or process in an approved manner or not. - The Security Policy may require updates related to indicators. AWS/google have added a table in their security policy called ‘Non-Approved Algorithms not allowed in the approved mode of operation’. An example is RSA with a keysize of < 2048 bits (which has been enforced by [4]). -Legacy Support --------------- - -Due to key transitions [4] we may have some legacy algorithms that are in a state of only being approved for processing (verification, decryption, validation), and not for protection (signing, encrypting, keygen). -For example DSA. - -The options are: - -- Completely remove the algorithm from the FIPS provider. This is simple but means older applications can no longer process existing data, which is not ideal. -- Allow the algorithm but make it not approved with an context specific indicator. - -It is safer to make the protection operations fail rather than use an indicator. -The processing operation for DSA would set the indicator to approved. - -Security Checks ---------------- - -OpenSSL currently defines configurable FIPS options. -These options are supplied via the FIPS configuration file - which is normally setup via fipsinstall. - -- FIPS_FEATURE_CHECK(FIPS_security_check_enabled, fips_security_checks, 1) -- FIPS_FEATURE_CHECK(FIPS_tls_prf_ems_check, fips_tls1_prf_ems_check, 0) -- FIPS_FEATURE_CHECK(FIPS_restricted_drbg_digests_enabled, 0) -- OSSL_PROV_FIPS_PARAM_CONDITIONAL_ERRORS selftest_params.conditional_error_check - -The following functions are available in providers/common/security_check.c. - -- ossl_rsa_check_key() -- ossl_ec_check_key() -- ossl_dsa_check_key() -- ossl_dh_check_key() -- ossl_digest_get_approved_nid_with_sha1() -- ossl_digest_is_allowed() - -Anywhere where these functions are called an indicator MAY be required. -Because these options are available I do not think it is sufficient to -document this in the security policy. - -Each of these functions contains code of the following form: - -``` c -#if !defined(OPENSSL_NO_FIPS_SECURITYCHECKS) - if (ossl_securitycheck_enabled(ctx)) { - // Do some checks, and maybe return 0 for a hard failure - ... - } -} -``` - -OPENSSL_NO_FIPS_SECURITYCHECKS is also a configurable option -If the security checks are not enabled then it is unapproved? - -Implementation options ----------------------- - -The above requirements indicate 2 options. - -### Option 1 - -Dont allow ANY non approved algorithms (an indicator is not required). - -- Pros: Simple -- Cons: Problematic since we already have configurable options that are used for security checks etc. -- Cons: We would need to return errors anywhere where an algorithm is not approved, which would cause compatibility issues - -### Option 2 - -Add an indicator everywhere that it is required. - -- Pros: Flexible solution -- Cons: Requires a lot more effort to add the indicator to all the required places. -- Cons: It is difficult to determine what should use an indicator, and what should just - return an error. -- Cons: We end up with potentially an undetermined state if the check is done early. - -Note that in order for a service to be ‘fips approved’ the following requirements would need to be met. - -- Any algorithms come from a FIPS provider. -- A service is a series of one or more API calls that must all succeed -- A extra API call is needed after the service succeeds, that should return 1 if the service is FIPS approved. - -### Option 3 - -Have a hybrid solution that behaves like Option 1 normally that can optionally be turned off. - -This could have a per ctx 'pendantic' flag that is enabled by default which could be switched off -via a ctx setter. - -The indicator is then just a ctx getter that returns whether the pendantic flag is set or not. - -The fips configurable options (See Security Checks) would then only be enabled in non pendantic mode? - -Anywhere where we were thinking of adding an indicator (In Option 2) will need code such as - -```` C - -if (pendant && some_conditions) - return 0; - -```` - -- Pros: When Pendantic mode is on, only strict FIPS approved algorithms will be selected - which seems like the most useful mode. -- Pros: For legacy cases The pendantic mode can be switched off if required. -- Pros: The non approved check is simple. -- Cons: Requires same effort to add indicator checks as option 2 does. -- Cons: pendantic state needs to be either stored in or passed to the provider algorithm. - - -Solutions for the Option 2 ----------------------------------- - -### Solution 1 (Using an indicator everywhere) - -Use a per thread global counter that is incremented when an algorithm is approved. AWS/google have added this in places where a service is at the point of completing its output (e.g. digest_final). This design is complicated by the fact that a service may call another service (e.g HMAC using SHA256) that also wants to increment the approved counter. To get around this issue they have a second variable that is used for nesting. If the variable is non zero then the approved counter doesnt increment. This also allows non security relevant functions to not increment the approved count. Another variation of this would be to use flags instead of a counter. - -- Cons: At the fips provider level this would require some plumbing to go from the core to the fips provider, which seems overly complex. -- Cons: The query can only be done after the output is set. -- Cons: The indicator code would end up having to be set in different places depending on the algorithm after the output is finalized. This would be fairly messy as the point where it is called is set could be different for different algorithms. -- Cons: The locking increment seems messy. - -### Proposed Solution (Using an indicator everywhere) - -Add a OSSL_PARAM getter to each provider algorithm context. -By default if the getter is not handled then it would return not approved. - -- Pros: The code is easier to find since it is part of the get_ctx_params function. -- Pros: The getter can be called at any point after the setting is done. - -Any fips algorithm that is approved would then need a setter that at a minimum contains code similar to the following - -``` C -int ossl_xxx_fips_approved(void) -{ -ifdef FIPS_MODULE - return 1; // conditional code would go here for each algorithm if required * -else - return 0; -endif -} -``` - -and in the algorithms get_ctx() function - -``` C -int xxx_get_fips_approved(OSSL_PARAM params[]) -{ - p = OSSL_PARAM_locate(params, OSSL_FIPS_PARAM_APPROVED); - if (p != NULL && !OSSL_PARAM_set_int(p, ossl_xxx_fips_approved())) - return 0; - return 1; -} -``` - -### Questions ### - -- Do we want to use 3 states? (Approved, Not Approved, Undetermined) -- Do we want this to apply this only to the FIPS provider? - -### API’s that would be used to support this are - -- EVP_PKEY Keygen, Encryption, Signatures, Key Exchange, KEM - -``` C -EVP_PKEY_CTX_get_params(ctx, ); -``` - -(Note that this would mean you could not use functions that hide the ctx such as EVP_PKEY_Q_keygen()!) - -- Ciphers - -``` C -EVP_CIPHER_CTX_get_params() -``` - -- Digests - -``` C -EVP_MD_CTX_get_params() -``` - -- KDF’s - -``` C -EVP_KDF_CTX_get_params() -``` - -- MAC’s - -``` C -EVP_MAC_CTX_get_params() -``` - -- RAND - -``` C -EVP_RAND_CTX_get_params() -``` +Solution +-------- + +We already have most of the existing code in the FIPS provider using +implicit indicators i.e. An error occurs if existing FIPS rules are violated. + +The following rules will apply to any code that currently is not FIPS approved, +but needs to be. + +- There will be a 'fips approved' mode per provider operation context that is on by default. +- In this mode any FIPS rule that is violated will result in an error. +- The 'fips approved' mode may be turned off per context via a OSSL_PARAM setter, if it +is turned off then the operation is not FIPS approved. +- A getter is required that returns if the operation is 'fips approved' using an +OSSL_PARAM. The returned value can be a combination of the set 'fips_approved' mode +plus any other logic. This is an explicit indicator. +- Any algorithm that is transitioning [4] to not being allowed should be removed from +the fips provider. +- If an algorithm is transitioning [4] to be only allowed for processing +(e.g. verification, signing, key validation) then the protection code +(keygen, signing, encryption) should be removed from the fips provider, any +attempt to use the protection API's should result in an error. The processing +code should still be functional. + +Other rules: +The existing flags that we set in the fips config file to control security checks +will continue to function as they do now, and will not be affected by the +strict mode variable. +The getter to determine if we are fips approved will however take the flags +into account. + +Motivation +---------- -### Backwards Compatibility +The nature of FIPS is that new rules are introduced that will break older code, +and this should be expected. +We have a FIPS provider to enforce FIPS rules, if you need NON FIPS approved +algorithms they should be coming from the default provider. -Previous providers do not support this operation, so they will return not approved if they are not handled. +Implicit indicators are being chosen as they are simple to understand and are +the most useful way of enforcing FIPS restrictions. In cases where FIPS cannot +be used, the setter will still provide a way to override the behaviour, but the +user must deliberately chose to do this. -### Alternate Solution +A system that relies on explicit indicators to test after the operation as to +whether a operation is approved or NOT is subject to misuse. Although this may +provide an 'easier' path for backwards compatibility, this is not the intention +of a FIPS module. -If we had different kinds of compliance requirements (something other than FIPS) either a separate getter could be added or the getter could return a int type instead of a 0 or 1.. -(e.g 1 = fips approved, 2 = some other compliance approved) +There was discussion related to also having a global config setting that could +turn off FIPS mode. If we get to this point we should be using the default provider. +It would also be confusing having the existing fips configuration flags combined +with a global setting. -Changes Required for indicators -------------------------------- +New Changes Required +-------------------- ### key size >= 112 bits @@ -245,7 +95,8 @@ There are a few places where we do not enforce key size that need to be addresse - DES_EDE3_ECB. Disallowed for encryption, allowed for legacy decryption - DSA. Keygen and Signing are no longer approved, verify is still allowed. -- ECDSA B & K curves are deprecated, but still approved according to (IG C.K Resolution 4). Should we remove these? If not we need to check that OSSL_PKEY_PARAM_USE_COFACTOR_ECDH is set for key agreement if the cofactor is not 1. +- ECDSA B & K curves are deprecated, but still approved according to (IG C.K Resolution 4).\ + If we chose not to remove them , then we need to check that OSSL_PKEY_PARAM_USE_COFACTOR_ECDH is set for key agreement if the cofactor is not 1. - ED25519/ED448 is now approved. - X25519/X448 is not approved currently. keygen and keyexchange would also need an indicator if we allow it? - RSA encryption(for key agreement/key transport) using PKCSV15 is no longer allowed. (Note that this breaks TLS 1.2 using RSA for KeyAgreement), @@ -256,12 +107,6 @@ There are a few places where we do not enforce key size that need to be addresse - TLS1_PRF If we are only trying to support TLS1.2 here then we should remove the tls1.0/1.1 code from the FIPS MODULE. -### Questions ### - -- Should we remove algorithms completely from the fips provider, or use indicators? -- Do we prefer returning errors over using indicators? -- Should we have the behavior configurable? - ### Digest Checks Any algorithms that use a digest need to make sure that the CAVP certificate lists all supported FIPS digests otherwise an indicator is required. @@ -302,7 +147,6 @@ We should only allow AES. We currently just check the mode. ### Configurable options - PBKDF2 'lower_bound_checks' needs to be part of the indicator check -- See the "security checks" Section. Anywhere using ossl_securitycheck_enabled() may need an indicator Other Changes ------------- @@ -310,6 +154,6 @@ Other Changes - AES-GCM Security Policy must list AES GCM IV generation scenarios - TEST_RAND is not approved. - SSKDF The security policy needs to be specific about what it supports i.e. hash, kmac 128/256, hmac-hash. There are also currently no limitations on the digest for hash and hmac -- KBKDF Security policy should list KMAC-128, KMAC-256 otherwise an indicator is required. +- KBKDF Security policy should list KMAC-128, KMAC-256 otherwise it should be removed. - KMAC may need a lower bound check on the output size (SP800-185 Section 8.4.2) - HMAC (FIPS 140-3 IG Section C.D has notes about the output length when using a Truncated HMAC) From efc6ca02c205a86bad6beb0496cd2aa83ae3f553 Mon Sep 17 00:00:00 2001 From: slontis Date: Tue, 23 Apr 2024 11:14:34 +1000 Subject: [PATCH 13/14] fixup! Update FIPS indicator document based on OTC discussions. --- doc/designs/fips_indicator.md | 147 ++++++++++++++++++++++++---------- 1 file changed, 105 insertions(+), 42 deletions(-) diff --git a/doc/designs/fips_indicator.md b/doc/designs/fips_indicator.md index 56c7f4ba0e533..ebd3ba208e04d 100644 --- a/doc/designs/fips_indicator.md +++ b/doc/designs/fips_indicator.md @@ -26,59 +26,122 @@ The following information was extracted from the FIPS 140-3 IG [5] “2.4.C Appr - Testing is required to execute all services and verify that the indicator provides an unambiguous indication of whether the service utilizes an approved cryptographic algorithm, security function or process in an approved manner or not. - The Security Policy may require updates related to indicators. AWS/google have added a table in their security policy called ‘Non-Approved Algorithms not allowed in the approved mode of operation’. An example is RSA with a keysize of < 2048 bits (which has been enforced by [4]). +Since any new FIPS restrictions added could possibly break existing applications +the following additional OpenSSL requirements are also needed: + +- The FIPS restrictions should be able to be disabled using Configuration file options (This results in unapproved mode and requires an indicator). +- A mechanism for logging the details of any unapproved mode operations that have been triggered (e.g. DSA Signing) +- The FIPS restrictions should be able to be enabled/disabled per algorithm context. +- If the per algorithm context value is not set, then the Configuration file option is used. + Solution -------- -We already have most of the existing code in the FIPS provider using +In OpenSSL most of the existing code in the FIPS provider is using implicit indicators i.e. An error occurs if existing FIPS rules are violated. The following rules will apply to any code that currently is not FIPS approved, but needs to be. -- There will be a 'fips approved' mode per provider operation context that is on by default. -- In this mode any FIPS rule that is violated will result in an error. -- The 'fips approved' mode may be turned off per context via a OSSL_PARAM setter, if it -is turned off then the operation is not FIPS approved. -- A getter is required that returns if the operation is 'fips approved' using an -OSSL_PARAM. The returned value can be a combination of the set 'fips_approved' mode -plus any other logic. This is an explicit indicator. -- Any algorithm that is transitioning [4] to not being allowed should be removed from -the fips provider. -- If an algorithm is transitioning [4] to be only allowed for processing -(e.g. verification, signing, key validation) then the protection code -(keygen, signing, encryption) should be removed from the fips provider, any -attempt to use the protection API's should result in an error. The processing -code should still be functional. - -Other rules: -The existing flags that we set in the fips config file to control security checks -will continue to function as they do now, and will not be affected by the -strict mode variable. -The getter to determine if we are fips approved will however take the flags -into account. - -Motivation +- The fipsinstall application will have a configurable item added for each algorithm that requires a change. +These options will be passed to the FIPS provider in a manner similar to existing code. + +- A user defined callback similar to OSSL_SELF_TEST will be added. This callback +will be triggered whenever an approved mode test fails. +It may be set up by the user using + +```c +OSSL_INDICATOR_set_callback(OSSL_LIB_CTX *libctx, OSSL_CALLBACK *cb, void *cbarg) +``` + +- The callback API will be + +```c +int OSSL_INDICATOR_callback(OSSL_LIB_CTX *libctx, const char *algtype, + const char *algdesc) +``` + +This can be used during application testing to log that an indicator was +triggered. The user callback may return 0 if the application wants an error +to occur based on the indicator type and description. + +- To control an algorithm context's checks via code requires a setter (e.g OSSL_ALG_PARAM_STRICT_CHECKS), + +```c + p = OSSL_PARAM_locate_const(params, OSSL_ALG_PARAM_STRICT_CHECKS); + if (p != NULL + && !OSSL_PARAM_get_int(p, &ctx->strict_checks)) + return 0; +``` + +The setter is initially -1 (unknown) and can be set to 0 or 1 via a set_ctx call. +If the setter is -1, when the FIPS related approved mode check is done then it +uses the value from the FIPS configuration instead. + +- To access the indicator via code requires a getter (e.g OSSL_ALG_PARAM_APPROVED_INDICATOR), + +```c + p = OSSL_PARAM_locate(params, OSSL_ALG_PARAM_APPROVED_INDICATOR); + if (p != NULL && !OSSL_PARAM_set_int(p, ctx->approved)) + return 0; +``` + +This initially has a value of -1, and is set to either 0 or 1 when a FIPS approved +mode check is done. The getter allows you to access the indicator value after the +operation has completed. + +- Example Algorithm Check + +```c +void alg_init(ALG_CTX *ctx) +{ + ctx->strict_checks = -1; + ctx->approved = -1; +} + +int alg_check_approved(ALG_CTX *ctx) +{ + int pass; + + ctx->approved = 1; + pass = some_fips_test_passes(ctx->libctx); // Check FIPS restriction for alg + if (!pass) { + ctx->approved = 0; + if (ctx->strict_checks == -1) + ctx->strict_checks = fips_config_get(ctx->libctx, op); + if (ctx->strict_checks == 1 + || !OSSL_INDICATOR_callback(ctx->libctx, "ALG NAME", "ALG DESC")) + return 0; + } + return 1; +} +``` + +- Existing security check changes + +OpenSSL currently does checks that are conditionally based on FIPS config values.. + +```c + if (ossl_securitycheck_enabled(ctx)) { + pass = do_some_alg_test(ctx); + if (!pass) + return 0; /* Produce an error */ + + } +``` + +These need to change to work as indicators so the test always runs.. i.e. + +```c + pass = do_some_alg_test(ctx); + // Do code similar to alg_check_approved() above +``` + +Notes ---------- -The nature of FIPS is that new rules are introduced that will break older code, -and this should be expected. -We have a FIPS provider to enforce FIPS rules, if you need NON FIPS approved -algorithms they should be coming from the default provider. - -Implicit indicators are being chosen as they are simple to understand and are -the most useful way of enforcing FIPS restrictions. In cases where FIPS cannot -be used, the setter will still provide a way to override the behaviour, but the -user must deliberately chose to do this. - -A system that relies on explicit indicators to test after the operation as to -whether a operation is approved or NOT is subject to misuse. Although this may -provide an 'easier' path for backwards compatibility, this is not the intention -of a FIPS module. - There was discussion related to also having a global config setting that could -turn off FIPS mode. If we get to this point we should be using the default provider. -It would also be confusing having the existing fips configuration flags combined -with a global setting. +turn off FIPS mode. This will not be added at this stage. New Changes Required -------------------- From e3d5ab0320f7e127a6e28b5d471a2df294ace56f Mon Sep 17 00:00:00 2001 From: slontis Date: Wed, 15 May 2024 12:53:23 +1000 Subject: [PATCH 14/14] fixup! Update FIPS indicator document based on OTC discussions. --- doc/designs/fips_indicator.md | 64 +++++++++++++++++++++++++++++------ 1 file changed, 54 insertions(+), 10 deletions(-) diff --git a/doc/designs/fips_indicator.md b/doc/designs/fips_indicator.md index ebd3ba208e04d..6655f5091f560 100644 --- a/doc/designs/fips_indicator.md +++ b/doc/designs/fips_indicator.md @@ -51,19 +51,25 @@ will be triggered whenever an approved mode test fails. It may be set up by the user using ```c -OSSL_INDICATOR_set_callback(OSSL_LIB_CTX *libctx, OSSL_CALLBACK *cb, void *cbarg) +typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg); + +void OSSL_INDICATOR_set_callback(OSSL_LIB_CTX *libctx, OSSL_CALLBACK *cb, void *cbarg) ``` +The callback and/or cbarg can be changed at any time. -- The callback API will be +- Internally within the FIPS module algorithms the following internal helper +callback may be called ```c -int OSSL_INDICATOR_callback(OSSL_LIB_CTX *libctx, const char *algtype, +int ossl_INDICATOR_callback(OSSL_LIB_CTX *libctx, const char *algtype, const char *algdesc) ``` -This can be used during application testing to log that an indicator was -triggered. The user callback may return 0 if the application wants an error -to occur based on the indicator type and description. +An application's indicator OSSL_CALLBACK can be used to log that an +indicator was triggered. The callback may return either zero or non zero based +on the indicator type and description. Returning non zero from the callback +allows the operation to continue in a non-FIPS approved mode of operation. +Returning 0 causes an error to occur in the caller operation. - To control an algorithm context's checks via code requires a setter (e.g OSSL_ALG_PARAM_STRICT_CHECKS), @@ -90,6 +96,11 @@ This initially has a value of -1, and is set to either 0 or 1 when a FIPS approv mode check is done. The getter allows you to access the indicator value after the operation has completed. +If strict_checks is set to 1 then: +- the FIPS configuration value is not used +- If the operation is detected to be using unapproved mode then an error will + occur and the indicator callback will not be triggered. + - Example Algorithm Check ```c @@ -109,7 +120,7 @@ int alg_check_approved(ALG_CTX *ctx) ctx->approved = 0; if (ctx->strict_checks == -1) ctx->strict_checks = fips_config_get(ctx->libctx, op); - if (ctx->strict_checks == 1 + if (ctx->strict_checks != 0 || !OSSL_INDICATOR_callback(ctx->libctx, "ALG NAME", "ALG DESC")) return 0; } @@ -119,7 +130,10 @@ int alg_check_approved(ALG_CTX *ctx) - Existing security check changes -OpenSSL currently does checks that are conditionally based on FIPS config values.. +OpenSSL already uses FIPS configuration options to perform security_checks, but +the existing code needs to change to work with indicators. + +e.g. existing code ```c if (ossl_securitycheck_enabled(ctx)) { @@ -129,14 +143,36 @@ OpenSSL currently does checks that are conditionally based on FIPS config values } ``` - -These need to change to work as indicators so the test always runs.. i.e. +In updated code for indicators the test always runs.. i.e. ```c pass = do_some_alg_test(ctx); // Do code similar to alg_check_approved() above + // which will conditionally decide whether to return an error + // or trigger the indicator callback. ``` +Issues with setting OSSL_ALG_PARAM_STRICT_CHECKS +------------------------------------------------ + +Normally a user would set params such as OSSL_ALG_PARAM_STRICT_CHECKS using +set_ctx_params() but some algorithms currently do checks in their init operation. +These init functions normally pass an OSSL_PARAM[] argument, but this still +requires the user to set OSSL_ALG_PARAM_STRICT_CHECKS in their init. + +e.g. + +```c +int strict = 0; +params[0] = OSSL_PARAM_construct_int(OSSL_ALG_PARAM_STRICT_CHECKS, strict); +EVP_DigestSignInit_ex(ctx, &pctx, name, libctx, NULL, pkey, params); +// using EVP_PKEY_CTX_set_params() here would be too late +``` + +Delaying the check to after the init would be possible, but it would be a change +in existing behaviour. For example the keysize checks are done in the init since +this is when the key is setup. + Notes ---------- @@ -146,6 +182,12 @@ turn off FIPS mode. This will not be added at this stage. New Changes Required -------------------- +The following changes are required for FIPS 140-3 and will require indicators. +On a cases by case basis we must decide what to do when unapproved mode is +detected. +The mechanism using FIPS configuration options and the indicator callback should +be used for most of these unapproved cases (rather than always returning an error). + ### key size >= 112 bits There are a few places where we do not enforce key size that need to be addressed. @@ -170,6 +212,8 @@ There are a few places where we do not enforce key size that need to be addresse - TLS1_PRF If we are only trying to support TLS1.2 here then we should remove the tls1.0/1.1 code from the FIPS MODULE. +- ECDSA Verify using prehashed message is not allowed. + ### Digest Checks Any algorithms that use a digest need to make sure that the CAVP certificate lists all supported FIPS digests otherwise an indicator is required.