wolfSSL · sebastian-carpenter · Jul 25, 2025
diff --git a/wolfProvider/Makefile b/wolfProvider/Makefile
@@ -22,6 +22,8 @@ endif
 
 .PHONY: html-prep
 html-prep:
+	$(Q)cp png/*.png build/html/
 
 .PHONY: pdf-prep
 pdf-prep:
+	$(Q)cp png/*.png build/pdf/
diff --git a/wolfProvider/src/chapter01.md b/wolfProvider/src/chapter01.md
@@ -7,6 +7,6 @@ wolfProvider is structured as a separate standalone library which links against
 For more details on the design and architecture of wolfProvider see the [wolfProvider Design](chapter09.md) chapter.
 
 
-![wolfProvider Overview](../png/wolfprovider_overview.png)
+![wolfProvider Overview](wolfProvider_overview.png)
 
 wolfProvider is compiled by default as a shared library called **libwolfprov** which can be dynamically registered at runtime by an application or OpenSSL through a config file. wolfProvider also provides an entry point for applications to load the provider when compiled in a static build.
diff --git a/wolfProvider/src/chapter02.md b/wolfProvider/src/chapter02.md
@@ -3,5 +3,6 @@
 wolfProvider has been tested against the following versions of OpenSSL. wolfProvider may work with other versions, but may require some modification or adjustment:
 
 - OpenSSL 3.0.0
+- OpenSSL 3.5.0
 
 If you are interested in having wolfSSL add support to wolfProvider for other OpenSSL versions, please contact wolfSSL at [[email protected]](mailto:[email protected]).
diff --git a/wolfProvider/src/chapter03.md b/wolfProvider/src/chapter03.md
@@ -9,14 +9,17 @@ The most recent version of wolfProvider can be obtained directly from wolfSSL In
 The general wolfProvider package is structured as follows:
 
 ```
-certs/                        (Test certificates and keys, used with unit tests)
-provider.conf              (Example OpenSSL config file using wolfProvider)
+certs/                      (Test certificates and keys, used with unit tests)
+examples/                   (Code examples)
 include/
-    wolfprovider/          (wolfProvider header files)
-scripts/                      (wolfProvider test scripts)
-src/                            (wolfProvider source files)
-test/                           (wolfProvider test files)
-user_settings.h         (EXAMPLE user_settings.h)
+    wolfprovider/           (wolfProvider header files)
+IDE/                        (Integration examples)
+scripts/                    (wolfProvider scripts for testing and building)
+src/                        (wolfProvider source files)
+test/                       (wolfProvider test files)
+provider.conf               (Example OpenSSL config file using wolfProvider)
+provider-fips.conf          (Example OpenSSL config file using wolfProvider FIPS)
+user_settings.h             (EXAMPLE user_settings.h)
 ```
 ## Building on *nix
 The quickest method is to use the `scripts/build-wolfprovider.sh` script as follows:
@@ -25,13 +28,25 @@ The quickest method is to use the `scripts/build-wolfprovider.sh` script as foll
 ./scripts/build-wolfprovider.sh
 ```
 
-It will retrieve the dependencies and compile them as necessary. To use other than the default (such as different releases) you can set various environment variables prior to calling the script:
+It will clone, configure, compile, and install OpenSSL and wolfSSL with a default set of options. Two methods are available to override these defaults:
+
+Setting the various environment variables prior to calling the script:
+
+```
+OPENSSL_TAG=openssl-3.2.0 WOLFSSL_TAG=v5.7.2-stable WOLFPROV_DEBUG=1 ./scripts/build-wolfprovider.sh
+```
+
+Specifying arguments for the script to parse:
 
 ```
-OPENSSL_TAG=openssl-3.2.0 WOLFSSL_TAG=v5.7.2-stable WOLFPROV_DEBUG=1 scripts/build-wolfprovider.sh
+./scripts/build-wolfprovider.sh --openssl-ver=openssl-3.2.0 --wolfssl-ver=v5.7.2-stable --debug
 ```
 
-Alternatively, you can manually compile each component using the following guide.
+Of course, these methods can be combined to achieve the desired build combination as well.
+
+For a full list of environment variables and script arguments do `./scripts/build-wolfprovider.sh --help`.
+
+If desired, each component can be manually compiled using the following guide.
 
 
 ### Building OpenSSL
@@ -47,20 +62,21 @@ sudo make install
 
 ### Building wolfSSL
 
-If using a FIPS-validated version of wolfSSL with wolfProvider, follow the build instructions provided with your specific FIPS validated source bundle and Security Policy. In addition to the correct “--enable-fips” configure option, wolfProvider will need wolfSSL to be compiled with “ **WOLFSSL_PUBLIC_MP** ” defined. For example, building the “wolfCrypt Linux FIPSv2” bundle on Linux:
+If using a FIPS-validated version of wolfSSL with wolfProvider, follow the build instructions provided with your specific FIPS validated source bundle and Security Policy. In addition to the correct “--enable-fips” configure option, wolfProvider will need wolfSSL to be compiled with “**WOLFSSL_PUBLIC_MP**” defined. For example, building the “wolfCrypt Linux FIPSv2” bundle on Linux:
 ```
 cd wolfssl-X.X.X-commercial-fips-linuxv
-./configure **--enable-fips=v2 CFLAGS=”-DWOLFSSL_PUBLIC_MP”**
+./configure --enable-fips=v2 CFLAGS=”-DWOLFSSL_PUBLIC_MP”
 make
 ./wolfcrypt/test/testwolfcrypt
-< modify fips_test.c using verifyCore hash output from testwolfcrypt
->
+< modify fips_test.c using verifyCore hash output from testwolfcrypt >
 make
 ./wolfcrypt/test/testwolfcrypt
 < all algorithms should PASS >
 sudo make install
 ```
 
+If available, it may be easier to instead `make` then run the `./fips-hash.sh` utility and then `make` once again. This utility automates the process of updating fips_test.c with the testwolfcrypt hash output.
+
 To build non-FIPS wolfSSL for use with wolfProvider:
 ```
 cd wolfssl-X.X.X
@@ -178,62 +194,83 @@ The following are options which may be appended to the `./configure` script to c
 
 By default, wolfProvider only builds a shared library, with building of a static library disabled. This speeds up build times by a factor of two. Either mode can be explicitly disabled or enabled if desired.
 
-| Option               | Default Value | Description |
-| :---------               | :---------------: | :-------------- |
-|  --enable-static  | **Disabled** | Build static libraries   |
-| --enable-shared | Enabled | Build shared libraries |
-|  --enable-debug | **Disabled** | Enable wolfProvider debugging support |
-|  --enable-coverage | **Disabled** | Build to generate code coverage stats |
+| Option            | Default Value     | Description                    |
+| :---------------- | :---------------: | :----------------------------- |
+| --disable-option-checking | **Disabled** | | ignore unrecognized --enable/--with options |
+| --enable-silent-rules | **Disabled** | less verbose build output (undo: "make V=1") |
+| --disable-silent-rules | **Disabled** | verbose build output (undo: "make V=0") |
+| --enable-static | **Disabled** | Build static libraries |
+| --enable-pic[=PKGS] | **Use Both** | try to use only PIC/non-PIC objects |
+| --enable-shared | **Enabled** | Build shared libraries |
+| --enable-fast-install[=PKGS] | **Enabled** |  optimize for fast installation |
+| --enable-aix-soname=aix\|svr4\|both | **aix** | shared library versioning (aka "SONAME") variant to provide on AIX |
+| --enable-dependency-tracking | **Disabled** | do not reject slow dependency extractors |
+| --disable-dependency-tracking | **Disabled** | speeds up one-time build |
+| --disable-libtool-lock | **Disabled** |  avoid locking (might break parallel builds) |
+| --enable-debug | **Disabled** | Enable wolfProvider debugging support |
+| --enable-coverage | **Disabled** | Build to generate code coverage stats |
 | --enable-usersettings | **Disabled** | Use your own user_settings.h and do not add Makefile CFLAGS |
-| --enable-dynamic | Enabled | Enable loading wolfProvider as a dynamic provider |
+| --enable-dynamic | **Enabled** | Enable loading wolfProvider as a dynamic provider |
 | --enable-singlethreaded | **Disabled** | Enable wolfProvider single threaded |
+| | | |
 | --with-openssl=DIR |   | OpenSSL installation location to link against. If not set, use the system default library and include paths. |
 | --with-wolfssl=DIR |   | wolfSSL installation location to link against. If not set, use the system default library and include paths. |
 
 ## Build Defines
 
 wolfProvider exposes several preprocessor defines that allow users to configure how wolfProvider is built. These are described in the table below.
 
-| Define                                                      | Description |
-| :---------------------------------------------- | :-------------- |
-| WOLFPROVIDER_DEBUG | Build wolfProvider with debug symbols, optimization level, and debug logging. |
-| WP_NO_DYNAMIC_PROVIDER |  Do not build wolfProvider with dynamic provider support. Dynamic providers are ones that can be loaded into OpenSSL at runtime. |
-| WP_SINGLE_THREADED | Build wolfProvider in single-threaded mode. This removes the need for locking around global resources used internally. |
-| WP_USE_HASH | Enable digest algorithms using the wc_Hash API. |
-| WP_HAVE_SHA1 | Enable SHA-1 digest algorithm. |
-| WP_HAVE_SHA224 | Enable SHA-2 digest algorithm with digest size 224. |
-| WP_HAVE_SHA256 | Enable SHA-2 digest algorithm with digest size 256. |
-| WP_HAVE_SHA384 | Enable SHA-2 digest algorithm with digest size 384. |
-| WP_HAVE_SHA512| Enable SHA-2 digest algorithm with digest size 512. |
-| WP_SHA1_DIRECT | Enable the SHA-1 digest algorithm using the wc_Sha API. Incompatible with WP_USE_HASH. |
-| WP_SHA224_DIRECT | Enable the SHA-2 224 digest algorithm using the wc_Sha224 API. Incompatible with WP_USE_HASH. |
-| WP_SHA256_DIRECT | Enable the SHA-2 256 digest algorithm using the wc_Sha256 API. Incompatible with WP_USE_HASH. |
-| WP_HAVE_SHA3_224 | Enable SHA-3 digest algorithm with digest size 224. Not available in OpenSSL 1.0.2. |
-| WP_HAVE_SHA3_256 | Enable SHA-3 digest algorithm with digest size 256. Not available in OpenSSL 1.0.2. |
-| WP_HAVE_SHA3_384 | Enable SHA-3 digest algorithm with digest size 384. Not available in OpenSSL 1.0.2. |
-| WP_HAVE_SHA3_512 | Enable SHA-3 digest algorithm with digest size 512. Not available in OpenSSL 1.0.2. |
-| WP_HAVE_EVP_PKEY | Enable functionality that uses the EVP_PKEY API. This includes things like RSA, DH, etc. |
-| WP_HAVE_CMAC | Enable CMAC algorithm. |
-| WP_HAVE_HMAC | Enable HMAC algorithm. |
-| WP_HAVE_DES3CBC | Enable DES3-CBC algorithm. |
-| WP_HAVE_AESECB | Enable AES algorithm with ECB mode. |
-| WP_HAVE_AESCBC | Enable AES algorithm with CBC mode. |
-| WP_HAVE_AESCTR | Enable AES algorithm with countee mode. |
-| WP_HAVE_AESGCM | Enable AES algorithm with GCM mode. |
-| WP_HAVE_AESCCM |Enable AES algorithm with CCM mode. |
-| WP_HAVE_RANDOM | Enable wolfCrypt random implementation. |
-| WP_HAVE_RSA | Enable RSA operations (e.g. sign, verify, key generation, etc.). |
-| WP_HAVE_DH | Enable Diffie-Hellman operations (e.g. key generation, shared secret computation, etc.). |
-| WP_HAVE_ECC | Enable support for elliptic curve cryptography. |
-| WP_HAVE_EC_KEY | Enable support for EC_KEY_METHOD. Not available in OpenSSL 1.0.2. |
-| WP_HAVE_ECDSA | Enable ECDSA algorithm. |
-| WP_HAVE_ECDH | Enable EC Diffie-Hellman operations. |
-| WP_HAVE_ECKEYGEN | Enable EC key generation. |
-| WP_HAVE_EC_P192 | Enable EC curve P192. |
-| WP_HAVE_EC_P224 | Enable EC curve P224. |
-| WP_HAVE_EC_P256 | Enable EC curve P256. |
-| WP_HAVE_EC_P384 | Enable EC curve P384. |
-| WP_HAVE_EC_P512 | Enable EC curve P512. |
-| WP_HAVE_DIGEST | Compile code in benchmark program and unit tests for use with digest algorithms. |
+| Define                           | Description |
+| :------------------------------- | :----------------------------- |
 | WOLFPROVIDER_USER_SETTINGS | Read user-specified defines from user_settings.h. |
-
+| WOLFPROV_DEBUG | Output debug information |
+| WP_CHECK_FORCE_FAIL | Force failure checking for testing purposes |
+| WP_ALLOW_NON_FIPS | Allow certain non-FIPS algorithms in FIPS mode |
+| WP_HAVE_AESCCM | AES encryption in CCM (Counter with CBC-MAC) mode |
+| WP_HAVE_AESCFB | AES encryption in CFB (Cipher Feedback) mode |
+| WP_HAVE_AESCBC | AES encryption in CBC (Cipher Block Chaining) mode |
+| WP_HAVE_AESCTR | AES encryption in CTR (Counter) mode |
+| WP_HAVE_AESCTS | AES encryption in CTS (Ciphertext Stealing) mode |
+| WP_HAVE_AESECB | AES encryption in ECB (Electronic Codebook) mode |
+| WP_HAVE_AESGCM | AES encryption in GCM (Galois/Counter Mode) mode |
+| WP_HAVE_CMAC | CMAC (Cipher-based Message Authentication Code) support |
+| WP_HAVE_DES3CBC | Triple DES encryption in CBC mode |
+| WP_HAVE_DH | Diffie-Hellman key exchange support |
+| WP_HAVE_DIGEST | General digest/hash algorithm support |
+| WP_HAVE_ECC | General Elliptic Curve Cryptography support |
+| WP_HAVE_EC_P192 | P-192 elliptic curve support |
+| WP_HAVE_EC_P224 | P-224 elliptic curve support |
+| WP_HAVE_EC_P256 | P-256 elliptic curve support |
+| WP_HAVE_EC_P384 | P-384 elliptic curve support |
+| WP_HAVE_EC_P521 | P-521 elliptic curve support |
+| WP_HAVE_ECDH | ECDH (Elliptic Curve Diffie-Hellman) key exchange support |
+| WP_HAVE_ECDSA | ECDSA (Elliptic Curve Digital Signature Algorithm) support |
+| WP_HAVE_ECKEYGEN | Elliptic curve key generation support |
+| WP_HAVE_ED25519 | Ed25519 elliptic curve signature support |
+| WP_HAVE_ED448 | Ed448 elliptic curve signature support |
+| WP_HAVE_GMAC | GMAC (Galois/Counter Mode Authentication) support |
+| WP_HAVE_HKDF | HKDF (HMAC-based Key Derivation Function) support |
+| WP_HAVE_HMAC | HMAC (Hash-based Message Authentication Code) support |
+| WP_HAVE_KRB5KDF | Kerberos 5 Key Derivation Function support |
+| WP_HAVE_MD5 | MD5 hash algorithm support |
+| WP_HAVE_MD5_SHA1 | MD5+SHA1 combination support |
+| WP_HAVE_PBE | Password-Based Encryption support |
+| WP_HAVE_RANDOM | Random number generation support |
+| WP_HAVE_RSA | RSA encryption and signature support |
+| WP_HAVE_SHA1 | SHA1 hash algorithm support |
+| WP_HAVE_SHA224 | SHA224 hash algorithm support |
+| WP_HAVE_SHA256 | SHA256 hash algorithm support |
+| WP_HAVE_SHA384 | SHA384 hash algorithm support |
+| WP_HAVE_SHA3 | SHA3 family hash algorithm support |
+| WP_HAVE_SHA3_224 | SHA3-224 hash algorithm support |
+| WP_HAVE_SHA3_256 | SHA3-256 hash algorithm support |
+| WP_HAVE_SHA3_384 | SHA3-384 hash algorithm support |
+| WP_HAVE_SHA3_512 | SHA3-512 hash algorithm support |
+| WP_HAVE_SHA512 | SHA512 hash algorithm support |
+| WP_HAVE_SHA512_224 | SHA512/224 hash algorithm support |
+| WP_HAVE_SHA512_256 | SHA512/256 hash algorithm support |
+| WP_HAVE_SHAKE_256 | SHAKE256 extendable output function support |
+| WP_HAVE_TLS1_PRF | TLS1 Pseudo-Random Function support |
+| WP_HAVE_X25519 | X25519 elliptic curve support |
+| WP_HAVE_X448 | X448 elliptic curve support |
+| WP_RSA_PSS_ENCODING | RSA-PSS (Probabilistic Signature Scheme) encoding support |
diff --git a/wolfProvider/src/chapter04.md b/wolfProvider/src/chapter04.md
@@ -6,7 +6,6 @@ Note that wolfCrypt FIPS libraries cannot be “switched” into non-FIPS mode.
 
 When wolfProvider is compiled to use wolfCrypt FIPS, it will only include support and register provider callbacks for FIPS-validated algorithms, modes, and key sizes. If OpenSSL based applications call non-FIPS validated algorithms, execution may not enter wolfProvider and could be handled by the default OpenSSL provider or other registered provider providers, based on the OpenSSL configuration. 
 
-**NOTE** : If targeting FIPS compliance,and non-wolfCrypt FIPS algorithms are called from a different provider, those algorithms are outside the scope of
-wolfProvider and wolfCrypt FIPS and may not be FIPS validated.
+**NOTE** : If targeting FIPS compliance, and non-wolfCrypt FIPS algorithms are called from a different provider, those algorithms are outside the scope of both wolfProvider and wolfCrypt FIPS and may not be FIPS validated.
 
 For more information on using wolfCrypt FIPS (140-2 / 140-3), contact wolfSSL at [email protected].
diff --git a/wolfProvider/src/chapter05.md b/wolfProvider/src/chapter05.md
@@ -5,7 +5,7 @@ wolfProvider supports output of log messages for informative and debug purposes.
 ./configure --enable-debug
 ```
 
-If not using Autoconf/configure, define `WOLFPROVIDER_DEBUG` when compiling the wolfProvider library.
+If not using Autoconf/configure, define `WOLFPROV_DEBUG` when compiling the wolfProvider library.
 
 ## Controlling Logging Levels
 
@@ -19,7 +19,7 @@ wolfProvider supports the following logging levels. These are defined in the “
 | WP_LOG_INFO | Logs informative messages | 0x0008 |
 | WP_LOG_VERBOSE | Verbose logs, including encrypted/decrypted/digested data | 0x0010 |
 | WP_LOG_LEVEL_DEFAULT | Default log level, all except verbose level | WP_LOG_ERROR &#124; WP_LOG_ENTER &#124; WP_LOG_LEAVE &#124; WP_LOG_INFO |
-WP_LOG_LEVEL_ALL WP_LOG_ERROR | All log levels are enabled | WP_LOG_ENTER &#124; WP_LOG_LEAVE &#124; WP_LOG_INFO &#124; WP_LOG_VERBOSE |
+WP_LOG_LEVEL_ALL | All log levels are enabled | WP_LOG_ERROR &#124; WP_LOG_ENTER &#124; WP_LOG_LEAVE &#124; WP_LOG_INFO &#124; WP_LOG_VERBOSE |
 
 
 The default wolfProvider logging level includes `WP_LOG_ERROR`, `WP_LOG_ENTER`, `WP_LOG_LEAVE`, and `WP_LOG_INFO`. This includes all log levels except verbose logs (`WP_LOG_VERBOSE`).
@@ -46,14 +46,15 @@ wolfProvider allows logging on a per-component basis. Components are defined in
 | WP_LOG_CIPHER | Ciphers (AES, 3DES) | 0x0008 |
 | WP_LOG_PK | Public Key Algorithms (RSA, ECC) | 0x0010 |
 | WP_LOG_KE | Key Agreement Algorithms (DH, ECDH) | 0x0020 |
-| WP_LOG_PROVIDER | All provider specific logs | 0x0040 |
-| WP_LOG_COMPONENTS_ALL | Log all components | WP_LOG_RNG &#124; WP_LOG_DIGEST &#124; WP_LOG_MAC &#124; WP_LOG_CIPHER &#124; WP_LOG_PK &#124; WP_LOG_KE &#124; WP_LOG_PROVIDER |
+| WP_LOG_KDF | Password Based Key Derivation Algorithms | 0x0040 |
+| WP_LOG_PROVIDER | All provider specific logs | 0x0080 |
+| WP_LOG_COMPONENTS_ALL | Log all components | WP_LOG_RNG &#124; WP_LOG_DIGEST &#124; WP_LOG_MAC &#124; WP_LOG_CIPHER &#124; WP_LOG_PK &#124; WP_LOG_KE &#124; WP_LOG_KDF &#124; WP_LOG_PROVIDER |
 | WP_LOG_COMPONENTS_DEFAULT | Default components logged (all). | WP_LOG_COMPONENTS_ALL |
 
 
 The default wolfProvider logging configuration logs all components (`WP_LOG_COMPONENTS_DEFAULT`).
 
-Components logged can be controlled using the `wolfProv_SetLogComponents(int mask)`. For example, to turn on only logging only for the Digest and Cipher algorithms:
+Components logged can be controlled using the `wolfProv_SetLogComponents(int mask)`. For example, to turn on logging only for the Digest and Cipher algorithms:
 ```
 #include <wolfprovider/wp_logging.h>
 
@@ -74,21 +75,21 @@ Applications that want to have more control over how or where log messages are o
 * component - [IN] - Component that log message is coming from
 * logMessage - [IN] - Log message
 */
