Merge pull request #236 from kaleb-himes/Q42025-FIPS-FAQ-UPDT

FIPS FAQ UPDT Q4 2025

Author: douzzer

wolfSSL-FIPS-FAQ/src/section01.md

@@ -2,6 +2,8 @@
 
 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 [email protected].
 
+Last Updated: 8 Dec 2025
+
 ## Questions
 
 1. [Why did I receive wolfSSL_X.X.X_commercial-fips-OE-v2.7z when we validated with Y.Y.Y?](./section02.md#why-did-i-receive-wolfssl-xxx-xommercial-fips-oe-v27z-when-we=validated-with-yyy)
@@ -12,3 +14,14 @@ This page lists some of the most common issues and questions that are recieved b
 	3. [Followup Post Q: Who can determine when NO_ATTRIBUTE_CONSTRUCTOR is allowed?](./section02.md#does-the-power-on-self-test-post-really-have-to-run-every-time)
 	4. [Followup Post Q: What about with fips-ready, can I use NO_ATTRIBUTE_CONSTRUCTOR with fips-ready?](./section02.md#does-the-power-on-self-test-post-really-have-to-run-every-time)
 4. [What can go wrong for the end user after basic testing?](./section02.md#what-can-go-wrong-for-the-end-user-after-basic-testing)
+5. [Moving from 140-2 to 140-3, what's new?](./section02.md#moving-from-140-2-to-140-3-whats-new)
+	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)
+		1. [API's that require UNLOCK before first use (should also be re-LOCKED after use):](./section02.md#apis-to-unlock)
+
+

wolfSSL-FIPS-FAQ/src/section02.md

@@ -149,17 +149,64 @@ extern unsigned int my_rng_seed_gen(void);
 level */
 ```
 
+## The wc_SetSeed_Cb() callback and a custom seed generation function:
+
+To avoid potential implementation bugs users should follow the known good procedure for adding a custom seed function.
+    Step 1) In either user_settings.h or settings.h header add the following:
+
+        ```
+            /* Seed Source */
+            extern unsigned int my_rng_seed_gen(byte* output, word32 sz);
+            #undef  CUSTOM_RAND_GENERATE_SEED
+            #define CUSTOM_RAND_GENERATE_SEED  my_rng_seed_gen
+        ```
+
+    Definition: A ***Consuming Application*** is anything outside the module boundary
+                that consumes the FIPS 140-3 crypto but is not subject to the
+                FIPS 140-3 validation (may be subject to ESV but that is
+                separate from 140-3)
+
+    Step 2) At the ***Consuming Application*** level implement the callback function:
+
+        ```
+            /* @param output The buffer to fill with entropy bits one byte at a time,
+             *           if the solution returns bits instead of bytes be sure
+             *           to gather 8 times 'sz' instead of just 'sz'
+             * @param sz The number of bytes the output buffer can hold based on
+             *           declared size in the Consuming Application
+             */
+            unsigned int my_rng_seed_gen(byte* output, word32 sz)
+            {
+                /* Pseudo code */
+                fill buffer 'output' with 'sz' bytes of entropy
+                if filling fails return the appropriate error code for this system
+                otherwise return 0 to indicate success
+            }
+        ```
+
+    Step 3) Finally ***ONLY*** use the wolfSSL supplied callback wc_GenerateSeed()
+            as your seeding mechanism. Register it in the ***Consuming Application***
+            with:
+
+        ```
+            #ifdef WC_RNG_SEED_CB
+                wc_SetSeed_Cb(wc_GenerateSeed);
+            #else
+                #error "Module was not compiled with required setting WC_RNG_SEED_CB"
+            #endif
+        ```
+
 ## The POST
 Under 140-2 POST stood for "Power On Self Test" and ran EVERY algorithm self-test leading to slow power-on / boot times.
 Under 140-3 POST stands for "Pre-Operational Self Test" and only runs the integrity check of the module (and any dependency self-test to support the integrity check). Since HMAC-SHA2-256 self-test must first run and then the integrity check is performed. No other self-tests run at this stage in the 140-3.
 
-## Threading considertation for all CASTs():
+## Threading consideration for all CASTs():
 
 Calling a CAST in a thread for the first time or allowing a CAST to run automatically by using a service for the first time in a thread may result in another thread getting a "FIPS_CAST_STATE_PROCESSING" error (meaning that another thread is actively running the CAST) if it attempts to exercise the same CAST in parallel. This will result in the module dropping into the degraded mode of operation.
 
 Once degraded mode is active the only recovery from degraded mode is a power cycle of the module or by re-running the integrity test to simulate a reload/power cycle of the module. To simulate reload or power cycle of the module, shut down all threads then call wolfCrypt_IntegrityTest_fips(); before starting threads up again.
 
-To avoid this problem one can simply call wc_RunAllCast_fips()^1 on startup along with the other FIPS specific initializers. 
+To avoid this problem one can simply call wc_RunAllCast_fips() on startup along with the other FIPS specific initializers. 
 
 Example:
 
@@ -212,7 +259,7 @@ if (wc_RunCast_fips(FIPS_CAST_RSA_SIGN_PKCS1v15) != 0){
 }
 ```
 
-## wc_SetSeedCb() a bit unique:
+## wc_SetSeedCb() a bit unique with relation to CAST's:
 
 wc_SetSeed_Cb(); is the first operational use of the DRBG and as such the CAST will run when the callback is set for the first time. To avoid a race condition on the CAST users should set the seed callback one time on startup and not on a per-thread basis or one time globally and then once per thread is also acceptable if the CAST has passed by the time threads are launched. This would be for a scenario where thread-A needs entropy-source-A and thread-B uses a different entropy source. Please remember that calling wolfSSL_Init() will set the seed callback and therefore should not be called on a per-thread basis unless called at least once globally first. A good practice if setting per thread might be:
 
@@ -239,7 +286,7 @@ int main(void) {
 
 By checking the return value of the call the function should block prior to threads starting up avoiding any race conditions on the CAST completing prior to threads consuming the DRBG.
 
-##Key Access Management
+## Key Access Management
 
 1. Users calling wolfSSL (SSL/TLS) APIs’ do not need to worry about this item
 2. Users invoking wolfcrypt (wc_XXX) APIs’ directly that involve loading or using a private key must manage the key access at the application level. To be able to read in or use a private key the application must allow this by calling
@@ -304,9 +351,10 @@ static inline int true_lock(void)
 #endif
 ```
 
-API's that require UNLOCK before first use (should also be re-LOCKED after use):
+## API's that require UNLOCK before first use (should also be re-LOCKED after use):
 
 ```
+v5.2.1 (and all other v5.X.X modules)
 * wc_PRF
 * wc_PRF_TLSv12
 * wc_HKDF_Extract
@@ -329,6 +377,8 @@ API's that require UNLOCK before first use (should also be re-LOCKED after use):
 * wc_ecc_shared_secret_ex
 * wc_DhGenerateKeyPair
 * wc_DhAgree
+
+v6.0.0 and newer module add some new ones in addition to the above list:
 * wc_SRTP_KDF
 * wc_SRTCP_KDF
 * wc_SRTCP_KDF_ex
@@ -342,5 +392,8 @@ API's that require UNLOCK before first use (should also be re-LOCKED after use):
 * wc_ed448_export_key
 * wc_PBKDF2_ex
 * wc_PBKDF2
+
+v7.0.0 (upcoming)
+* Will have some additional services listed here for Post Quantum key material
 ```