Build and run Java examples

The following Java examples are included:

Prerequisites

The following versions of Java have been tested to work with, and are supported by, your nShield Security World Software:

  • Java8 (or Java 1.8x)

  • Java11

  • Java17

  • Java21

Ensure that Java is installed before you install the Security World software. The Java executable must be on your system path.

If you can do so, please use the latest Java version currently supported by Entrust that is compatible with your requirements. Java versions before those shown are no longer supported.

The Java interface

The Java host-side examples work with the same SEE machines as the C host-side examples, with build and signing instructions in Build and sign example SEE machines on Linux and Build and sign example SEE machines on Windows.

Java applications using SEEJobs to communicate with the SEE machine can use the PublishedSEEWorld class to talk to the CSEE application that has been auto-loaded via the [codesafe] section in the config file or run directly using hsc_codesafe. Existing Java applications that used PublishedSEEWorld class to send SEEJobs to previous HSM models can work unchanged with CodeSafe 5 as well.

Applications that wish to create the SEE World ID directly from the client application (rather than leaving it to the automatic configuration code to register it as a published object) are recommended to use the SEEWorld5 class to simplify that initialization. Existing applications that used SEEWorld to do this with previous HSM models should now use SEEWorld5 instead.

Build the examples

The Java example files are in the nCipherKM-See-Examples.jar in opt/nfast/java/examples (Linux) or %NFAST_HOME%\java\examples (Windows).

Extract and compile the examples:

