175 lines
5.2 KiB
Markdown
175 lines
5.2 KiB
Markdown
|
|
# wolfJSSE Provider Examples
|
|
|
|
This directory contains examples for the wolfSSL JSSE provider (wolfJSSE).
|
|
|
|
Examples should be run from the package root directory, and using the provided
|
|
wrapper scripts. The wrapper scripts set up the correct environment variables
|
|
for use with the wolfJSSE provider included in the wolfssljni package. For
|
|
example to run the example JSSE server and client, after compiling wolfSSL and
|
|
wolfssljni:
|
|
|
|
```
|
|
$ cd <wolfssljni_root>
|
|
$ ./examples/provider/ServerJSSE.sh
|
|
$ ./examples/provider/ClientJSSE.sh
|
|
```
|
|
|
|
## Notes on Debug and Logging
|
|
|
|
wolfJSSE debug logging can be enabled by using `-Dwolfjsse.debug=true` at
|
|
runtime.
|
|
|
|
wolfSSL native debug logging can be enabled by using `-Dwolfssl.debug=true` at
|
|
runtime, if native wolfSSL has been compiled with `--enable-debug`.
|
|
|
|
JDK debug logging can be enabled using the `-Djavax.net.debug=all` option.
|
|
|
|
## wolfJSSE Example Client and Server
|
|
|
|
Example client/server applications that use wolfJSSE along with the SSLSocket
|
|
API.
|
|
|
|
**ServerJSSE.java** - Example wolfJSSE server \
|
|
**ClientJSSE.java** - Example wolfJSSE client
|
|
|
|
These examples can be run with the provided bash scripts:
|
|
|
|
```
|
|
$ ./examples/provider/ServerJSSE.sh <options>
|
|
$ ./examples/provider/ClientJSSE.sh <options>
|
|
```
|
|
|
|
## ClientSSLSocket.java
|
|
|
|
Very minimal JSSE client example using SSLSocket. Does not support all the
|
|
options that ClientJSSE.java does.
|
|
|
|
Example usage is:
|
|
|
|
```
|
|
$ ./examples/provider/ClientSSLSocket.sh [host] [port] [keystore] [truststore]
|
|
```
|
|
|
|
Example usage for connecting to the wolfSSL example server is:
|
|
|
|
```
|
|
$ ./examples/provider/ClientSSLSocket.sh 127.0.0.1 11111 \
|
|
./examples/provider/client.jks ./examples/provider/ca-server.jks
|
|
```
|
|
|
|
The password for client.jks is: "wolfSSL test"
|
|
|
|
## MultiThreadedSSLClient.java
|
|
|
|
Multi threaded SSLSocket example that connects a specified number of client
|
|
threads to a server. Intended to test multi-threading with wolfJSSE.
|
|
|
|
This example creates a specified number of client threads to a server located
|
|
at 127.0.0.1:11118. This example is set up to use the SSLSocket class. It makes
|
|
one connection (handshake), sends/receives data, and shuts down.
|
|
|
|
A random amount of time is injected into each client thread before:
|
|
|
|
1) The SSL/TLS handshake
|
|
2) Doing I/O operations after the handshake
|
|
|
|
The maximum amount of sleep time for each of those is "maxSleep", or 3 seconds
|
|
by default. This is intended to add some randomness into the the client thread
|
|
operations.
|
|
|
|
Example usage:
|
|
|
|
```
|
|
$ ant examples
|
|
$ ./examples/provider/MultiThreadedSSLClient.sh -n <num_client_threads>
|
|
```
|
|
|
|
This example is designed to connect against the MultiThreadedSSLServer example:
|
|
|
|
```
|
|
$ ./examples/provider/MultiThreadedSSLServer.sh
|
|
```
|
|
|
|
This example also prints out average SSL/TLS handshake time, which is measured
|
|
in milliseconds on the "startHandshake()" API call.
|
|
|
|
## MultiThreadedSSLServer.java
|
|
|
|
SSLServerSocket example that creates a new thread per client connection.
|
|
|
|
This server waits in an infinite loop for client connections, and when connected
|
|
creates a new thread for each connection. This example is compiled when
|
|
`ant examples` is run in the package root.
|
|
|
|
```
|
|
$ ant examples
|
|
$ ./examples/provider/MultiThreadedSSLServer.sh
|
|
```
|
|
|
|
For multi threaded client testing, test against MultiThreadedSSLClient.sh.
|
|
For example, to connect 10 client threads:
|
|
|
|
```
|
|
$ ./examples/provider/MultiThreadedSSLClient.sh -n 10
|
|
```
|
|
|
|
## ProviderTest.java
|
|
|
|
This example tests the wolfSSL provider installation. It lists all providers
|
|
installed on the system, tries to look up the wolfSSL provider, and if
|
|
found, prints out the information about the wolfSSL provider. Finally, it tests
|
|
what provider is registered to provide TLS to Java.
|
|
|
|
This app can be useful for testing if wolfJSSE has been installed
|
|
correctly at the system level.
|
|
|
|
```
|
|
$ ./examples/provider/ProviderTest.sh
|
|
```
|
|
|
|
Note, if wolfJSSE has not been installed at the OS system level, wolfJSSE
|
|
will not show up as an installed provider when this example is run.
|
|
|
|
## ThreadedSSLSocketClientServer.java
|
|
|
|
SSLSocket example that connects a client thread to a server thread.
|
|
|
|
This example creates two threads, one server and one client. The examples
|
|
are set up to use the SSLSocket and SSLServerSocket classes. They make
|
|
one connection (handshake) and shut down.
|
|
|
|
Example usage:
|
|
|
|
```
|
|
$ ./examples/provider/ThreadedSSLSocketClientServer.sh
|
|
```
|
|
|
|
## DtlsClientEngine.java and DtlsServerEngine.java
|
|
|
|
Example client/server applications that demonstrate how to use SSLEngine with DTLS 1.3.
|
|
|
|
**DtlsServerEngine.java** - Example DTLS 1.3 server using SSLEngine
|
|
**DtlsClientEngine.java** - Example DTLS 1.3 client using SSLEngine
|
|
|
|
These examples show how to implement DTLS 1.3 with SSLEngine for datagram-based
|
|
secure communication. Unlike the TCP-based examples, these use DatagramSocket for
|
|
UDP transport and handle the complexities of DTLS, including session tickets
|
|
and handshake state management.
|
|
|
|
Run the examples with the provided bash scripts:
|
|
|
|
```
|
|
$ ./examples/provider/DtlsServerEngine.sh
|
|
$ ./examples/provider/DtlsClientEngine.sh
|
|
```
|
|
|
|
The client connects to the server, sends a message, and receives the echoed response.
|
|
Both examples support various command-line options that can be viewed with the -? flag.
|
|
|
|
## Support
|
|
|
|
Please contact the wolfSSL support team at support@wolfssl.com with any
|
|
questions or feedback.
|
|
|