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

TL;DR>

The quickest way to get up and running is to use the scripts/util-*.sh. There is a scripts/test-sanity.sh that will pull all the required dependencies, compile them as needed, and finally run a few tests to make sure things are working as they should. For a more detailed step-by-step instruction, continue reading.

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.

SBOM / EU CRA Compliance

wolfEngine generates a Software Bill of Materials (SBOM) in CycloneDX 1.6 and SPDX 2.3 formats to support compliance with the EU Cyber Resilience Act (CRA). The SBOM records the configured build options, hashes the built libwolfengine library artifact (shared or static; ELF, Mach-O, or PE), and lists both wolfSSL and OpenSSL as dependencies so vulnerability scanners can associate wolfSSL and OpenSSL advisories with a wolfEngine deployment. Output is reproducible: set SOURCE_DATE_EPOCH (or build from a git checkout, which uses the last commit time) and repeated runs are byte-identical.

make sbom

Requires python3 and pyspdxtools (pip install spdx-tools). The generator is vendored in tools/sbom/ from wolfssl-compliance-tooling (revision in tools/sbom/.wolfssl-compliance-tooling-rev), so no wolfSSL source tree is needed. Pass WOLFSSL_DIR=/path/to/wolfssl to read the wolfSSL dependency version from a source tree instead of pkg-config.

Output: wolfengine-<version>.cdx.json, wolfengine-<version>.spdx.json, wolfengine-<version>.spdx

Optional overrides:

• SBOM_LICENSE_OVERRIDE - SPDX expression to use instead of the licence parsed from COPYING (e.g. LicenseRef-wolfSSL-Commercial for commercial licensees). Defaults to GPL-3.0-or-later (the per-file header licence).
• SBOM_LICENSE_TEXT - path to the licence text for any LicenseRef-* used in SBOM_LICENSE_OVERRIDE (required by SPDX 2.3).
• SBOM_WOLFSSL_VERSION - version recorded for the wolfSSL dependency; auto-detected from WOLFSSL_DIR/wolfssl/version.h (or wolfSSL's pkg-config entry) when unset.
• SBOM_OPENSSL_VERSION - version recorded for the OpenSSL dependency; resolved via OpenSSL's pkg-config entry when unset.

make install-sbom    # installs to $(datadir)/doc/wolfengine/
make uninstall-sbom

For further CRA guidance see wolfssl/doc/CRA.md.

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.