/wolfEngine

wolfCrypt and wolfCrypt FIPS engine for OpenSSL

Primary LanguageCGNU General Public License v3.0GPL-3.0

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.