Linux
cd /opt/nfast/java/examples
jar xf nCipherKM-SEE-Examples.jar
jar xf ../classes/nCipherKM-jhsee.jar
javac -cp /opt/nfast/java/classes/nCipherKM.jar com/ncipher/see/hostside/*.java
javac -cp .:/opt/nfast/java/classes/nCipherKM.jar com/ncipher/see/hostside/examples/benchmark5/BenchMark5.java
javac -cp .:/opt/nfast/java/classes/nCipherKM.jar com/ncipher/see/hostside/examples/echo5/Echo5.java
javac -cp .:/opt/nfast/java/classes/nCipherKM.jar com/ncipher/see/hostside/examples/helloworld5/HelloWorld5.java
javac -cp .:/opt/nfast/java/classes/nCipherKM.jar com/ncipher/see/hostside/examples/hosttickets5/HostTickets5.java
Windows
cd %NFAST_HOME%\java\examples
jar xf nCipherKM-SEE-Examples.jar
jar xf ..\classes\nCipherKM-jhsee.jar
javac -cp "%NFAST_HOME%\java\classes\nCipherKM.jar com\ncipher\see\hostside\*.java"
javac -cp "%NFAST_HOME%\java\classes\nCipherKM.jar ^ com\ncipher\see\hostside\examples\benchmark5\BenchMark5.java"
javac -cp "%NFAST_HOME%\java\classes\nCipherKM.jar ^ com\ncipher\see\hostside\examples\echo5\Echo5.java"
javac -cp "%NFAST_HOME%\java\classes\nCipherKM.jar ^ com\ncipher\see\hostside\examples\helloworld5\HelloWorld5.java"
javac -cp "%NFAST_HOME%\java\classes\nCipherKM.jar ^ com\ncipher\see\hostside\examples\hosttickets5\HostTickets5.java"

Run the examples

All examples can be run with the following help options:

  • -m, --module=MODULE: Use module MODULE.
    Default: 1

  • -n, --pubname=PUBNAME: Use the specified published object name (should match worldid_pubname in config) if different from the default.

  • -h, --help: Displays the help message.

  • -v, --version: Displays the version number of this program.

  • -u, --usage: Displays a brief usage summary.

Before running the examples, ensure that you are in the examples directory:

Linux
cd /opt/nfast/java/examples
Windows
cd %NFAST_HOME%\java\examples

BenchMark5

BenchMark5 is a simple demonstration of a Java hostside app for benchmarking end-to-end communication and crypto processing time.

Linux
java -cp .:/opt/nfast/java/classes/nCipherKM.jar com.ncipher.see.hostside.examples.benchmark5.BenchMark5 [options] <key-app>
Windows
java -cp "%NFAST_HOME%\java\classes\nCipherKM.jar ^
com\ncipher\see\hostside\examples\benchmark5\BenchMark5 [options] <key-app>"

Options (in addition to common options):

  • -s, --slot=SLOT: Use slot SLOT for operator cards.
    Default: 0

  • -t, --threads=THREADS: Use THREADS threads.
    Default: 32

  • -i, --iterations=ITERATIONS: Each thread will perform ITERATIONS iterations.
    Default: 100

  • -l, --logfile=LOGFILE: Record public key and timestamps in file LOGFILE.

Arguments:

  • key-app: The key to be used to encrypt the data. This must be an RSA key, for example simple rsa2k. See generatekey for more information.

For example (this assumes that the SEE machine was loaded with the default bmsee as the published object name):

$ java -cp .:/opt/nfast/java/classes/nCipherKM.jar com.ncipher.see.hostside.examples.benchmark5.BenchMark5 -i 10 simple rsa2k
Generating 320 Timestamps Using 32 threads
Sending ticket...
Threads started...
Finished!

Echo5

Echo5 is a simple demonstration of a Java hostside app for performance testing.

Linux
java -cp .:/opt/nfast/java/classes/nCipherKM.jar com.ncipher.see.hostside.examples.echo5.Echo5 [options]
Windows
java -cp "%NFAST_HOME%\java\classes\nCipherKM.jar com\ncipher\see\hostside\examples\echo5\Echo5 [options]

Options (in addition to common options):

  • -t, --threads=THREADS: Use THREADS threads.
    Default: 32

  • -p, --payload=PAYLOAD: Send PAYLOAD bytes.
    Default: 32

  • -i, --iterations=ITERATIONS: Each thread will perform ITERATIONS iterations.
    Default: 100

  • -e, --verify: Verify that the returned value matches the value sent.

For example (this assumes that the SEE machine was loaded with the default echosee as the published object name):

$ java -cp .:/opt/nfast/java/classes/nCipherKM.jar com.ncipher.see.hostside.examples.echo5.Echo5 -i 10
Threads = 32 Payload = 32 bytes Iterations = 10 Verify replies = OFF
320 jobs in 0.04 seconds = 9006.18 jobs/Second,  288198 bytes/second

HelloWorld5

HelloWorld5 is a simple demonstration of a Java hostside app talking to a C SEE machine. It takes the text from an <inputFile> and outputs it with all the lower-case text converted to upper-case text.

The HelloWorld5.java example is not intended for use as the basis for real world applications.
Linux
java -cp .:/opt/nfast/java/classes/nCipherKM.jar com.ncipher.see.hostside.examples.helloworld5.HelloWorld5 [options] <inputFile>
Windows
java -cp "%NFAST_HOME%\java\classes\nCipherKM.jar ^
com\ncipher\see\hostside\examples\helloworld5\HelloWorld5 [options] <inputFile>"

For example (this assumes that the SEE machine was loaded with the default hellosee as the published object name):

$ cat /tmp/testfile.txt
lowercase
$ java -cp .:/opt/nfast/java/classes/nCipherKM.jar com.ncipher.see.hostside.examples.helloworld5.HelloWorld5 /tmp/testfile.txt
LOWERCASE

HostTickets5

HostTickets5 is a simple demonstration of a Java hostside app using tickets.

Linux
java -cp .:/opt/nfast/java/classes/nCipherKM.jar com.ncipher.see.hostside.examples.hosttickets5.HostTickets5 [options]
Windows
java -cp "%NFAST_HOME%\java\classes\nCipherKM.jar ^
com\ncipher\see\hostside\examples\hosttickets5\HostTickets5 [options]"

Options (in addition to common options):

  • -s, --string=STRING: String to be encrypted.
    If you do not use this option, you will be prompted for a string when you execute the command.

For example (this assumes that the SEE machine was loaded with the default ticketsee as the published object name):

$ java -cp .:/opt/nfast/java/classes/nCipherKM.jar com.ncipher.see.hostside.examples.hosttickets5.HostTickets5  -s encryptme
String to be encrypted = encryptme
Sending ticket...
Sending blobbed key...
Sending encrypted text...
Decrypted text = encryptme