Skip to content

Initial implementation of opensl FIPS baseline process #357

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ColtonWilley wants to merge 2 commits into
base: master
Choose a base branch
from
+13,109 −220
Open

Initial implementation of opensl FIPS baseline process #357

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0115b55
Initial implementation of opensl FIPS baseline process
ColtonWilley Feb 4, 2026
26fb139
Update naming to be consistent, doc updates per comments
ColtonWilley Feb 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
276 changes: 58 additions & 218 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,238 +3,78 @@

wolfProvider is a library that can be used as a Provider in OpenSSL.

## Features

* MD5-1
* SHA-1
* SHA-224
* SHA-256
* SHA-384
* SHA-512
* SHA-512/224
* SHA-512/256
* SHA3-224
* SHA3-256
* SHA3-384
* SHA3-512
* SHAKE 256
* AES
* 128, 192, and 256 bit keys
* ECB
* CBC
* CTR
* GCM
* CCM
* DRBG
* RSA, RSA-PSS
* Signing, Verification
* Asymmetric Encrypt, Decrypt
* Key generation
* DH
* ECC
* ECDSA
* ECDH
* Key generation
* Curve P-192
* Curve P-224
* Curve P-256
* Curve P-384
* Curve P-521
* HMAC
* CMAC
* GMAC
* HKDF
* PBKDF2
* PKCS12 PBKDF2
* TLS1_3 KDF
* TLS1 PRF

## Building
The quickest method is to use the `scripts/build-wolfprovider.sh` script as follows:

```
./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:

```
OPENSSL_TAG=openssl-3.5.0 WOLFSSL_TAG=v5.8.0-stable WOLFPROV_DEBUG=1 scripts/build-wolfprovider.sh
```

Or you can set them with variables like so:

```
./scripts/build-wolfprovider.sh --debug --openssl-ver=openssl-3.5.0 --wolfssl-ver=v5.8.0-stable
```

To clean the build, use the following:
```
./scripts/build-wolfprovider.sh --clean
```

To remove all source directories, use the following:
```
./scripts/build-wolfprovider.sh --distclean
```

Alternatively, you can manually compile each component using the following guide.

### OpenSSL

```
git clone --depth=1 -b openssl-3.0.0 https://github.com/openssl/openssl.git
cd openssl
./config no-fips shared
make
sudo make install
```

### wolfSSL

```
git clone https://github.com/wolfssl/wolfssl.git
cd wolfssl
./autogen.sh
./configure --enable-opensslcoexist --enable-cmac --enable-keygen --enable-sha --enable-des3 --enable-aesctr --enable-aesccm --enable-x963kdf --enable-compkey CPPFLAGS="-DHAVE_AES_ECB -DWOLFSSL_AES_DIRECT -DWC_RSA_NO_PADDING -DWOLFSSL_PUBLIC_MP -DHAVE_PUBLIC_FFDHE -DWOLFSSL_DH_EXTRA -DWOLFSSL_PSS_LONG_SALT -DWOLFSSL_PSS_SALT_LEN_DISCOVER -DRSA_MIN_SIZE=1024" --enable-certgen --enable-aeskeywrap --enable-enckeys --enable-base16 --with-eccminsz=192
make
sudo make install
```

Add `--enable-aesgcm-stream` if available for better AES-GCM support.
Add `--enable-curve25519` to include support for X25519 Key Exchange.
Add `--enable-curve448` to include support for X448 Key Exchange.
Add `--enable-ed25519` to include support for Ed25519 signatures and certificates..
Add `--enable-ed448` to include support for Ed448 signature and certificates.

Add `--enable-pwdbased` to the configure command above if PKCS#12 is used in OpenSSL.

Add to CPPFLAGS `-DHAVE_FFDHE_6144 -DHAVE_FFDHE_8192 -DFP_MAX_BITS=16384` to enable predefined 6144-bit and 8192-bit DH parameters.

Add to `--enable-hmac-copy` if performing HMAC repeatedly with the same key to improve performance. (Available with wolfSSL 5.7.8+.)

Add `--enable-sp=yes,asm' '--enable-sp-math-all'` to use SP Integer maths. Replace `-DFP_MAX_BITS=16384` with -DSP_INT_BITS=8192` when used.

Remove `-DWOLFSSL_PSS_LONG_SALT -DWOLFSSL_PSS_SALT_LEN_DISCOVER` and add `--enable-fips=v2` to the configure command above if building from a FIPS v2 bundle and not the git repository. Change `--enable-fips=v2` to `--enable-fips=ready` if using a FIPS Ready bundle.

If '--with-eccminsz=192' is not supported by wolfSSL, add '-DECC_MIN_KEY_SZ=192' to the CPPFLAGS.
## Supported OpenSSL Versions

### wolfProvider
wolfProvider supports all release versions of OpenSSL 3.x

```
./autogen.sh
./configure
make
```
## Replace Default Mode

To build using a different OpenSSL installation directory (e.g. one at /usr/local/ssl) use:
wolfProvider can be configured to replace OpenSSL's default provider, making wolfSSL's
cryptographic implementations the default for all OpenSSL operations. This ensures
applications use wolfSSL crypto without code changes. See the [Integration Guide](docs/INTEGRATION_GUIDE.md) for details.

```
./configure --with-openssl=/usr/local/ssl
make
export LD_LIBRARY_PATH=/usr/local/ssl/lib
make check
```
## Documentation

## Building with FIPS
Information on how to configure, build, and test wolfProvider can be found here:

