wolfEngine

wolfEngine is an OpenSSL engine backed by wolfSSL's wolfCrypt cryptography library. wolfCrypt is FIPS-validated, so wolfEngine can be used to achieve FIPS compliance with OpenSSL, all without having to touch the OpenSSL code itself.

Features

SHA-1
SHA-224
SHA-256
SHA-384
SHA-512
SHA3-224
SHA3-256
SHA3-384
SHA3-512
DES3-CBC
AES
- 128, 192, and 256 bit keys
- ECB
- CBC
- CTR
- GCM
- CCM
DRBG
RSA
DH
ECC
- ECDSA
- ECDH
- EC key generation
- Curve P-192
- Curve P-224
- Curve P-256
- Curve P-384
- Curve P-521
HMAC
CMAC
HKDF
PBKDF2
TLS PRF

OpenSSL Version Support

wolfEngine can be used with any OpenSSL version that supports the engine framework. Engines are deprecated in OpenSSL 3.0.0. They're replaced with a similar concept called providers. wolfSSL also offers a provider backed by wolfCrypt. Please reach out to facts@wolfssl.com if you're interested in evaluating the wolfSSL provider.

Caveats

SHA-3 support is only available with OpenSSL versions 1.1.1+.
EC_KEY_METHOD is only available with OpenSSL versions 1.1.1+.

Building on *nix

OpenSSL

Assuming you've downloaded OpenSSL source code into a directory called openssl:

cd openssl
./config shared
make
sudo make install

wolfSSL

From FIPS Bundle

Use this configure command:

./configure --enable-engine

This adds support for --enable-engine=fips-v2 automatically. Replace this with --enable-engine=fips-v5 if using a FIPSv5 140-3 bundle. Replace this with --enable-engine=fips-ready if using a FIPS Ready bundle. If your wolfSSL version doesn't support --enable-engine, use this instead:

./configure --enable-fips=v2 --enable-opensslcoexist --enable-cmac
--enable-keygen --enable-sha --enable-des3 --enable-aesctr --enable-aesccm
--enable-x963kdf CPPFLAGS="-DHAVE_AES_ECB -DWOLFSSL_AES_DIRECT
-DWC_RSA_NO_PADDING -DWOLFSSL_PUBLIC_MP -DECC_MIN_KEY_SZ=192 -DSha3=wc_Sha3
-DNO_OLD_SHA256_NAMES -DNO_OLD_MD5_NAME"

Change --enable-fips=v2 to --enable-fips=ready if using a FIPS Ready bundle.

From Git

git clone https://github.com/wolfssl/wolfssl.git
cd wolfssl
./autogen.sh
./configure --enable-engine=no-fips
make
sudo make install

If your wolfSSL version doesn't support --enable-engine, use this instead:

./configure --enable-opensslcoexist --enable-cmac --enable-keygen --enable-sha
--enable-des3 --enable-aesctr --enable-aesccm --enable-x963kdf
CPPFLAGS="-DHAVE_AES_ECB -DWOLFSSL_AES_DIRECT -DWC_RSA_NO_PADDING
-DWOLFSSL_PUBLIC_MP -DECC_MIN_KEY_SZ=192 -DWOLFSSL_PSS_LONG_SALT
-DWOLFSSL_PSS_SALT_LEN_DISCOVER"

Additional Options

Add --enable-pwdbased to the configure commands above if using PKCS#12.
Add --enable-debug to turn on debug logging.

wolfEngine

git clone https://github.com/wolfSSL/wolfEngine.git
cd wolfEngine
./autogen.sh
./configure --with-openssl=/path/to/openssl/installation --with-wolfssl=/path/to
/wolfssl/installation
make
make check

make check may fail if the OpenSSL or wolfSSL libraries aren't found. In this case, try export LD_LIBRARY_PATH=/path/to/openssl/installation/lib:/path/to/ wolfssl/installation/lib:$LD_LIBRARY_PATH and re-run make check.

Customizing

To build wolfEngine in single-threaded mode, add --enable-singlethreaded to the configure command.
To build wolfEngine with PBES support (used with PKCS #12), add --enable-pbe. Note: wolfSSL must have been configured with --enable-pwdbased.
To disable support for loading wolfEngine dynamically, add --disable-dynamic-engine.
To build a static version of wolfEngine, add --enable-static.
To use a custom user_settings.h file to override the defines produced by ./configure, add --enable-usersettings and place a user_settings.h file with the defines you want in the include directory. See the root of the project for an example user_settings.h.
To build wolfEngine with debug support, add --enable-debug. Then, to activate the debug logging at runtime, your application should send this control command to wolfEngine (denoted "e" here): ENGINE_ctrl_cmd(e, "enable_debug", 1, NULL, NULL, 0).
To build wolfEngine for use with OpenSSH, add --enable-openssh.

Testing on *nix

Unit Tests

Run the unit tests with 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 earlier.

Integration Tests

See the scripts directory for integration tests with other applications (e.g. OpenSSH, stunnel, etc.).

Commit Tests

For wolfEngine developers running commit tests, a custom OpenSSL installation location can be set using the WOLFENGINE_OPENSSL_INSTALL environment variable. When set, wolfEngine commit tests will use the specified OpenSSL installation path for commit tests, setting the path using --with-openssl=WOLFENGINE_OPENSSL_INSTALL at configure time.

Windows

Refer to windows/README.md for instructions for building wolfEngine using Visual Studio.

Examples

Example programs using wolfEngine can be found in the examples/ subdirectory.

Need Help?

Please reach out to support@wolfssl.com for technical support. If you're interested in commercial licensing, FIPS operating environment additions, consulting services, or other business engagements, please reach out to facts@wolfssl.com.