wolfSSL JSSE Provider and JNI Wrapper

This package provides Java support for the wolfSSL embedded SSL/TLS library, giving applications support for SSL/TLS up to the current TLS 1.3 protocol level. It contains both a wolfSSL JSSE (Java Secure Socket Extension) provider, called wolfJSSE, and a thin JNI-based interface that wraps the native C library.

wolfSSL also provides a JCE (Java Cryptography Extension) provider that wraps native wolfCrypt. This can be found in a separate repository, located here.

Why use wolfJSSE?

This interface gives Java applications access to all the benefits of using wolfSSL, including current SSL/TLS standards up to TLS 1.3, FIPS 140-2 and 140-3 support, performance optimizations, hardware cryptography support, commercial support, and more!

User Manual

The wolfSSL JNI/JSSE Manual is available on the wolfSSL website: wolfSSL JNI Manual.

For additional build instructions and more detailed comments, please reference the manual.

Building

wolfJSSE currently supports compilation on the following platforms:

Linux/Unix
Mac OSX
Windows (Visual Studio)
Android Studio
Android AOSP

To build wolfJSSE on Windows using Visual Studio, please reference the Windows README.md.

Building Native wolfSSL (Dependency)

To compile the wolfSSL JNI wrapper and JSSE provider, first the native (C) wolfSSL library must be compiled and installed.

To build wolfJSSE in Linux/Unix environments, first download, compile, and install wolfSSL. wolfSSL can be downloaded from the wolfSSL download page or cloned from GitHub.

$ unzip wolfssl-X.X.X.zip
$ cd wolfssl-X.X.X
$ ./configure --enable-jni
$ make check
$ sudo make install

If building a wolfSSL FIPS or FIPS Ready release bundle, additional configure options may be required. Reference the wolfSSL Manual and build documentation for exact build instructions.

Building and testing with make/ant

wolfSSL JNI/JSSE's ant build is the most stable and well-tested. Newer support for building with Maven has also been added. See section below for instructions on building with Maven.

The Makefile compiles the native JNI shared library (libwolfssljni.so/libwolfssljni.dylib) and invokes ant to build the Java sources. It will auto-detect JAVA_HOME if not already set. To explicitly specify a Java installation, set JAVA_HOME before running make.

Make targets:

make / make build - Compiles the native JNI library and Java sources (JAR)
make check - Builds and runs JUnit tests (requires JUNIT_HOME)
make native - Compiles only the native JNI shared library
make clean - Cleans all Java and native artifacts
make clean-native - Cleans only native artifacts (.o, .d, shared lib)
make install - Installs shared library and JARs
make uninstall - Removes installed files

Ant-only targets are also available:

ant build (ant) - Only builds the JAR
ant test - Builds and runs tests (requires JUNIT setup)
ant examples - Builds examples
ant clean - Cleans Java artifacts
ant cleanjni - Cleans native artifacts

To build wolfJSSE:

$ cd wolfssljni
$ export JUNIT_HOME=/path/to/junit/jars
$ make build
$ make check

Custom wolfSSL installation directories and library names can be passed to make:

$ make WOLFSSL_INSTALL_DIR=/path/to/wolfssl WOLFSSL_LIBNAME=wolfssljsse

Set V=1 to see the full compiler commands:

$ make V=1

Set ENABLE_PATCHES=1 to automatically detect and enable JNI code that depends on wolfSSL pull request patches (WOLFSSL_PR*_PATCH_APPLIED defines). This enables functionality and test coverage for features added since the last official wolfSSL build.

Note: this requires a recent build of wolfSSL with the PR included, often newer than the latest tagged release.

$ make ENABLE_PATCHES=1

To compile and run the examples, use the ant examples target:

$ ant examples

Then, run the examples from the root directory using the provided wrapper scripts:

$ ./examples/provider/ServerJSSE.sh
$ ./examples/provider/ClientJSSE.sh

java.sh Script

The java.sh script is a convenience wrapper around the Makefile that compiles the native JNI sources into a shared library named either libwolfssljni.so (Linux/Unix) or libwolfssljni.dylib (MacOS). It invokes make clean-native followed by make native, performing a clean rebuild of the native library each time.

The script accepts two optional arguments:

wolfSSL installation directory (default: /usr/local) - should match the directory set at wolfSSL ./configure --prefix=<DIR>.
wolfSSL library name (default: wolfssl) - useful if a non-standard library name has been used, for example via ./configure --with-libsuffix.