To build and test with our prebuilt FIPS bundle, use the following command to build wolfProvider with FIPS enabled. You can refer to `.github/workflows/fips-ready.yml` for the workflow that does this.
- [wolfProvider FIPS Integration Guide](docs/FIPS_INTEGRATION_GUIDE.md) - FIPS baseline and production builds
- [wolfProvider Integration Guide](docs/INTEGRATION_GUIDE.md) - General integration and replace-default mode

Go to our website to download the FIPS bundle. [here](https://www.wolfssl.com/download/) and select wolfssl-5.8.2-gplv3-fips-ready.zip.

or you can use wget to download the FIPS bundle like so:
```
wget -O wolfssl-fips-ready.zip https://www.wolfssl.com/wolfssl-5.8.2-gplv3-fips-ready.zip
unzip wolfssl-fips-ready.zip
```

Then use the following command to build wolfProvider with FIPS enabled.
```
./scripts/build-wolfprovider.sh --fips-bundle="path/to/fips-bundle" --fips-check=ready --distclean
```

## Building with Replace Default

wolfProvider can be configured to replace OpenSSL's default provider, making wolfProvider the default cryptographic provider for all OpenSSL operations. This is useful for applications that want to use wolfSSL's cryptographic implementations without modifying their code.

### Replace Default vs. Standard Provider Mode

Replace default mode is fundamentally different from the standard provider approach:

**Standard Provider Mode:** When wolfProvider is loaded as a standard provider alongside OpenSSL's default provider, applications can still access OpenSSL's native crypto implementations in several ways:
- When an application explicitly requests a specific provider (e.g., "default") for an algorithm
- When wolfProvider doesn't implement a particular algorithm, OpenSSL falls back to its built-in implementations
- If the execution environment does not pick up the specified configuration file enabling
use of wolfProvider

**Replace Default Mode:** This mode patches OpenSSL to disable many of these fallback paths.
When replace default is enabled:
- wolfProvider becomes the primary cryptographic provider
- Requests for the "default" provider are redirected to wolfProvider
- Requests for the "fips" provider are redirected to wolfProvider
- Requests for the "wolfProvider" provider are redirected to wolfProvider
- This ensures maximum use of wolfSSL's cryptographic implementations for testing and validation

This makes replace default mode particularly useful for comprehensive testing scenarios where you want to ensure that wolfSSL's implementations are being used throughout the entire system.

### Basic Replace Default

To build wolfProvider as a replacement for OpenSSL's default provider:

```bash
./scripts/build-wolfprovider.sh --replace-default
```

This patches OpenSSL so that wolfProvider becomes the default provider.

### Replace Default with Testing Support

For unit testing with replace-default enabled, you need additional support to load the real OpenSSL default provider alongside wolfProvider. This requires both flags:

```bash
./scripts/build-wolfprovider.sh --replace-default --enable-replace-default-testing
```

### Important Notes

**For `--replace-default`:**
- Can be used standalone in production or testing environments
- Makes wolfProvider the default cryptographic provider

**For `--enable-replace-default-testing`:**
**Warning:** This option patches OpenSSL to export internal symbols that are not part of the public API. This configuration:
- Should only be used for development and testing
- Is not suitable for production deployments

### Examples

Build with replace-default only:
```bash
./scripts/build-wolfprovider.sh --replace-default
```
## Features

Build with replace-default and unit testing support:
```bash
./scripts/build-wolfprovider.sh --replace-default --enable-replace-default-testing
```
### Digests
* MD5
* SHA-1
* SHA-2: SHA-224, SHA-256, SHA-384, SHA-512, SHA-512/224, SHA-512/256
* SHA-3: SHA3-224, SHA3-256, SHA3-384, SHA3-512
* SHAKE-256

### Symmetric Ciphers
* AES (128, 192, 256-bit keys)
* ECB, CBC, CTR, CFB, CTS
* GCM, CCM (AEAD)
* Key Wrap
* 3DES-CBC

### MACs
* HMAC
* CMAC
* GMAC

## Testing
### KDFs
* HKDF
* PBKDF2
* PKCS12 KDF
* TLS 1.3 KDF
* TLS1 PRF
* KBKDF
* KRB5 KDF

### Unit Tests
### Random
* CTR-DRBG
* Hash-DRBG

To run automated unit tests:
* `make test`
### RSA
* Signing, Verification (PKCS#1 v1.5, PSS)
* Encryption, Decryption
* Key generation

### Command Tests
### DH
* Key exchange
* Key generation

To run the command tests:
* `./scripts/cmd_test/do-cmd-tests.sh`
### ECC
* ECDSA (signing, verification)
* ECDH (key exchange)
* Key generation
* Curves: P-192, P-224, P-256, P-384, P-521

### Integration Tests
### Curve25519/448
* X25519, X448 (key exchange)
* Ed25519, Ed448 (signatures)

To run the cipher suite testing:
* `./scripts/test-wp-cs.sh`

## Debugging
## Support

To enable wolfProvider debug logging, build with `--debug` which enables exit messages, error messages, and informational messages. If you want to filter logging a certain way or increase detail level, set `WOLFPROV_LOG_LEVEL_FILTER` and `WOLFPROV_LOG_COMPONENTS_FILTER` in `include/wolfprovider/wp_logging.h` as needed. See comments in that file for examples.
- [GitHub Issues](https://github.com/wolfssl/wolfProvider/issues)
- [wolfSSL Support](https://www.wolfssl.com/products/support-and-maintenance/)
Loading
Loading