Skip to content

Requirements

Java / JDK

wolfJCE requires Java to be installed on the host system. There are several JDK variants available to users and developers - including the Oracle JDK and OpenJDK. wolfJCE has currently been tested with OpenJDK, Oracle JDK, Amazon Coretto, Zulu, Temurin, Microsoft JDK, and Android. Some JDK implementations such as OpenJDK and Android do not require JCE providers to be code signed, whereas the Oracle JDK does. For details on code signing, please see Chapter 7

JUnit

JUnit is required to be installed on the development system in order to run unit tests. JUnit4 can be downloaded from the project website at www.junit.org.

To install JUnit4 on a Unix/Linux/OSX system:

1) Download " junit-4.13.2.jar " and " hamcrest-all-1.3.jar "from junit.org/junit4/. At the time of writing, the mentioned .jar files could be downloaded from the following links:

Junit: junit-4.13.2.jar

Hamcrest: hamcrest-all-1.3.jar

2) Place these JAR files on your system and set JUNIT_HOME to point to the directory location they are at. For example:

$ export JUNIT_HOME=/path/to/jar/files

make and ant

“make” and “ant” are used to compile native C code and Java code, respectively. Please ensure that these are installed on your development machine.

wolfSSL / wolfCrypt Library

As a wrapper around the native wolfCrypt library, wolfSSL must be installed and placed on the include and library search paths. wolfJCE can be compiled against either the FIPS 140-2/3 or non-FIPS version of the wolfSSL/wolfCrypt native library.

Compiling wolfSSL/wolfCrypt

To compile and install native wolfSSL in a Unix/Linux environment, please follow build instructions in the wolfSSL Manual. The most common way to compile wolfSSL is with the Autoconf system using configure.

You can build and install a wolfSSL (wolfssl-x.x.x), wolfSSL FIPS release (wolfssl-x.x.x-commercial-fips), or wolfSSL FIPS Ready release. With any of these archives, you will need to use the --enable-jni ./configure option in addition to any other package-specific configure option requirements (ex: --enable-fips).

The --enable-jni option includes all native wolfSSL features needed by both wolfCrypt JNI/JCE (this package) as well as wolfSSL JNI/JSSE (a separate package). If you want the minimal set of requirements needed for only wolfJCE, you can instead use --enable-keygen --enable-crl, where CRL support is needed for the JCE CertPathValidator (PKIX) CRL support.

Native Feature Requirements for Optional Algorithms

Several algorithms supported by wolfJCE depend on native wolfSSL features that are not always enabled by --enable-jni alone, and may require additional native wolfSSL configure options. The Notes column lists which ones are enabled by default. If the matching native feature is not compiled into wolfSSL, wolfJCE will still compile and run normally, but the corresponding services will not be registered by the provider.

Algorithm Native wolfSSL configure option Notes
ML-KEM (FIPS 203) --enable-mlkem The javax.crypto.KEM service additionally requires running on JDK 21 or later
ML-DSA (FIPS 204) --enable-mldsa The older --enable-dilithium is an accepted alias
SLH-DSA (FIPS 205) --enable-slhdsa --enable-slhdsa builds the six SHAKE parameter sets. Use --enable-slhdsa=yes,sha2 to build all twelve (recommended, since the SLH-DSA-SHA2-128f default lives in the SHA2 family)
XMSS / XMSS^MT (RFC 8391) --enable-xmss Requires wolfSSL 5.9.2 or later. SHAKE-based parameter sets additionally require --enable-sha3. Verify-only in wolfJCE
LMS / HSS (RFC 8554) --enable-lms --enable-lms=verify-only is also sufficient. SHAKE256 parameter sets additionally require --enable-sha3. Verify-only in wolfJCE
Ed25519 / Ed448 (RFC 8032) --enable-ed25519, --enable-ed448 --enable-ed448 also enables SHAKE256. Both are included in --enable-all
AES Key Wrap (RFC 3394) --enable-aeskeywrap Also enabled by --enable-all and --enable-pkcs7. Enabled by default in FIPS v6, v7, and FIPS Ready builds
AES-XTS --enable-aesxts Also enabled by --enable-all
AES-CFB --enable-aescfb Also enabled by --enable-all
SHAKE128 / SHAKE256 --enable-shake128, --enable-shake256 Enabled by default when SHA-3 is enabled (default on x86_64 and aarch64) for non-FIPS and FIPS v6+ builds
DH --enable-dh or --enable-dh=conditional Enabled by default, except in FIPS v7 and FIPS Ready builds starting with wolfSSL 5.9.4. See DH in FIPS v7 and FIPS Ready Builds

Note that the post-quantum and hash-based algorithms above (ML-KEM, ML-DSA, SLH-DSA, XMSS, LMS) are not enabled by --enable-all or --enable-all-crypto. On wolfSSL versions newer than 5.9.2, all five of these algorithm families can be enabled at once with --enable-all-quantum-crypto, which enables ML-KEM, ML-DSA, XMSS, LMS, and all twelve SLH-DSA parameter sets (yes,sha2).

The raw RSA RSA/ECB/NoPadding Cipher is only registered when native wolfSSL has raw RSA support compiled in (WC_RSA_NO_PADDING or WC_RSA_DIRECT). --enable-jni defines WC_RSA_NO_PADDING, so no additional options are needed with it. The minimal --enable-keygen --enable-crl build does not define either one, so add it to that configure line if RSA/ECB/NoPadding is needed:

$ ./configure --enable-keygen --enable-crl CPPFLAGS="-DWC_RSA_NO_PADDING"

XMSS/XMSS^MT and LMS/HSS support in wolfJCE is signature verification and public-key handling only. Key generation and signing are not supported, since stateful hash-based signing belongs in hardware (NIST SP 800-208).

wolfSSL Standard Build:

$ cd wolfssl-x.x.x
$ ./configure --enable-jni
$ make check
$ sudo make install

wolfSSL FIPSv2 Build (FIPS 140-2, Certificate #3389):

$ cd wolfssl-x.x.x-commercial-fips
$ ./configure --enable-fips=v2 --enable-jni
$ make check
$ sudo make install

wolfSSL FIPSv5 Build (FIPS 140-3, Certificate #4718):

$ cd wolfssl-x.x.x-commercial-fips
$ ./configure --enable-fips=v5 --enable-jni
$ make check
$ sudo make install

wolfSSL FIPS Ready Build:

$ cd wolfssl-x.x.x-commercial-fips
$ ./configure --enable-fips=ready --enable-jni
$ make check
$ sudo make install

This will install the wolfSSL library to your system default installation location. On many platforms this is:

/usr/local/lib
/usr/local/include

DH in FIPS v7 and FIPS Ready Builds

wolfCrypt FIPS v7 places DH outside the FIPS module boundary. Starting with wolfSSL 5.9.4, FIPS v7 and FIPS Ready builds leave DH out by default. Add --enable-dh=conditional to compile DH in but keep it disabled at runtime until the application calls Dh.enable(), or use --enable-dh to enable it at compile time. When DH is disabled, FeatureDetect.DhEnabled() returns false and wolfJCE does not register DH services.

wolfJCE decides which services to register when the provider is created, so call Dh.enable() before creating or installing the wolfJCE provider. If the provider was created before DH was enabled (for example, when wolfJCE is registered in java.security), refresh its services after calling Dh.enable():

Dh.enable();
WolfCryptProvider prov = (WolfCryptProvider)Security.getProvider("wolfJCE");
prov.refreshServices();