Merge pull request #245 from rlm2002/jniManUpdates

update wolfJSSE manual to reflect changes up to 1.16.0 release

Author: cconlon

wolfSSL-JNI/src/chapter01.md

@@ -4,6 +4,6 @@ wolfSSL JNI/JSSE is a provider implementation of the Java Secure Socket Extensio
 
 The Java Secure Socket Extension ( **JSSE** ) framework supports the installation of security providers. These providers can implement a subset of the functionality used by the Java JSSE security APIs, including SSL/TLS.
 
-This document describes wolfSSL’s JSSE provider implementation, named “**wolfJSSE / wolfSSLProvider**”. wolfJSSE wraps the native wolfSSL SSL/TLS library. This interface gives Java applications access to all the benefits of using wolfSSL, including current SSL/TLS standards up to [TLS 1.3](https://www.wolfssl.com/tls13), [FIPS 140-2 and 140-3](https://www.wolfssl.com/license/fips/) support, performance optimizations, hardware cryptography support, [commercial support](https://www.wolfssl.com/products/support-and-maintenance/), and more!
+This document describes wolfSSL’s JSSE provider implementation, named “**wolfJSSE / wolfSSLProvider**”. wolfJSSE wraps the native wolfSSL SSL/TLS library. This interface gives Java applications access to all the benefits of using wolfSSL, including current SSL/TLS standards up to [TLS 1.3](https://www.wolfssl.com/tls13), [DTLS 1.3](https://www.wolfssl.com/wolfssl-java-jsse-provider-supports-dtls-1-3/), and [FIPS 140-2 and 140-3](https://www.wolfssl.com/license/fips/) support, performance optimizations, hardware cryptography support, [commercial support](https://www.wolfssl.com/products/support-and-maintenance/), and more!
 
 wolfJSSE is distributed as part of the “ **wolfssljni** ”package.

wolfSSL-JNI/src/chapter02.md

@@ -10,7 +10,8 @@ on the following:
     + Oracle JDK
     + OpenJDK
     + Zulu JDK
-    + Amazon Coretto
+    + Amazon Corretto
+    + Eclipse Temurin
 - Mac OSX
 - Windows (Visual Studio)
 - Android Studio

wolfSSL-JNI/src/chapter03.md

@@ -34,6 +34,27 @@ location. For example:
 $ ./java.sh /path/to/wolfssl/install
 ```
 
+A second optional argument specifies a custom wolfSSL library name to link
+against. This is useful when wolfSSL was compiled with `--with-libsuffix`:
+
+```
+$ ./java.sh /usr/local wolfssljsse
+```
+
+The script will attempt to auto-detect `JAVA_HOME` if not set. To explicitly
+specify a Java installation, set the `JAVA_HOME` environment variable before
+running.
+
+Preset `CFLAGS` can be passed to the script via the environment:
+
+```
+$ CFLAGS="-DWOLFJNI_USE_IO_SELECT" ./java.sh
+```
+
+On Aarch64 hosts, `-fPIC` is automatically added to CFLAGS.
+
+## Building with ant
+
 To compile the Java sources, `ant` is used:
 
 ```
@@ -82,6 +103,73 @@ is used:
 $ ant examples
 ```
 
+## Building with Maven
+
+wolfJSSE supports building and packaging with Maven for projects that consume
+Maven packages.
+
+First, compile the native JNI shared library using `java.sh` as described above.
+This creates the native library under `./lib`:
+
+```
+$ ./java.sh
+```
+
+Compile the Java sources (output to `./target/classes`):
+
+```
+$ mvn compile
+```
+
+Compile and run JUnit tests:
+
+```
+$ mvn test
+```
+
+Package the JAR file (runs tests, then creates `target/wolfssl-jsse-X.X.X-SNAPSHOT.jar`):
+
+```
+$ mvn package
+```
+
+Generate Javadoc API documentation (output to `./docs/apidocs`):
+
+```
+$ mvn javadoc:javadoc
+```
+
+Install the JAR to the local Maven repository:
+
+```
+$ mvn install
+```
+
+The JAR will be installed to a location similar to:
+
+```
+~/.m2/repository/com/wolfssl/wolfssl-jsse/X.X.X-SNAPSHOT/wolfssl-jsse-X.X.X-SNAPSHOT.jar
+```
+
+The native `libwolfssljni.so` (or `.dylib`) library must be installed on the
+native library search path (e.g., `/usr/local/lib`) or the path can be set via
+`LD_LIBRARY_PATH` (Linux) or `DYLD_LIBRARY_PATH` (macOS).
+
+Applications can include wolfJSSE as a Maven dependency:
+
+```xml
+<dependency>
+    <groupId>com.wolfssl</groupId>
+    <artifactId>wolfssl-jsse</artifactId>
+    <version>1.16.0-SNAPSHOT</version>
+</dependency>
+```
+
+## Windows Visual Studio Build
+
+wolfJSSE can be compiled on Windows using Visual Studio. For detailed
+instructions, see the `IDE/WIN/README.md` file in the wolfssljni package.
+
 ## Android Studio Build
 
 An example Android Studio project is located in the directory `IDE/Android`.

wolfSSL-JNI/src/chapter04.md

@@ -48,6 +48,39 @@ for (Provider prov:providers) {
 }
 ```
 
+### Java Module System (JPMS) Support
+
+wolfJSSE includes Java ServiceLoader support for compatibility with the Java
+Module System (JPMS). This allows the wolfJSSE provider to be automatically
+discovered and loaded when the JAR is on the module path.
+
+The wolfJSSE JAR contains a `META-INF/services/java.security.Provider` file
+that registers `com.wolfssl.provider.jsse.WolfSSLProvider` for automatic
+discovery. Applications can discover and load the provider using the standard
+Java ServiceLoader API:
+
+```
+import java.security.Provider;
+import java.security.Security;
+import java.util.ServiceLoader;
+
+ServiceLoader<Provider> loader = ServiceLoader.load(Provider.class);
+for (Provider provider : loader) {
+    if (provider.getName().equals("wolfJSSE")) {
+        Security.addProvider(provider);
+        break;
+    }
+}
+```
+
+For modular applications, wolfJSSE can be used as an automatic module or
+included as a dependency in your `module-info.java`.
+
+**Note:** ServiceLoader-based provider discovery relies on the
+`META-INF/services` mechanism which is a JAR/module system feature. On Android,
+applications should register the provider directly using
+`Security.addProvider(new WolfSSLProvider())` instead.
+
 ##  Installation at OS / System Level
 
 ###  Unix/Linux

wolfSSL-JNI/src/chapter05.md

@@ -9,22 +9,25 @@ wolfJSSE / wolfSSL JNI package structure:
 
 ```
 wolfssljni/
-    build.xml  ant build script
+    build.xml       ant build script
+    pom.xml         Maven build configuration
     COPYING
-    docs/      Javadocs
-    examples/  Example apps
-    IDE/       Example IDE project, Android Studio
-    java.sh    Script to build native C JNI sources
+    docs/           Javadocs
+    examples/       Example apps
+    IDE/            IDE projects
+        Android/    Android Studio
+        WIN/        Windows Visual Studio
+    java.sh         Script to build native C JNI sources
     LICENSING
     Makefile
-    lib/       Output directory for compiled library
-    native/    Native C JNI binding source files
-    platform/  Android AOSP build files
+    lib/            Output directory for compiled library
+    native/         Native C JNI binding source files
+    platform/       Android AOSP build files
     README.md
-    rpm/       rpm spec files
+    rpm/            rpm spec files
     src/
-        java/  Java source files
-        test/  Test source files
+        java/       Java source files
+        test/       Test source files
 ```
 
 The **wolfJSSE** provider source code is located in the

wolfSSL-JNI/src/chapter06.md

@@ -3,7 +3,7 @@
 wolfJSSE extends or implements the following JSSE classes:
 
     javax.net.ssl.SSLContextSpi
-        SSL, TLS, DEFAULT, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3
+        SSL, TLS, DEFAULT, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3, DTLSv1.3
     javax.net.ssl.KeyManagerFactorySpi
         PKIX, X509, SunX509
     javax.net.ssl.TrustManagerFactorySpi
@@ -20,3 +20,16 @@ wolfJSSE extends or implements the following JSSE classes:
     java.security.cert.X509Certificate
     javax.security.cert.X509Certificate
 
+**Note:** `DTLSv1.3` is only supported through the `SSLEngine` interface.
+
+## Secure Renegotiation
+
+wolfJSSE supports secure renegotiation when the underlying native wolfSSL
+library has been compiled with secure renegotiation support:
+
+```
+$ ./configure --enable-secure-renegotiation
+```
+
+Or by defining `HAVE_SECURE_RENEGOTIATION`.
+