Skip to content

Commit cfe4574

Browse files
dgarskedgarske
authored
Merge pull request #81 from cconlon/jni_doc_update
Fix up wolfSSL JNI/JSSE documentation and Markdown
2 parents a6ab749 + 2dd08e3 commit cfe4574

File tree

9 files changed

+431
-241
lines changed

9 files changed

+431
-241
lines changed

‎wolfSSL-JNI/mkdocs.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ site_name: wolfSSL JNI and wolfJSSE Manual
22
site_url: https://wolfssl.com/
33
docs_dir: build/html/
44
site_dir: html/
5-
copyright: wolfSSL Inc. 2021
5+
copyright: wolfSSL Inc. 2023
66
nav:
77
- "1. Introduction": index.md
88
- "2. Requirements": chapter02.md

‎wolfSSL-JNI/src/chapter01.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
# Introduction
22

3+
wolfSSL JNI/JSSE is a provider implementation of the Java Secure Socket Extension. It also includes a thin JNI wrapper around the native wolfSSL SSL/TLS library.
4+
35
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.
46

5-
This document describes wolfSSL’s JSSE provider implementation, named “ **wolfJSSE** ”. wolfJSSE wraps the native wolfSSL SSL/TLS library, providing Java users the opportunity to take advantage of wolfSSL’s progressive features, performance, and resource optimizations. 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!
7+
This document describes wolfSSL’s JSSE provider implementation, named “ **wolfJSSE** ”. 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!
68

79
wolfJSSE is distributed as part of the “ **wolfssljni** ”package. This package includes both a thin JNI wrapper for wolfSSL and the wolfJSSE provider.
8-

‎wolfSSL-JNI/src/chapter02.md‎

Lines changed: 38 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -2,62 +2,79 @@
22

33
## Java / JDK
44

5-
wolfJSSE requires Java to be installed on the host system. There are several JDK variants available to users and developers - including the Oracle JDK, OpenJDK, Zulu JDK, and Android.
5+
wolfJSSE requires Java to be installed on the host system. There are several
6+
JDK variants available to users and developers. wolfSSL JNI/JSSE has been tested
7+
on the following:
8+
9+
- Unix/Linux:
10+
+ Oracle JDK
11+
+ OpenJDK
12+
+ Zulu JDK
13+
+ Amazon Coretto
14+
- Android
15+
16+
The build system for wolfSSL JNI/JSSE has not been set up to run on Microsoft
17+
Windows yet. If this is something you are interested in, contact wolfSSL at
18+
[[email protected]](mailto:[email protected]). The example Android Studio
19+
project included, under `IDE/Android` has been tested on both Linux and Windows.
620

721
## JUnit
822

9-
In order to run the unit tests, JUnit is required to be installed on the development system. JUnit can be downloaded from the project website at [www.junit.org]().
23+
In order to run the unit tests, JUnit 4 is required to be installed on the
24+
development system. JUnit can be downloaded from the project website at
25+
[www.junit.org]().
1026

1127
To install JUnit on a Unix/Linux/OSX system:
1228

13-
1. Download “ **junit-4.13.jar** ” and “ **hamcrest-all-1.3.jar** ”from [junit.org/junit4/](). At the time of writing, the above mentioned .jar files could be downloaded from the following links:
29+
1) Download “ **junit-4.13.2.jar** ” and “ **hamcrest-all-1.3.jar** ”from [junit.org/junit4/](). At the time of writing, the above mentioned .jar files could be downloaded from the following links:
1430