For example, if wolfSSL was configured with --with-libsuffix=jsse, then this script could be called like so using the default installation path of /usr/local:

java.sh /usr/local wolfssljsse

CFLAGS can be set in the environment prior to running the script:

CFLAGS=-DWOLFJNI_USE_IO_SELECT java.sh

Building with Maven

wolfJSSE supports building and packaging with Maven, for those projects that are already set up to use and consume Maven packages.

wolfJSSE's Maven build configuration is defined in the included pom.xml.

First, compile the native JNI shared library (libwolfssljni.so/dylib). This will create the native JNI shared library under the ./lib directory:

$ make native

Compile the Java sources, where Maven will place the compiled .class files under the ./target/classes directory:

$ mvn compile

Compile and run JUnit tests using:

$ mvn test

Package up the wolfSSL JNI/JSSE JAR file using the following command. This will run the JUnit tests then create a .jar file located under the ./target directory, similar to target/wolfssl-jsse-X.X.X-SNAPSHOT.jar:

$ mvn package

To build the Javadoc API reference for wolfSSL JNI/JSSE run the following. This will generate Javadoc HTML under the ./docs/apidocs directory:

$ mvn javadoc:javadoc

To install the wolfSSL JNI/JSSE JAR file, run the following. This will install the JAR into the local Maven repository:

$ mvn install

The local Maven repository installation location will be similar to:

~/.m2/repository/com/wolfssl/wolfssl-jsse/X.X.X-SNAPSHOT/wolfssl-jsse-X.X.X-SNAPSHOT.jar

The wolfSSL JNI shared library (libwolfssljni.so/dylib) will need to be "installed" by being placed on your native library search path. For example, copied into /usr/local/lib, /usr/lib, or other location. Alternatively, append the ./lib directory to your native library search path by exporting LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (OSX):

$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/wolfssljni/lib

After wolfSSL JNI/JSSE has been installed into the local Maven repository, an application can include this as a dependency in the application's pom.xml file, similar to:

<project ...>
    ...
    <dependencies>
        <dependency>
            <groupId>com.wolfssl</groupId>
            <artifactId>wolfssl-jsse</artifactId>
            <version>1.16.0-SNAPSHOT</version>
        </dependency>
    </dependencies>
    ...
</project>

Java 9+ Module Support (JPMS)

wolfSSL JNI/JSSE supports the Java Platform Module System (JPMS) introduced in Java 9. This allows the library to be used with jlink to create custom Java runtimes.

How It Works

The build system uses conditional compilation to include module support only when building with Java 9 or later:

| JDK Used to Build | Resulting JAR | | --- | --- | | Java 8 | Standard JAR (classpath only) | | Java 9+ | Modular JAR (works with both classpath and module path) |

When building with Java 9+, a module-info.class is included in the JAR that:

Declares the module as com.wolfssl
Exports com.wolfssl and com.wolfssl.provider.jsse packages
Registers WolfSSLProvider as a java.security.Provider service

Building a Modular JAR

To build a modular JAR, simply use Java 9 or later when building. Both Ant and Maven builds support automatic module-info compilation.

Using Ant:

$ export JAVA_HOME=/path/to/jdk11   # or any JDK 9+
$ make build

Using Maven:

$ export JAVA_HOME=/path/to/jdk11   # or any JDK 9+
$ make native
$ mvn package

Maven uses a profile (java9-module) that automatically activates on Java 9+ to compile and include module-info.class in the JAR.

You can verify module support with:

$ jar --describe-module --file=lib/wolfssl-jsse.jar
com.wolfssl jar:file:///path/to/lib/wolfssl-jsse.jar/!module-info.class
exports com.wolfssl
exports com.wolfssl.provider.jsse
requires java.logging
provides java.security.Provider with com.wolfssl.provider.jsse.WolfSSLProvider

Using with jlink

Once built with Java 9+, the JAR can be used with jlink to create custom Java runtimes:

$ jlink \
    --module-path lib/wolfssl-jsse.jar \
    --add-modules com.wolfssl \
    --output custom-runtime \
    --no-header-files \
    --no-man-pages

This creates a minimal Java runtime with wolfJSSE included, which can be deployed independently.

Java 8 Compatibility

Java 8 users can still build and use wolfSSL JNI/JSSE normally. When building with Java 8, the module-info.java is automatically excluded from compilation, and the resultin

Wolfssljni

Install / Use

README