From 5bfb136511a7370a5bb1ef0ed11bc94b2f939795 Mon Sep 17 00:00:00 2001 From: Chris Conlon Date: Wed, 11 Oct 2023 15:49:16 -0600 Subject: [PATCH] JNI/JCE: update Maven build pom.xml, add instructions to README.md --- .gitignore | 4 ++ README.md | 119 +++++++++++++++++++++++++++++++++++++++++++++++++---- pom.xml | 23 +++++++++-- 3 files changed, 134 insertions(+), 12 deletions(-) diff --git a/.gitignore b/.gitignore index 96ad99d..cb6c7b5 100644 --- a/.gitignore +++ b/.gitignore @@ -24,3 +24,7 @@ IDE/WIN/DLL Debug IDE/WIN/DLL Debug FIPS IDE/WIN/DLL Release IDE/WIN/DLL Release FIPS + +# Maven output directory +target/ + diff --git a/README.md b/README.md index de56372..ef153c4 100644 --- a/README.md +++ b/README.md @@ -11,12 +11,13 @@ or the wolfSSL online documentation. For instructions and notes on the JCE provider, please reference the [README_JCE.md](./README_JCE.md) file, or online instructions. -### Compiling +### Compiling Native wolfSSL (Dependency) --------- -To compile the wolfCrypt JNI wrapper: +To compile the wolfCrypt JNI wrapper and JCE provider, first the native (C) +wolfSSL library must be compiled and installed. -1) Compile and install a wolfSSL (wolfssl-x.x.x), wolfSSL FIPS +Compile and install a wolfSSL (wolfssl-x.x.x), wolfSSL FIPS release (wolfssl-x.x.x-commercial-fips), or wolfSSL FIPS Ready release: In any of these cases, you will need the `--enable-keygen` ./configure option. @@ -56,23 +57,32 @@ $ make check $ sudo make install ``` -2) Compile the native wolfCrypt JNI object files. Two makefiles are distributed -for Linux (`makefile.linux`) and Mac OSX (`makefile.macosx`). First copy -the makefile for your platform to a file called `makefile`: +### Compiling wolfSSL JNI/JCE with ant +--------- + +wolfCrypt JNI/JCE'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. Continue reading here for instructions to build with +ant. + +1) Compile the native wolfCrypt JNI object files. Two makefiles are distributed, +one for Linux (`makefile.linux`) and one for Mac OSX (`makefile.macosx`). First +copy the makefile for your platform to a file called `makefile`: ``` $ cd wolfcrypt-jni $ cp makefile.linux makefile ``` -Then compile the native wolfCrypt JNI object files: +Then compile the native wolfCrypt JNI object files into a native C shared +library: ``` $ cd wolfcrypt-jni $ make ``` -3) Compile the wolfCrypt JNI Java sources files, from the wolfcrypt-jni +2) Compile the wolfCrypt JNI/JCE Java sources files, from the wolfcrypt-jni directory: ``` @@ -111,7 +121,7 @@ $ ant clean $ make clean ``` -### API Javadocs +#### API Javadocs --------- Running `ant` will generate a set of Javadocs under the `wolfcrypt-jni/docs` @@ -119,6 +129,97 @@ directory. To view the root document, open the following file in a web browser: `wolfcrypt-jni/docs/index.html` +### Compiling wolfSSL JNI/JCE with Maven +--------- + +wolfSSL JNI/JCE supports building and packaging with Maven, for those projects +that are already set up to use and consume Maven packages. + +wolfSSL JNI/JCE's Maven build configuration is defined in the included +`pom.xml` file. + +First, compile the native JNI shared library (libwolfcryptjni.so/dylib) same +as above. This will create the native JNI shared library under the `./lib` +directory: + +``` +$ cd wolfcrypt-jni +$ cp makefile.linux makefile +$ make +``` + +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 wolfCrypt JNI/JCE 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/wolfcrypt-jni-X.X.X-SNAPSHOT.jar`: + +``` +$ mvn package +``` + +To build the Javadoc API reference for wolfCrypt JNI/JCE run the following. This +will generate Javadoc HTML under the `./docs/apidocs` directory: + +``` +$ mvn javadoc:javadoc +``` + +To install the wolfSSL JNI/JCE 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/wolfcrypt-jni/X.X.X-SNAPSHOT/wolfcrypt-jni-X.X.X-SNAPSHOT.jar +``` + +The wolfCrypt JNI shared library (`libwolfcryptjni.so/dylib`) created with +`make` 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 `./libs` 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/wolfcryptjni/lib +``` + +After wolfCrypt JNI/JCE 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 (where the version number will change depending +on the current release): + +``` + + ... + + + com.wolfssl + wolfcrypt-jni + 1.5.0-SNAPSHOT + + + ... + +``` + + ### Example / Test Code --------- diff --git a/pom.xml b/pom.xml index 3d99be8..acf13a2 100644 --- a/pom.xml +++ b/pom.xml @@ -2,17 +2,22 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> 4.0.0 - wolfssl + com.wolfssl wolfcrypt-jni - 1.0.0-SNAPSHOT + 1.5.0-SNAPSHOT jar wolfcrypt-jni + https://www.wolfssl.com + + + UTF-8 + org.hamcrest - hamcrest-core + hamcrest-all 1.3 test @@ -27,7 +32,9 @@ + org.apache.maven.plugins maven-compiler-plugin + 3.11.0 1.8 1.8 @@ -36,10 +43,20 @@ org.apache.maven.plugins maven-surefire-plugin + 3.1.2 -Djava.library.path=./lib:/usr/lib/jni + + org.apache.maven.plugins + maven-javadoc-plugin + 3.6.0 + + ./docs + ./docs + +