wolfCrypt JNI/JCE manual: sync content with current wolfcrypt-jni, fix table rendering

common/table-code.css

@@ -0,0 +1,20 @@
+/* Keep inline code spans (configure options, property names, etc.) on a
+ * single line inside tables. The code column then sizes to its content and
+ * prose columns absorb the wrapping instead. Opt in per manual via the
+ * extra_css list in its mkdocs.yml. */
+/* display: inline-block is required for WebKit (Safari): it otherwise sizes
+ * table columns using the hyphen break opportunities inside code spans, then
+ * line-breaks the span (e.g. --enable-slhdsa) even under white-space: nowrap.
+ * As an inline-block atom the span's full width feeds into column sizing.
+ * The word-break/hyphens resets guard the wrapped-prose case (Notes columns),
+ * where WebKit can still honor the theme's `code { word-break: break-word }`
+ * break opportunities inside a nowrap inline element. */
+.md-typeset table:not([class]) th code,
+.md-typeset table:not([class]) td code {
+    display: inline-block;
+    white-space: nowrap;
+    word-break: normal;
+    overflow-wrap: normal;
+    -webkit-hyphens: none;
+    hyphens: none;
+}

wolfCrypt-JNI/mkdocs.yml

@@ -2,7 +2,7 @@ site_name: wolfCrypt JCE Provider and JNI Manual
 site_url: https://wolfssl.com/
 docs_dir: build/html/
 site_dir: html/
-copyright: wolfSSL Inc. 2024
+copyright: wolfSSL Inc. 2026
 nav:
     - "1. Introduction": index.md
     - "2. Requirements": chapter02.md
@@ -28,7 +28,7 @@ theme:
   favicon: logo.png
   feature:
     tabs: true
-extra_css: [skin.css]
+extra_css: [skin.css, table-code.css]
 extra:
     generator: false
 use_directory_urls: false

wolfCrypt-JNI/src/chapter02.md