15-
LINK: [junit-4.13.jar](https://search.maven.org/search?q=g:junit%20AND%20a:junit)
16-
LINK: [hamcrest-all-1.3.jar](https://search.maven.org/artifact/org.hamcrest/hamcrest-all/1.3/jar)
31+
[junit-4.13.jar](https://search.maven.org/search?q=g:junit%20AND%20a:junit) <br/>
32+
[hamcrest-all-1.3.jar](https://search.maven.org/artifact/org.hamcrest/hamcrest-all/1.3/jar)
1733

18-
2. Place these JAR files on your system and set **JUNIT_HOME** to point to that location. Ex:
34+
2) Place these JAR files on your system and set **JUNIT_HOME** to point to that location. Ex:
1935

2036
```
2137
$ export JUNIT_HOME=/path/to/jar/files
2238
```
23-
## gcc and ant
2439

25-
Both “ gcc ” and “ ant ” are used to compile native Ccode and Java code, respectively. Please ensure that these are installed on your development machine.
40+
## System Dependencies (gcc and ant)
2641

27-
**Note**: The java.sh script uses a common location for the Java install location. If your Java install location is different, this could lead to an error when running java.sh. In this case, you should modify java.sh to match your environment.
42+
**gcc** and **ant** are used to compile native C code and Java code, respectively. Please ensure that these are installed on your development machine.
2843

29-
Build targets for ant are :
30-
- ant build (only builds the jar necessary for an app to use)
31-
- ant test (builds the jar and tests then runs the tests, requires JUNIT setup)
32-
- ant examples (builds the jar and example cases)
33-
- ant clean (cleans all Java artifacts)
34-
- ant cleanjni (cleans native artifacts)
44+
**Note**: The `java.sh` script uses a common location for the Java install location. If your Java install location is different, this could lead to an error when running `java.sh`. In this case, you should modify `java.sh` to match your environment.
3545

36-
## wolfSSL Library
46+
## wolfSSL SSL/TLS Library
3747

38-
As a wrapper around the native wolfSSL library, the wolfSSL C library must be installed on the host platform and placed on the include and library search paths.
48+
As a wrapper around the native wolfSSL library, the [wolfSSL](https://www.wolfssl.com/products/wolfssl/) C library must be installed on the host platform and placed on the include and library search paths before compiling wolfSSL JNI/JSSE.
3949

4050
### Compiling wolfSSL and wolfCrypt C Library
4151

42-
To compile and install wolfSSL in a Unix/Linux environment for use with wolfJSSE, please follow build instructions in the wolfSSL Manual. The most common way to compile wolfSSL is with the Autoconf system.
52+
To compile and install wolfSSL in a Unix/Linux environment for use with wolfJSSE, please follow build instructions in the [wolfSSL Manual](https://www.wolfssl.com/documentation/wolfssl-manual/index.html). The most common way to compile wolfSSL is using Autoconf.
53+
54+
When using Autoconf to configure wolfSSL, the `--enable-jni` option will need to be used:
4355

44-
When using Autoconf to configure wolfSSL, the “ --enable-jni ”option will need to be used:
4556
```
4657
$ cd wolfssl-X.X.X
4758
$ ./configure --enable-jni
4859
$ make
4960
```
50-
Verify “ make check ” passes successfully, then install the library:
61+
62+
Verify `make check` passes successfully, then install the library:
63+
5164
```
5265
$ make check
5366
$ sudo make install
5467
```
68+
5569
This will install the wolfSSL library to your system default installation location. On many platforms this is:
70+
5671
```
5772
/usr/local/lib
5873
/usr/local/include
5974
```
60-
If wolfSSL has installed to a non-standard library installation location, you may need to update LD_LIBRARY_PATH (Unix/Linux) or DYLD_LIBRARY_PATH (OSX):
75+
76+
If wolfSSL has been installed to a non-standard library installation location, you may need to update `LD_LIBRARY_PATH` (Unix/Linux) or `DYLD_LIBRARY_PATH` (OSX):
77+
6178
```
6279
$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/wolfssl/install
6380
```

‎wolfSSL-JNI/src/chapter03.md‎

Lines changed: 166 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,65 @@
1-
# wolfSSL JNI and wolfJSSE Compilation
1+
# wolfSSL JNI and wolfJSSE Compilation
22

3-
There are three ways to compile wolfJSSE listed in this section, including using the Unix Command Line, Android Studio Build and Generic IDE Build.
3+
There are three ways to compile wolfJSSE listed in this chapter, including
4+
using the Unix Command Line, Android Studio Build and Generic IDE Build.
45

5-
## Unix Command Line
6+
## Unix Command Line
7+
8+
Before following steps in this section, please ensure that the dependencies
9+
listed in Chapter 2 are installed.
10+
11+
The `java.sh` script in the root package directory is used to compile the native
12+
JNI C source files into a shared library for either Unix/Linux or Mac OSX.
13+
This script tries to auto-detect between OSX (Darwin) and Linux to set up
14+
include paths and shared library extension type. This script directly calls gcc
15+
on the JNI C source files, producing `./lib/libwolfssljni.so` or
16+
`./lib/libwolfssljni.dylib`.
617

7-
Before following steps in this section, please ensure that the dependencies listed in Chapter 1 are installed. The “ java.sh ” script in the root package directory is used to compile the native JNI C source files into a shared library for either Unix/Linux or Mac. This script tries to auto-detect between OSX (Darwin) and Linux to set up include paths and shared library extension type. This script directly calls gcc on the JNI C source files, producing “./lib/libwolfssljni.so” or “./lib/libwolfssljni.dylib”
818
```
919
$ ./java.sh
1020
1121
Compiling Native JNI library:
12-
WOLFSSL_INSTALL_DIR = /usr/local
13-
Detected Linux host OS
14-
Generated ./lib/libwolfssljni.so
22+
WOLFSSL_INSTALL_DIR = /usr/local
23+
Detected Linux host OS
24+
Linux x86_64
25+
Java Home = /usr/lib/jvm/java-8-openjdk-amd64
26+
Generated ./lib/libwolfssljni.so
27+
```
28+
29+
If linking against a native wolfSSL library not installed to `/usr/local`, one
30+
argument may be passed to `java.sh` which represents the wolfSSL installation
31+
location. For example:
32+
33+
```
34+
$ ./java.sh /path/to/wolfssl/install
1535
```
16-
To compile the Java sources, “ ant ” is used:
36+
37+
To compile the Java sources, `ant` is used:
38+
1739
```
1840
$ ant
1941
```
20-
This will build the wolfJSSE jar and native code necessary to use wolfJSSE in a project. To compile and run tests the command “ ant test ”is used:
42+
43+
Available build targets for `ant` are :
44+
45+
- `ant` (only builds the jar necessary for an app to use)
46+
- `ant test` (builds the jar and tests then runs the tests, requires JUNIT setup)
47+
- `ant examples` (builds the jar and example cases)
48+
- `ant clean` (cleans all Java artifacts)
49+
- `ant cleanjni` (cleans native artifacts)
50+
51+
These two commands will build the wolfJSSE jar and native code necessary to use
52+
wolfJSSE in a project. To compile and run JUnit tests the command `ant test`
53+
is used:
54+
2155
```
2256
$ ant test
2357
```
24-
This will compile tests and the main wolfJSSE code and output with the results of the tests will be displayed along with a summary of total tests that passed at the end of the wolfJSSE testsuite and wolfSSL JNI testsuite. A successful build will display the message “BUILD SUCCESSFUL” at the end.
58+
59+
This will compile tests and the main wolfJSSE code and output with the results
60+
of the tests will be displayed along with a summary of total tests that passed
61+
at the end of the wolfJSSE testsuite and wolfSSL JNI testsuite. A successful
62+
build will display the message “BUILD SUCCESSFUL” at the end.
2563

2664
```
2765
[junit] WolfSSLTrustX509 Class
@@ -30,35 +68,116 @@ This will compile tests and the main wolfJSSE code and output with the results o
3068
[junit] Testing parse all.jks ... passed
3169
[junit] Testing verify ... passed
3270
...
33-
...
34-
...
3571
3672
build:
3773
3874
BUILD SUCCESSFUL
3975
Total time: 18 seconds
4076
```
41-
To compile and run examples bundled with wolfJSSE the command “ ant examples ” is used:
77+
78+
To compile and run examples bundled with wolfJSSE the command `ant examples`
79+
is used:
80+
4281
```
4382
$ ant examples
4483
```
45-
## Android Studio Build
4684

47-
An example Android Studio project is located in the directory IDE/Android. To run the example Android Studio project use the following steps;
85+
## Android Studio Build
86+
87+
An example Android Studio project is located in the directory `IDE/Android`.
88+
This is an example Android Studio project file for wolfssljni / wolfJSSE.
89+
This project should be used for reference only.
90+
91+
More details on tool and version information used when testing can be found in
92+
the `wolfssljni/IDE/Android/README.md`. The following steps outline what is
93+
required to run this example on an Android device or emulator.
94+
95+
### 1. Add Native wolfSSL Library Source Code to Project
96+
97+
This example project is already set up to compile and build the native
98+
wolfSSL library source files, but the wolfSSL files themselves have not been
99+
included in this package. You must download or link an appropriate version
100+
of wolfSSL to this project using one of the options below.
101+
102+
The project looks for the directory
103+
`wolfssljni/IDE/Android/app/src/main/cpp/wolfssl` for wolfSSL source code.
104+
This can added in multiple ways:
105+
106+
- OPTION A: Download the latest wolfSSL library release from www.wolfssl.com,
107+
unzip it, rename it to `wolfssl`, and place it in the direcotry
108+
`wolfssljni/IDE/Android/app/src/main/cpp/`.
109+
110+
```
111+
$ unzip wolfssl-X.X.X.zip
112+
$ mv wolfssl-X.X.X wolfssljni/IDE/Android/app/src/main/cpp/wolfssl
113+
```
114+
115+
- OPTION B: Alternatively GitHub can be used to clone wolfSSL:
116+
117+
```
118+
$ cd /IDE/Android/app/src/main/cpp/
119+
$ git clone https://github.com/wolfssl/wolfssl
120+
$ cp wolfssl/options.h.in wolfssl/options.h
121+
```
48122

49-
1. On an Android device, BKS format key stores are expected. To convert the JKS example bundles to BKS use the following commands:
123+
- OPTION C: A symbolic link to a wolfssl directory on the system by using:
124+
125+
```
126+
$ cd /IDE/Android/app/src/main/cpp/
127+
$ ln -s /path/to/local/wolfssl ./wolfssl
128+
```
129+
130+
### 2. Update Java Symbolic Links (Only applies to Windows Users)
131+
132+
The following Java source directory is a Unix/Linux symlink:
133+
134+
```
135+
wolfssljni/IDE/Android/app/src/main/java/com/wolfssl
136+
```
137+
138+
This will not work correctly on Windows, and a new Windows symbolic link needs
139+
to be created in this location. To do so:
140+
141+
1) Open Windows Command Prompt (Right click, and "Run as Administrator")
142+
2) Navigate to `wolfssljni\IDE\Android\app\src\main\java\com`
143+
3) Delete the existing symlink file (it shows up as a file called "wolfssl")
144+
145+
```
146+
del wolfssl
147+
```
148+
149+
4) Create a new relative symbolic link with `mklink`:
150+
151+
```
152+
mklink /D wolfssl ..\..\..\..\..\..\..\src\java\com\wolfssl\
153+
```
154+
155+
### 3. Convert Example JKS files to BKS for Android Use
156+
157+
On an Android device BKS format key stores are expected. To convert the
158+
JKS example bundles to BKS use the following commands. Note: you will need
159+
to download a version of the bcprov JAR from the Bouncy Castle website:
50160

51161
```
52162
cd examples/provider
53163
./convert-to-bks.sh <path/to/provider>
54164
```
55-
Example:
165+
166+
For exmaple, when using bcprov-ext-jdk15on-169.jar:
167+
56168
```
57169
cd examples/provider
58-
./convert-to-bks.sh ~/Downloads/bcprov-jdk15on-161.jar
170+
./convert-to-bks.sh ~/Downloads/bcprov-ext-jdk15on-169.jar
59171
```
60172

61-
2. Push BKS bundles up to the device along with certificates. To do this, start up the emulator/device and use "adb push". An example of this would be the following commands from root wolfssljni directory:
173+
### 4. Push BKS files to Android Device or Emulator
174+
175+
Push BKS bundles up to the device along with certificates. To do this start
176+
up the emulator/device and use `adb push`. An example of this would be the
177+
following commands from root wolfssljni directory. This step may be done
178+
after the starting Android Studio and compiling the project, but must be done
179+
before running the app or test cases.
180+
62181
```
63182
adb shell
64183
cd sdcard
@@ -68,35 +187,46 @@ mkdir examples/certs
68187
exit
69188
adb push ./examples/provider/*.bks /sdcard/examples/provider/
70189
adb push ./examples/certs/ /sdcard/examples/
190+
adb push ./examples/certs/intermediate/* /sdcard/examples/certs/intermediate/
71191
```
72192

73-
3. Add wolfSSL source code for compiling. The project looks for the directory wolfssljni/IDE/Android/app/src/main/cpp/wolfssl for wolfSSL source code. This can be done multiple ways one being to download the latest release from wolfSSL's website, unzip it, rename it to wolfssl, and place it in the directory wolfssljni/IDE/Android/app/src/main/cpp/. Alternatively GitHub can be used with "cd /IDE/Android/app/src/main/cpp/ && git clone https://github.com/wolfssl/wolfssl". And the final method to be mentioned in this document is by creating a symbolic link to a wolfssl directory on the system by using "cd /IDE/Android/app/src/main/cpp/ && ln -s /path/to/local/wolfssl ./wolfssl".
74-
75-
4. Open the Android studio project by double clicking on the Android folder in wolfssljni/IDE/.
193+
### 5. Import and Build the Example Project with Android Studio
76194

77-
5. Compile the project and run MainActivity from app -> java -> com ->example.wolfssl. This will ask for permissions to access the certificates in the
78-
/sdcard/ directory and then print out the server certificate information on success.
195+
1) Open the Android Studio project by double clicking on the `Android` folder
196+
in wolfssljni/IDE/. Or, from inside Android Studio, open the `Android` project
197+
located in the wolfssljni/IDE directory.
79198