-typedef void (* **wolfProvider_Logging_cb** )(const int logLevel,
+typedef void (* wolfProvider_Logging_cb )(const int logLevel,
 const int component,
 const char *const logMessage);
 ```
 The callback can then be registered with wolfProvider using the `wolfProv_SetLoggingCb(wolfProv_Logging_cb logf)`. For example:
 ```
-void **customLogCallback** (const int logLevel, const int component,
+void customLogCallback (const int logLevel, const int component,
 const char* const logMessage)
 {
     (void)logLevel;
     (void)component;
     fprintf(stderr, “wolfProvider log message: %d\n”, logMessage);
 }
 
-int **main** (void)
+int main (void)
 {
     int ret;
 ...

diff --git a/wolfProvider/src/chapter07.md b/wolfProvider/src/chapter07.md
@@ -10,7 +10,7 @@ If the application is configured to read/use an OpenSSL config file, additional
 
 [OpenSSL 3.0](https://www.openssl.org/docs/man3.0/man5/config.html)
 
-An application can read and consume the default OpenSSL config file (openssl.cnf) or config as set by OPENSSL\_CONF environment variable, and default [openssl\_conf] section.
+An application can read and consume the default OpenSSL config file (openssl.cnf) or config as set by OPENSSL\_CONF environment variable and default [openssl\_conf] section.
 
 Alternatively to using an OpenSSL config file, applications can explicitly initialize and register wolfProvider using the desired OSSL\_PROVIDER_\* APIs. As one example, initializing wolfProvider and registering for all algorithms could be done using:
 ```