Update naming to be consistent, doc updates per comments

Author: ColtonWilley

docs/FIPS_INTEGRATION_GUIDE.md

@@ -23,7 +23,7 @@ For non-FIPS builds and general wolfProvider setup, see the [Integration Guide](
 
 ### Patch OpenSSL
 
-Apply FIPS baseline restrictions to your OpenSSL source tree. See [FIPS Baseline Patches](../patches/openssl-fips-baseline/README.md) for detailed options and common errors.
+Apply FIPS baseline restrictions to your OpenSSL source tree. This mode disables non-FIPS approved algorithms so one can evaluate their application before integrating wolfProvider. See [FIPS Baseline Patches](../patches/openssl-fips-baseline/README.md) for detailed options and common errors.
 
 ```bash
 ./scripts/patch-openssl-fips.sh --openssl-src=/path/to/openssl-3.x
@@ -50,7 +50,7 @@ openssl list -providers
 | Restriction | Requirement |
 |-------------|-------------|
 | RSA Key Size | 2048 bits minimum |
-| SHA1 Signing | Blocked (verification allowed) |
+| SHA1 Signing | Blocked for signing (verification and hashing/digests still allowed) |
 | ECDSA Curves | P-256, P-384, P-521 only |
 | PBKDF2 Password | 14 bytes minimum |
 | DH Groups | FFDHE only (no MODP) |
@@ -60,6 +60,9 @@ openssl list -providers
 Run your application's test suite against the baseline build. Fix any failures before proceeding.
 The goal should be an application test suite that only uses FIPS compliant algorithms.
 
+If you encounter failures, consult the **Common Failures** table below for quick fixes. For additional
+assistance, contact [wolfSSL support](mailto:support@wolfssl.com) for consulting.
+
 ```bash
 # Example tests
 openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048  # Should succeed
@@ -68,16 +71,6 @@ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:1024  # Should fail
 /path/to/your/application/test-suite # Ensure your application test suite works properly
 ```
 
-### Important Limitations
-
-> **Note:** FIPS baseline testing filters non-approved algorithms at the OpenSSL provider level, but passing these tests does not guarantee full FIPS compliance. You should also review your application for:
->
-> - **Inline cryptography** - Custom crypto implementations that don't use OpenSSL APIs
-> - **Legacy OpenSSL 1.x APIs** - Some older APIs bypass the provider architecture entirely
-> - **Non-provider operations** - Direct calls to low-level OpenSSL functions
->
-> A thorough code review is recommended to ensure all cryptographic operations route through OpenSSL's provider interface.
-
 ### Common Failures
 
 | Issue | Symptom | Solution |
@@ -88,12 +81,21 @@ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:1024  # Should fail
 | Short PBKDF2 password | `invalid salt length` | Use 14+ byte passwords |
 | MODP DH groups | Group not available | Use FFDHE groups |
 
+### Important Limitations
+
+> **Note:** FIPS baseline testing filters non-approved algorithms at the OpenSSL provider level, but passing these tests does not guarantee full FIPS compliance. You should also review your application for:
+>
+> - **Inline cryptography** - Custom crypto implementations that don't use OpenSSL APIs
+> - **Legacy OpenSSL 1.x APIs** - Some older APIs bypass the provider architecture entirely
+> - **Non-provider operations** - Direct calls to low-level OpenSSL functions
+>
+> A thorough code review is recommended to ensure all cryptographic operations route through OpenSSL's provider interface.
+
 ---
 
 ## Replace Default Mode (Recommended for FIPS)
 
-FIPS certification applies system-wide, meaning all cryptographic operations should use the FIPS-validated module. wolfProvider's replace-default mode ensures this by making wolfProvider the primary cryptographic provider for all OpenSSL operations. In this model it is impossible for an application
-to use the default provider, any attempts to do so will yield wolfProvider instead.
+FIPS certification applies system-wide, meaning all cryptographic operations should use the FIPS-validated module. wolfProvider's replace-default mode ensures this by making wolfProvider the primary cryptographic provider for all OpenSSL operations. In this model it is impossible for an application to use the default provider, any attempts to do so will yield wolfProvider instead.
 
 **Why use replace-default for FIPS:**
 - Ensures all crypto operations use wolfSSL's FIPS-validated implementations
@@ -106,12 +108,12 @@ to use the default provider, any attempts to do so will yield wolfProvider inste
 
 Once baseline testing passes, build wolfProvider with your FIPS bundle. You have two options:
 
-- **Build Script** - A convenience wrapper that fetches dependencies (OpenSSL, wolfSSL) and handles configuration automatically
+- **Build Script (Recommended)** - A convenience wrapper that fetches dependencies (OpenSSL, wolfSSL) and handles configuration automatically
 - **Manual Build** - Build each component directly using autotools
 
 Choose the approach that fits your workflow.
 
-### Build Script
+### Option A: Build Script (Recommended)
 
 The build script (`scripts/build-wolfprovider.sh`) is a convenience wrapper that automates:
 

docs/INTEGRATION_GUIDE.md

@@ -188,6 +188,34 @@ See comments in that file for examples.
 
 ---
 
+## Verifying Installation
+
+After building and installing wolfProvider, confirm that it is working correctly.
+
+### Check Provider Availability
+
+```bash
+openssl list -providers
+```
+
+This should list wolfProvider among the available providers.
+
+### Run Unit Tests
+
+```bash
+make test
+```
+
+### Run Command Line Tests
+
+```bash
+./scripts/run-tests.sh
+```
+
+If any tests fail, enable debug logging (see the [Debugging](#debugging) section) and review the output for details.
+
+---
+
 ## Support
 
 - [GitHub Issues](https://github.com/wolfssl/wolfProvider/issues)

test/standalone/tests/fips_baseline/run.sh

@@ -35,13 +35,13 @@ echo ""
 # Detect FIPS version
 FIPS_VERSION="unknown"
 
-# Check if provider output indicates FIPS mode
-if ${OPENSSL_BIN} list -providers 2>/dev/null | grep -qi "fips"; then
+# Check if provider output indicates FIPS baseline mode
+if ${OPENSSL_BIN} list -providers 2>/dev/null | grep -qi "Baseline"; then
     FIPS_VERSION="fips"
-    echo "FIPS provider detected"
+    echo "FIPS Baseline provider detected"
 else
     FIPS_VERSION="none"
-    echo "No FIPS provider detected (running in non-FIPS mode)"
+    echo "No FIPS Baseline provider detected (running in non-FIPS Baseline mode)"
 fi
 
 # Try to get more specific version info from openssl

test/standalone/tests/fips_baseline/test_fips_baseline.h

@@ -36,13 +36,16 @@ extern OSSL_PROVIDER *g_default_prov;
 extern OSSL_PROVIDER *g_wolfprov;
 
 /* Global library contexts - one for each provider (defined in test_fips_baseline.c) */
-extern OSSL_LIB_CTX *g_default_libctx;
-extern OSSL_LIB_CTX *g_wolfprov_libctx;
+extern OSSL_LIB_CTX *osslLibCtx;
+extern OSSL_LIB_CTX *wpLibCtx;
 
 /* Setup and cleanup functions (implemented in test_fips_baseline.c) */
 int setup_and_verify_providers(void);
 void cleanup_providers(void);
 
+/* FIPS sanity check (implemented in test_fips_baseline_digest.c) */
+int test_fips_sanity(void);
+
 /* Digest restriction tests (implemented in test_fips_baseline_digest.c) */
 int test_md5_restriction(void);
 

test/standalone/tests/fips_baseline/test_fips_baseline_ciphers.c

@@ -68,13 +68,13 @@ static int test_des_restriction(void)
     TEST_INFO("  Testing DES cipher restriction:");
 
     /* Test with wolfProvider */
-    if (test_cipher_unavailable(g_wolfprov_libctx, "DES-CBC", "wolfProvider") != TEST_SUCCESS) {
+    if (test_cipher_unavailable(wpLibCtx, "DES-CBC", "wolfProvider") != TEST_SUCCESS) {
         TEST_ERROR("    DES restriction test failed for wolfProvider");
         return TEST_FAILURE;
     }
 
     /* Test with default (baseline) provider */
-    if (test_cipher_unavailable(g_default_libctx, "DES-CBC", "default (baseline)") != TEST_SUCCESS) {
+    if (test_cipher_unavailable(osslLibCtx, "DES-CBC", "default (baseline)") != TEST_SUCCESS) {
         TEST_ERROR("    DES restriction test failed for default (baseline) provider");
         return TEST_FAILURE;
     }
@@ -93,13 +93,13 @@ static int test_3des_restriction(void)
     TEST_INFO("  Testing 3DES cipher restriction:");
 
     /* Test with wolfProvider */
-    if (test_cipher_unavailable(g_wolfprov_libctx, "DES-EDE3-CBC", "wolfProvider") != TEST_SUCCESS) {
+    if (test_cipher_unavailable(wpLibCtx, "DES-EDE3-CBC", "wolfProvider") != TEST_SUCCESS) {
         TEST_ERROR("    3DES restriction test failed for wolfProvider");
         return TEST_FAILURE;
     }
 
     /* Test with default (baseline) provider */
-    if (test_cipher_unavailable(g_default_libctx, "DES-EDE3-CBC", "default (baseline)") != TEST_SUCCESS) {
+    if (test_cipher_unavailable(osslLibCtx, "DES-EDE3-CBC", "default (baseline)") != TEST_SUCCESS) {
         TEST_ERROR("    3DES restriction test failed for default (baseline) provider");
         return TEST_FAILURE;
     }
@@ -118,13 +118,13 @@ static int test_chacha20_restriction(void)
     TEST_INFO("  Testing ChaCha20 cipher restriction:");
 
     /* Test with wolfProvider */
-    if (test_cipher_unavailable(g_wolfprov_libctx, "ChaCha20", "wolfProvider") != TEST_SUCCESS) {
+    if (test_cipher_unavailable(wpLibCtx, "ChaCha20", "wolfProvider") != TEST_SUCCESS) {
         TEST_ERROR("    ChaCha20 restriction test failed for wolfProvider");
         return TEST_FAILURE;
     }
 
     /* Test with default (baseline) provider */
-    if (test_cipher_unavailable(g_default_libctx, "ChaCha20", "default (baseline)") != TEST_SUCCESS) {
+    if (test_cipher_unavailable(osslLibCtx, "ChaCha20", "default (baseline)") != TEST_SUCCESS) {
         TEST_ERROR("    ChaCha20 restriction test failed for default (baseline) provider");
         return TEST_FAILURE;
     }
@@ -143,13 +143,13 @@ static int test_chacha20_poly1305_restriction(void)
     TEST_INFO("  Testing ChaCha20-Poly1305 cipher restriction:");
 
     /* Test with wolfProvider */
-    if (test_cipher_unavailable(g_wolfprov_libctx, "ChaCha20-Poly1305", "wolfProvider") != TEST_SUCCESS) {
+    if (test_cipher_unavailable(wpLibCtx, "ChaCha20-Poly1305", "wolfProvider") != TEST_SUCCESS) {
         TEST_ERROR("    ChaCha20-Poly1305 restriction test failed for wolfProvider");
         return TEST_FAILURE;
     }
 
     /* Test with default (baseline) provider */
-    if (test_cipher_unavailable(g_default_libctx, "ChaCha20-Poly1305", "default (baseline)") != TEST_SUCCESS) {
+    if (test_cipher_unavailable(osslLibCtx, "ChaCha20-Poly1305", "default (baseline)") != TEST_SUCCESS) {
         TEST_ERROR("    ChaCha20-Poly1305 restriction test failed for default (baseline) provider");
         return TEST_FAILURE;
     }

test/standalone/tests/fips_baseline/test_fips_baseline_dh.c

@@ -126,7 +126,7 @@ static int test_modp_2048_blocked(void)
     TEST_INFO("  Test 1: modp_2048 named group (must be BLOCKED)");
 
     /* wolfProvider should block */
-    wolf_blocked = (try_dh_named_group(g_wolfprov_libctx, "modp_2048") == 0);
+    wolf_blocked = (try_dh_named_group(wpLibCtx, "modp_2048") == 0);
     TEST_INFO("    [wolfProvider] modp_2048: %s",
               wolf_blocked ? "BLOCKED" : "ALLOWED");
 
@@ -136,7 +136,7 @@ static int test_modp_2048_blocked(void)
     }
 
     /* Baseline should also block (after patch) */
-    baseline_blocked = (try_dh_named_group(g_default_libctx, "modp_2048") == 0);
+    baseline_blocked = (try_dh_named_group(osslLibCtx, "modp_2048") == 0);
     TEST_INFO("    [baseline] modp_2048: %s",
               baseline_blocked ? "BLOCKED" : "ALLOWED");
 
@@ -160,7 +160,7 @@ static int test_small_custom_dh_blocked(void)
     TEST_INFO("  Test 2: 1024-bit custom DH keygen (must be BLOCKED)");
 
     /* wolfProvider should block */
-    wolf_blocked = (try_dh_custom_keygen(g_wolfprov_libctx, 1024) == 0);
+    wolf_blocked = (try_dh_custom_keygen(wpLibCtx, 1024) == 0);
     TEST_INFO("    [wolfProvider] 1024-bit custom DH: %s",
               wolf_blocked ? "BLOCKED" : "ALLOWED");
 
@@ -170,7 +170,7 @@ static int test_small_custom_dh_blocked(void)
     }
 
     /* Baseline should also block (after patch) */
-    baseline_blocked = (try_dh_custom_keygen(g_default_libctx, 1024) == 0);
+    baseline_blocked = (try_dh_custom_keygen(osslLibCtx, 1024) == 0);
     TEST_INFO("    [baseline] 1024-bit custom DH: %s",
               baseline_blocked ? "BLOCKED" : "ALLOWED");
 
@@ -200,7 +200,7 @@ static int test_ffdhe2048_allowed(void)
     TEST_INFO("  Test 3: ffdhe2048 named group (must be ALLOWED)");
 
     /* wolfProvider should allow */
-    wolf_allowed = (try_dh_named_group(g_wolfprov_libctx, "ffdhe2048") == 1);
+    wolf_allowed = (try_dh_named_group(wpLibCtx, "ffdhe2048") == 1);
     TEST_INFO("    [wolfProvider] ffdhe2048: %s",
               wolf_allowed ? "ALLOWED" : "BLOCKED");
 
@@ -210,7 +210,7 @@ static int test_ffdhe2048_allowed(void)
     }
 
     /* Baseline should also allow */
-    baseline_allowed = (try_dh_named_group(g_default_libctx, "ffdhe2048") == 1);
+    baseline_allowed = (try_dh_named_group(osslLibCtx, "ffdhe2048") == 1);
     TEST_INFO("    [baseline] ffdhe2048: %s",
               baseline_allowed ? "ALLOWED" : "BLOCKED");
 

test/standalone/tests/fips_baseline/test_fips_baseline_digest.c

@@ -26,6 +26,96 @@
 
 #include "test_fips_baseline.h"
 
+/**
+ * Test that a basic FIPS-approved operation (SHA-256 digest) works.
+ * This provides a positive sanity check before running restriction tests.
+ *
+ * @param libctx Library context with provider loaded
+ * @param desc Description for logging
+ * @return TEST_SUCCESS if SHA-256 works, TEST_FAILURE otherwise.
+ */
+static int test_sha256_available(OSSL_LIB_CTX *libctx, const char *desc)
+{
+    EVP_MD *sha256 = NULL;
+    EVP_MD_CTX *mdctx = NULL;
+    unsigned char digest[EVP_MAX_MD_SIZE];
+    unsigned int digest_len = 0;
+    const char *test_data = "FIPS sanity check test data";
+    int ret = TEST_FAILURE;
+
+    TEST_INFO("  Testing with %s...", desc);
+
+    sha256 = EVP_MD_fetch(libctx, "SHA256", NULL);
+    if (sha256 == NULL) {
+        TEST_ERROR("    ✗ SHA-256 is unavailable (should be available in FIPS)");
+        ERR_clear_error();
+        goto cleanup;
+    }
+
+    mdctx = EVP_MD_CTX_new();
+    if (mdctx == NULL) {
+        TEST_ERROR("    ✗ Failed to create EVP_MD_CTX");
+        goto cleanup;
+    }
+
+    if (EVP_DigestInit_ex(mdctx, sha256, NULL) != 1) {
+        TEST_ERROR("    ✗ SHA-256 DigestInit failed");
+        ERR_clear_error();
+        goto cleanup;
+    }
+
+    if (EVP_DigestUpdate(mdctx, test_data, strlen(test_data)) != 1) {
+        TEST_ERROR("    ✗ SHA-256 DigestUpdate failed");
+        ERR_clear_error();
+        goto cleanup;
+    }
+
+    if (EVP_DigestFinal_ex(mdctx, digest, &digest_len) != 1) {
+        TEST_ERROR("    ✗ SHA-256 DigestFinal failed");
+        ERR_clear_error();
+        goto cleanup;
+    }
+
+    if (digest_len != 32) {
+        TEST_ERROR("    ✗ SHA-256 digest length is %u (expected 32)", digest_len);
+        goto cleanup;
+    }
+
+    TEST_INFO("    ✓ SHA-256 digest works correctly (len=%u)", digest_len);
+    ret = TEST_SUCCESS;
+
+cleanup:
+    EVP_MD_CTX_free(mdctx);
+    EVP_MD_free(sha256);
+    return ret;
+}
+
+/**
+ * FIPS sanity check: verify that SHA-256 (a FIPS-approved algorithm) works
+ * with both providers before testing restrictions.
+ *
+ * @return TEST_SUCCESS if both providers support SHA-256, TEST_FAILURE otherwise.
+ */
+int test_fips_sanity(void)
+{
+    TEST_INFO("Testing FIPS sanity (SHA-256 should work with both providers):");
+
+    /* Test with wolfProvider */
+    if (test_sha256_available(wpLibCtx, "wolfProvider") != TEST_SUCCESS) {
+        TEST_ERROR("FIPS sanity check failed for wolfProvider");
+        return TEST_FAILURE;
+    }
+
+    /* Test with default (baseline) provider */
+    if (test_sha256_available(osslLibCtx, "default (baseline)") != TEST_SUCCESS) {
+        TEST_ERROR("FIPS sanity check failed for default (baseline) provider");
+        return TEST_FAILURE;
+    }
+
+    TEST_INFO("✓ Both providers support SHA-256 (FIPS sanity check passed)");
+    return TEST_SUCCESS;
+}
+
 /**
  * Test that MD5 digest is unavailable in FIPS mode.
  *
@@ -66,13 +156,13 @@ int test_md5_restriction(void)
     TEST_INFO("Testing MD5 restriction with both providers:");
 
     /* Test with wolfProvider */
-    if (test_md5_unavailable(g_wolfprov_libctx, "wolfProvider") != TEST_SUCCESS) {
+    if (test_md5_unavailable(wpLibCtx, "wolfProvider") != TEST_SUCCESS) {
         TEST_ERROR("MD5 restriction test failed for wolfProvider");
         return TEST_FAILURE;
     }
 
     /* Test with default (baseline) provider */
-    if (test_md5_unavailable(g_default_libctx, "default (baseline)") != TEST_SUCCESS) {
+    if (test_md5_unavailable(osslLibCtx, "default (baseline)") != TEST_SUCCESS) {
         TEST_ERROR("MD5 restriction test failed for default (baseline) provider");
         return TEST_FAILURE;
     }