@@ -28,12 +28,34 @@ $ export JUNIT_HOME=/path/to/jar/files
 
 As a wrapper around the native wolfCrypt library, [wolfSSL](https://www.wolfssl.com/products/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 
+###  Compiling wolfSSL/wolfCrypt
 
 To compile and install native wolfSSL in a Unix/Linux environment, please follow build instructions in the [wolfSSL Manual](https://www.wolfssl.com/documentation/manuals/wolfssl/index.html). 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 Post-Quantum and Hash-Based Algorithms
+
+Several algorithms supported by wolfJCE are **not** enabled by `--enable-jni` alone and require additional native wolfSSL configure options. 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 |
+
+Note that these algorithms are **not** enabled by `--enable-all` or
+`--enable-all-crypto`. On wolfSSL versions newer than 5.9.2, all five algorithm
+families in the table above 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`).
+
+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

wolfCrypt-JNI/src/chapter03.md

@@ -2,7 +2,7 @@
 
 Before following steps in this section, please ensure that the dependencies in [Chapter 2](chapter02.md#requirements) 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:
+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
@@ -87,16 +87,52 @@ 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:
+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.9.0-SNAPSHOT</version>
+    <version>1.10.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.
+
 ## API Javadocs
 
 Running `ant` will generate a set of Javadocs under the `wolfcrypt-jni/docs/javadoc`

wolfCrypt-JNI/src/chapter04.md

@@ -7,7 +7,7 @@ applications to use.
 ##  Installation at Runtime
 
 To install and use wolfJCE at runtime inside a single application, first make
-sure that "**libwolfcryptjni.so**" (or "**libwolfcryptjni.dylib**" if on MacOS)
+sure that "**libwolfcryptjni.so**" (or "**libwolfcryptjni.dylib**" if on macOS)
 is on your system library search path.
 
 On Linux, you can modify this path with:
@@ -16,7 +16,7 @@ On Linux, you can modify this path with:
 $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/add
 ```
 
-On MacOS, you can use `DYLD_LIBRARY_PATH` instead:
+On macOS, you can use `DYLD_LIBRARY_PATH` instead:
 
 ```
 $ export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/path/to/add
@@ -58,6 +58,13 @@ for (Provider prov:providers) {
 }
 ```
 
+wolfJCE also registers itself as a `java.security.Provider` service
+(`META-INF/services/java.security.Provider`), which allows the provider to be
+discovered through the Java `ServiceLoader` mechanism and used with the Java
+Platform Module System (JPMS). See
+[Chapter 3](chapter03.md#java-9-module-support-jpms) for more details on module
+support.
+
 ##  Installation at OS / System Level (Java <= 8)
 
 wolfJCE can be installed at the system level so that any Java application
@@ -66,7 +73,7 @@ consuming Java Security APIs for cryptography can leverage wolfJCE.
 To install the wolfJCE provider at the system level, copy the JAR into the
 correct Java installation directory for your OS and JDK and verify the shared
 library is on your library search path.
-    
+
 Add the wolfCrypt JNI/JCE JAR file (**wolfcrypt-jni.jar**) and shared library
 (**libwolfcryptjni.so** or **libwolfcryptjni.dylib**) to the following
 directory:
@@ -97,3 +104,53 @@ $JAVA_HOME/jre/lib/security/java.security
 Replacing “N” with the order of precedence you would like the WolfCryptProvider
 to have in comparison to other providers in the file.
 
+##  Installation at OS / System Level (Java > 8)
+
+Note that the `$JAVA_HOME/jre/lib/ext` extension mechanism was removed in
+Java 9. On Java 9 and later, place `wolfcrypt-jni.jar` on the application
+classpath (or module path) instead, and add the
+`security.provider.N=com.wolfssl.provider.jce.WolfCryptProvider` entry to the
+`java.security` file located at `$JAVA_HOME/conf/security/java.security`.
+
+## Custom Native Library Loading
+
+By default, wolfCrypt JNI/JCE loads the native `wolfcryptjni` library using
+`System.loadLibrary()`. This requires the native library to be located on
+the system library search path.
+
+For applications that need custom library loading behavior, such as bundling
+native libraries inside a JAR file and extracting them at runtime, wolfCrypt
+JNI/JCE supports skipping the automatic library loading via the
+`wolfssl.skipLibraryLoad` System property. When set to `true`, wolfCrypt
+JNI/JCE will skip calling `System.loadLibrary()` for the native libraries,
+and the application is then responsible for loading the native libraries
+before any wolfCrypt classes are accessed.
+
+This property must be set before any wolfCrypt JNI/JCE classes are loaded by
+the JVM, as the native library loading occurs in static initializer blocks:
+
+```
+/* Option 1: Set via command line */
+/* java -Dwolfssl.skipLibraryLoad=true -jar myapp.jar */
+
+/* Option 2: Load libraries manually with absolute paths, then set property.
+ * This must happen at application startup, BEFORE any wolfCrypt classes
+ * are accessed or loaded by the JVM. */
+System.load("/path/to/libwolfssl.so");
+System.load("/path/to/libwolfcryptjni.so");
+System.setProperty("wolfssl.skipLibraryLoad", "true");
+
+/* Now wolfCrypt classes can be used normally */
+```
+
+Applications can check if library loading was skipped using the
+`WolfObject.isLibraryLoadSkipped()` method:
+
+```
+import com.wolfssl.wolfcrypt.WolfObject;
+
+if (WolfObject.isLibraryLoadSkipped()) {
+    System.out.println("Native library loading was skipped");
+}
+```
+

wolfCrypt-JNI/src/chapter05.md

@@ -10,20 +10,24 @@ version of “wolfcrypt-jni.jar” that does not include the JCE provider classe
 **wolfJCE / wolfCrypt JNI package structure:**
 
 ```
-wolfcrypt-jni /
+wolfcrypt-jni/
     .github                        GitHub Actions workflows
     AUTHORS
     COPYING
     ChangeLog.md                   Version ChangeLog
     IDE/                           IDE Project Files
+        Android/                   Example Android Studio project
         WIN/                       Visual Studio Project Files
     LICENSING
     README.md                      Main README
     README_JCE.md                  wolfJCE README
     build.xml                      ant build script
-    docs /                         Javadocs
+    docs/                          Javadocs and design documents
+        design/                    Design documents (WKS KeyStore, etc)
+        javadoc/                   Generated Javadocs
     examples/                      Example applications and certs/keys
         certs/                     Example cert/keys/KeyStores
+        filtered-providers/        Filtered Sun provider examples (FIPS)
         provider/                  JCE example apps
     jni/                           Native C JNI binding source files
     lib/                           Compiled library artifacts
@@ -33,14 +37,16 @@ wolfcrypt-jni /
     rpm/                           Linux rpm files
     scripts/                       Test scripts (Facebook Infer, etc)
     src/                           Source code
+        java9/                     module-info.java (Java 9+ JPMS support)
         main/java                  Java source files
+        test/java                  JUnit test source files
 
 ```
 
 The wolfJCE provider source code is located in the
 `src/main/java/com/wolfssl/provider/jce` directory, and is part of the
 “**com.wolfssl.provider.jce**” Java package.
- 
+
 The wolfCrypt JNI wrapper is located in the
 `src/main/java/com/wolfssl/wolfcrypt` directory and is part of the
 “**com.wolfssl.wolfcrypt**” Java package. Users of JCE will not need to use