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 fips=v2 automatically. Replace this will --enable-engine=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

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.).

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.