Building wolfProvider
Getting wolfProvider Source Code
The most recent version of wolfProvider can be obtained directly from wolfSSL Inc. Contact facts@wolfssl.com for more information.
wolfProvider Package Structure
The general wolfProvider package is structured as follows:
certs/ (Test certificates and keys, used with unit tests)
docs/ (Integration and FIPS integration guides)
examples/ (Code examples)
include/
wolfprovider/ (wolfProvider header files)
IDE/ (Integration examples, including the Windows Visual Studio solution)
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)
Building on *nix
The quickest method is to use the scripts/build-wolfprovider.sh script as follows:
./scripts/build-wolfprovider.sh
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.5.4 WOLFSSL_TAG=v5.9.2-stable WOLFPROV_DEBUG=1 ./scripts/build-wolfprovider.sh
Specifying arguments for the script to parse:
./scripts/build-wolfprovider.sh --openssl-ver=openssl-3.5.4 --wolfssl-ver=v5.9.2-stable --debug
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
A pre-installed version of OpenSSL may be used with wolfProvider, or OpenSSL can be recompiled for use with wolfProvider. General instructions for compiling OpenSSL on *nix-like platforms will be similar to the following. For complete and comprehensive OpenSSL build instructions, reference the OpenSSL INSTALL file and documentation.
# Check out the latest patch release of a supported OpenSSL 3.x series.
git clone https://github.com/openssl/openssl.git
cd openssl
git checkout "$(git tag -l 'openssl-3.*' | grep -Ev 'alpha|beta' | sort -V | tail -1)"
./config no-fips shared
make
sudo make install
Always build against the latest patch release of your chosen OpenSSL 3.x series (see the OpenSSL Version Compatibility chapter); older point releases may be missing security fixes.
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 FIPSv5" bundle on Linux:
cd wolfssl-X.X.X-commercial-fips-linuxv5
./configure --enable-fips=v5 CFLAGS="-DWOLFSSL_PUBLIC_MP"
make
./wolfcrypt/test/testwolfcrypt
# modify fips_test.c using the 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
./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-sha3 and --enable-shake256 to include SHA-3 and SHAKE-256 support.
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 math. 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.
If cloning wolfSSL from GitHub, you will need to run the autogen.sh script before running ./configure. This will generate the configure script:
./autogen.sh
Building wolfProvider
When building wolfProvider on Linux or other *nix-like systems, use the autoconf system. To configure and compile wolfProvider run the following two commands from the wolfProvider root directory:
./configure
make
If building wolfProvider from GitHub, run autogen.sh before running configure:
./autogen.sh
Any number of build options can be appended to ./configure. For a list of available build options, please reference the “Build Options” section below or run the following command to see a list of available build options to pass to the ./configure script:
./configure --help
wolfProvider will use the system default OpenSSL library installation unless changed with the “--with-openssl” configure option:
./configure --with-openssl=/usr/local/ssl
The custom OpenSSL installation location may also need to be added to your library search path. On Linux, LD_LIBRARY_PATH is used:
export LD_LIBRARY_PATH=/usr/local/ssl/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}
To build then install wolfProvider, run:
make
make install
You may need superuser privileges to install, in which case precede the command with sudo:
sudo make install
To test the build, run the built-in tests from the root wolfProvider directory:
./test/unit.test
Or use autoconf to run the tests:
make check
If you get an error like error while loading shared libraries: libssl.so.3 then the library cannot be found. Use the LD_LIBRARY_PATH environment variable as described in the section above.
Building on Windows (Visual Studio)
wolfProvider includes a Visual Studio 2022 solution at IDE/WINVS/wolfprovider.sln that builds libwolfprov.dll, an OpenSSL 3.x provider backed by wolfSSL. The DLL name matters: -provider libwolfprov resolves to libwolfprov.dll. There is no configure step on Windows; wolfSSL is configured through a user_settings.h.
Prerequisites:
- Visual Studio 2022 with the C++ toolset (v143) and MASM (
ml64.exe). - Perl (for example Strawberry Perl), NASM, and git, to build OpenSSL. NASM is a separate install from Perl.
The solution provides four x64 configurations. DLL Release and DLL Debug build the shipped provider (libwolfprov.dll); Static Release and Static Debug build unit-test.exe, which links wolfProvider statically to run the unit tests. The shipped provider is the DLL; a statically linked wolfProvider is instead registered as an OpenSSL built-in provider via OSSL_PROVIDER_add_builtin() (see the Loading wolfProvider chapter). wolfProvider, wolfSSL, and OpenSSL are expected to sit side by side; the paths are set in wolfprovider.props and can be overridden on the command line (for example /p:wolfCryptDir=D:\wolfssl). Both non-FIPS and FIPS wolfSSL builds are supported.
Build Options (./configure Options)
The following are options which may be appended to the ./configure script to customize how the wolfProvider library is built.
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 |
|---|---|---|
| --disable-option-checking | Disabled | |
| --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-singlethreaded | Disabled | Enable wolfProvider single threaded |
| --enable-debug-silent | Disabled | With --enable-debug, compile debug logging in but keep it silent until enabled at runtime via WOLFPROV_LOG_LEVEL / WOLFPROV_LOG_COMPONENTS (has no effect without --enable-debug) |
| --enable-replace-default | Disabled | Compile wolfProvider with -DWOLFPROV_REPLACE_DEFAULT for replace-default mode. Making wolfProvider the default provider also requires building OpenSSL with wolfProvider's provider_predefined.c replacement; use scripts/build-wolfprovider.sh --replace-default for the complete setup |
| --enable-seed-src | Disabled | Enable the SEED-SRC entropy source with /dev/urandom caching for fork-safe entropy |
| --enable-pqc | Disabled | Enable ML-KEM, ML-DSA and SLH-DSA (FIPS 203/204/205). Requires wolfSSL master/v5.9.2+ and OpenSSL 3.6+ |
| --enable-mlkem | Disabled | Enable ML-KEM (FIPS 203) only |
| --enable-mldsa | Disabled | Enable ML-DSA (FIPS 204) only |
| --enable-slhdsa | Disabled | Enable SLH-DSA (FIPS 205) only |
| --enable-lms | Disabled | Enable LMS verification only |
| --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_USER_SETTINGS | Define this (in your build flags or user_settings.h) to have wolfProvider read user-specified defines from user_settings.h. Some source files currently also check the shorter name WOLFPROV_USER_SETTINGS. The separate --enable-usersettings configure option tells the build not to add its own Makefile CFLAGS; it does not define this macro. |
| 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_KBKDF | KBKDF (Key-Based Key Derivation Function) support |
| WP_HAVE_KRB5KDF | Kerberos 5 Key Derivation Function support |
| WP_HAVE_LMS | LMS (RFC 8554 / SP 800-208) verification support |
| WP_HAVE_MD5 | MD5 hash algorithm support |
| WP_HAVE_MD5_SHA1 | MD5+SHA1 combination support |
| WP_HAVE_MLDSA | ML-DSA (FIPS 204) post-quantum signature support |
| WP_HAVE_MLKEM | ML-KEM (FIPS 203) post-quantum key encapsulation 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_SEED_SRC | SEED-SRC entropy source 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_SSHKDF | SSHKDF (SSH Key Derivation Function) support |
| WP_HAVE_SLHDSA | SLH-DSA (FIPS 205) post-quantum signature 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 |