Skip to content

Compilation

Before following steps in this section, please ensure that the dependencies in Chapter 2 above are installed.

Before running make, copy the correct “makefile” for your system, depending if you are on Linux/Unix or macOS. For example, if you were on Linux:

$ cd wolfcrypt-jni
$ cp makefile.linux makefile

If you are instead on Mac OSX:

$ cd wolfcrypt-jni
$ cp makefile.macosx makefile

Then compile the native C JNI source code with “make”. This will generate the native JNI shared library (libwolfcryptjni.so/dylib).

$ cd wolfcrypt-jni
$ make

To compile the Java sources, “ant” is used. There are several ant targets to compile either the JNI or JCE (includes JNI) packages, in either debug or release mode. Running regular “ant” will give usage options:

$ ant
...
build:
[echo] wolfCrypt JNI and JCE
[echo] ----------------------------------------------------------------------------
[echo] USAGE:
[echo] Run one of the following targets with ant:
[echo] build-jni-debug | builds debug JAR with only wolfCrypt JNI classes
[echo] build-jni-release | builds release JAR with only wolfCrypt JNI classes
[echo] build-jce-debug | builds debug JAR with JNI and JCE classes
[echo] build-jce-release | builds release JAR with JNI and JCE classes
[echo] ----------------------------------------------------------------------------

Use the build target that matches your needs. For example, if you want to build the wolfJCE provider in release mode, run:

$ ant build-jce-release

To run the JUnit tests, run ant test. This will compile only the tests that match the build that was done (JNI vs. JCE) and run those tests.

$ ant test

To clean the both Java JAR and native library, run:

$ ant clean
$ make clean

Compiling with Maven

wolfCrypt JNI/JCE also supports building with Maven. First, compile the native JNI shared library using make as described above.

The included Maven Wrapper, ./mvnw (or mvnw.cmd on Windows), can be used in place of mvn in the commands below. It downloads the Maven release pinned in .mvn/wrapper/maven-wrapper.properties, verifies its SHA-256 checksum, and runs Maven with --strict-checksums so that a dependency or plugin download that fails its checksum stops the build.

Then compile the Java sources with Maven:

$ mvn compile

To compile and run JUnit tests:

$ mvn test

To package the JAR file:

$ mvn package

To install the JAR into the local Maven repository:

$ mvn install

After installation, the package can be included as a dependency in other Maven projects, where the version number will change depending on the current release:

<dependency>
    <groupId>com.wolfssl</groupId>
    <artifactId>wolfcrypt-jni</artifactId>
    <version>1.12.0-SNAPSHOT</version>
</dependency>

Java 9+ Module Support (JPMS)

wolfCrypt JNI/JCE supports the Java Platform Module System (JPMS) introduced in Java 9. This enables use with jlink for creating custom, minimal Java runtimes.

Module Information:

  • Module name: com.wolfssl.wolfcrypt
  • Exported packages: com.wolfssl.wolfcrypt, com.wolfssl.provider.jce
  • Service provider: java.security.Provider (WolfCryptProvider)

The module-info.java (located under src/java9) is conditionally compiled based on the JDK version used to build. When building with Java 9 or later, a modular JAR is produced that includes module-info.class. When building with Java 8, module-info.java is automatically excluded from compilation and the resulting JAR works as a standard classpath JAR.

When built with Java 9+, the wolfCrypt JNI/JCE JAR can be used with jlink to create a custom Java runtime that includes the wolfCrypt module:

$ jlink \
    --module-path lib/wolfcrypt-jni.jar:$JAVA_HOME/jmods \
    --add-modules com.wolfssl.wolfcrypt \
    --output custom-runtime \
    --no-header-files \
    --no-man-pages

$ ./custom-runtime/bin/java --list-modules

Note that the native wolfCrypt JNI shared library (libwolfcryptjni.so/dylib) must still be available on the native library search path at runtime.

JDK 15+ Multi-Release JAR (EdDSA)

When built with JDK 15 or later, wolfcrypt-jni.jar is a multi-release JAR (Multi-Release: true). Classes under src/java15 are compiled into the META-INF/versions/15 layer of the JAR, so that on JDK 15 and later wolfJCE EdDSA keys also implement the JDK java.security.interfaces.EdECPublicKey and EdECPrivateKey interfaces. This allows wolfJCE Ed25519 and Ed448 keys to be passed directly to other providers such as SunEC. JDK 8 through 14 and Android use the base classes. Both ant and Maven build this layer automatically when the build JDK is 15 or later.

Multi-release class selection is done by the JAR loader, so the JDK 15 classes are only used when wolfJCE is loaded from wolfcrypt-jni.jar. A class directory such as Maven's target/classes (used by mvn test) uses the base classes. Run mvn clean when switching between build JDKs below and above 15.

API Javadocs

Running ant will generate a set of Javadocs under the wolfcrypt-jni/docs/javadoc directory. To view the Javadoc index, open the following file in a web browser:

wolfcrypt-jni/docs/javadoc/index.html

When using Maven, Javadocs can be generated with:

$ mvn javadoc:javadoc

This will generate Javadoc HTML under the ./docs/apidocs directory.