80-
6. OPTIONAL : The androidTests can then be run after permissions have been given. app->java->com.wolfssl->provider.jsse.test->WolfSSLJSSETestSuite and
81-
app->java->com.wolfssl->test->WolfSSLTestSuite.
199+
2) Build the project and run MainActivity from app -> java/com/example.wolfssl.
200+
This will ask for permissions to access the certificates in the /sdcard/
201+
directory and then print out the server certificate information on success.
82202

83-
7. OPTIONAL : To build with TLS 1.3 enabled macros need added to IDE/Android/app/src/main/cpp/CMakeLists.txt. The macros needed to be defined
84-
are; `HAVE_HKDF`, `WC_RSA_PSS`, `HAVE_FFDHE_2048`, `HAVE_SUPPORTED_CURVES`,`WOLFSSL_TLS13` and `HAVE_TLS_EXTENSION`. Each of those should be added to the “add_definitions” list in the CMakeLists.txt file.
203+
3) OPTIONAL: The androidTests can be run after permissions has been given.
204+
app->java->com.wolfssl->provider.jsse.test->WolfSSLJSSETestSuite and
205+
app->java->com.wolfssl->test->WolfSSLTestSuite
85206

86207
## Generic IDE Build
87208

88-
For generic IDE builds create a new project in the IDE, then add source files from src/java. This will be the following packages:
209+
For generic IDE builds create a new project in the IDE, then add source files
210+
from `src/java`. This will be the following packages:
211+
89212
```
90213
com.wolfssl
91214
com.wolfssl.provider.jsse
92215
com.wolfssl.wolfcrypt
93216
```
94-
Run java.sh from the command line or have the IDE execute "java.sh" to generate the native shim layer linking against wolfSSL.
95-
96-
Add native library reference to the project. It should look in the lib directory for libwolfssl.jnilib (i.e. wolfssljni/lib/).
97-
98-
To compile test cases add the packages com.wolfssl.provider.jsse.test and com.wolfssl.test from the directory src/test. The project will also need JUNIT5 to run the tests.
99-
100-
If adding in optional examples then the source code in examples/provider/ can be added to the project. Optionally the IDE can execute examples/provider/ClientJSSE.sh. One of the difficult parts to adding in the examples is making sure the path to keystores is known to the IDE when it runs the examples, if trying to use the default keystores.
101217

218+
Run java.sh from the command line or have the IDE execute `java.sh` to generate
219+
the native shim layer linking against wolfSSL.
102220

221+
Add native library reference to the project. It should look in the lib
222+
directory for libwolfssl.jnilib (i.e. wolfssljni/lib/).
223+
224+
To compile test cases add the packages `com.wolfssl.provider.jsse.test` and
225+
`com.wolfssl.test` from the directory `src/test`. The project will also need
226+
Junit to run the tests.
227+
228+
If adding in optional examples then the source code in
229+
`examples/provider/` can be added to the project. Optionally the IDE can
230+
execute `examples/provider/ClientJSSE.sh`. One of the difficult parts to adding
231+
in the examples is making sure the path to keystores is known to the IDE when
232+
it runs the examples, if trying to use the default keystores.

0 commit comments

Comments
 (0)