diff --git a/wolfSSL-FIPS-FAQ/src/section01.md b/wolfSSL-FIPS-FAQ/src/section01.md index c1fa4c61..d7bf4ba2 100644 --- a/wolfSSL-FIPS-FAQ/src/section01.md +++ b/wolfSSL-FIPS-FAQ/src/section01.md @@ -2,7 +2,7 @@ This page lists some of the most common issues and questions that are recieved by our wolfSSL security experts, along with their responses. This FAQ is useful for solving general questions that pertain to building/implementing wolfSSL FIPS. If this page does not provide an answer to your question, please feel free to check the wolfSSL Manual, or contact us at support@wolfssl.com. -Last Updated: 8 Dec 2025 +Last Updated: 30 Mar 2026 ## Questions @@ -18,10 +18,12 @@ Last Updated: 8 Dec 2025 1. [Will my applications that are linked agaist the 140-2 module still work with the 140-3 module?](./section02.md#will-my-app-for-1402-still-work-with-1403) 2. [The wc_SetSeed_Cb() callback and the TLS Layer:](./section02.md#wc-setseed-and-tls) 3. [The wc_SetSeed_Cb() callback and a custom seed generation function:](./section02.md#wc-setseed-and-custom-genseed) - 4. [Threading consideration for all CASTs():](./section02.md#threading-and-casts) - 5. [wc_SetSeedCb() a bit unique with relation to CAST's:](./section02.md#setseedcb-and-casts) - 6. [Key Access Management](./section02.md#key-access-management) - 7. [wc_SetSeedCb() a bit unique with relation to CAST's:](./section02.md#setseedcb-and-casts) + 4. [The POST](./section02.md#the-post) + 5. [Threading consideration for all CASTs():](./section02.md#threading-and-casts) + 6. [wc_SetSeedCb() a bit unique with relation to CAST's:](./section02.md#setseedcb-and-casts) + 7. [Key Access Management](./section02.md#key-access-management) 1. [API's that require UNLOCK before first use (should also be re-LOCKED after use):](./section02.md#apis-to-unlock) +6. [Moving from v5 to v6 or even v7, what's new?](./section02.md#moving-from-v5-to-v6-or-even-v7-whats-new) +7. [Long-running application(s) & DRBG_CONT_FIPS_E or RNG_FAILURE_E errors](./section02.md#long-running-applications-drbg_cont_fips_e-or-rng_failure_e-errors) diff --git a/wolfSSL-FIPS-FAQ/src/section02.md b/wolfSSL-FIPS-FAQ/src/section02.md index 3c036f98..75def2f3 100644 --- a/wolfSSL-FIPS-FAQ/src/section02.md +++ b/wolfSSL-FIPS-FAQ/src/section02.md @@ -397,3 +397,75 @@ v7.0.0 (upcoming) * Will have some additional services listed here for Post Quantum key material ``` +## Moving from v5 to v6 or even v7, what's new? + +v6 offers new algorithms not available in v5: +``` +* SRTP-KDF +* AES-XTS (256, 512) +* AES-GCM Streaming mode of operation! +* AES-CFB (1, 8, 128) +* AES-KW +* PBKDF2 +* RSA, ECC, DH FIPS 186-5 upgrade from 186-4! +* ED25519 +* ED448 +* SHAKE128 +* SHAKE256 +* Optional ESV SP800-90B certifiable entropy source w/ SHA3 conditioning function +``` + +In addition to v5 and v6 algorithms, v7 offers new algorithms for PQ and NSA 2.0 suite considerations! +``` +* ML-KEM +* ML-DSA +* SLH-DSA +* LMS (verify only) +* XMSS (verify only) +* SHA512-DRBG (+ Option to run-time disable SHA256-DRBG for NSA 2.0 suite) +* SHA512-based integrity check (no SHA256 use by default for NSA 2.0 suite) +* SHA512/224 & SHA512/256 truncated variants +* RSA, ECC, DH getting additional hash modes for SHAKE and SHA512 variants +* Optional ESV SP800-90B certifiable entropy source w/ SHA3 conditioning function +``` + +## Long-running application(s) & DRBG_CONT_FIPS_E or RNG_FAILURE_E errors... +After millions of calls to wc_InitRng or wc_RNG_GenerateBlock I see these DRBG errors and then +all subsequent wolfCrypt API calls just return FIPS_NOT_ALLOWED_E. What is happening and how do I resolve this? + +A: This is expected behavior related to the DRBG continuous health test (CRNGT) used in the +FIPS module. The legacy CRNGT has a false-positive rate of roughly 1 in every 134 million +invocations. For long-running applications that never power cycle, a false positive will +eventually occur. When it does the DRBG enters an error state and the module will not allow +any further cryptographic operations that depend on a DRBG. This is required by SP 800-90A Rev. 1. + +So the module is behaving correctly. + +Best practices to mitigate this in long-running applications: + +1. Initialize the WC_RNG instance once globally and protect it with a mutex rather than + creating and destroying a new WC_RNG for each operation in every thread. + Initializing and freeing the RNG on every call dramatically increases the + rate at which you will encounter a false positive (the CRNGT runs during + wc_InitRng, so fewer calls to wc_InitRng means fewer opportunities to hit + a false positive). + +2. If a DRBG continuous test failure does occur, the application can recover by restarting + the executable (or the process using the wolfCrypt shared library). On a modern OS, + unloading and reloading the shared object is equivalent to a power cycle of the module + from the FIPS perspective. A full device power cycle is NOT required when using a shared object. + +3. wolfSSL strongly recommends that persistent connections be shut down and a new + handshake performed at least once every 24 to 48 hours. Re-negotiating ephemeral keys + every 8 - 10 minutes (complete shutdown and fresh handshake) is ideal, do + not leave a TLS/DTLS session active for 24, 48, 72... hours or more, this will + increase your chances of hitting a false positive as well. + +NOTE: The upcoming v7.0.0 FIPS module will replace the legacy CRNGT with the newer +Repetition Count Test (RCT) and Adaptive Proportion Test (APT) as defined in SP800-90B. +These tests are more mathematically robust and will significantly reduce the false-positive +rate, alleviating this issue for long-lived applications. However, because any change inside +the FIPS boundary requires re-validation, as such these newer tests cannot be back-ported to older validated +modules (e.g. v5.x or v6.x). Customers running an older module version will need to use the +mitigation strategies above until they migrate to the v7.0.0 module once it is validated. +