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 interface works with the same SEE machines as the C compatibility interface, see Compatibility layer for legacy SEE machines. These examples work with the SEE machines built in Build and sign example SEE machines on Linux and Build and sign example SEE machines on Windows.

CodeSafe5 uses SEEWorld5 instead of SEEWorld and SEE5Connection instead of EasyConnection. The SEE5Connection constructor takes the same arguments as the EasyConnection constructor. The only difference in behavior between SEE5Connection and EasyConnection is the handling of SEEJob commands: if a SEE5Connection has an open socket, SEEJob commands are diverted to the socket. This is the same as the legacy SEE machine interface. SEE5Connection can only route to a single module. World ID is ignored.

If you are supplying a SEE5Connection to the SEE5World constructor, do not open the socket. The SEE5World constructor opens the socket and it will fail if the socket is already open.

The interface supports multi-threaded access to the SEE machine with asynchronous command processing. There is no timeout on commands, so if no reply is received, threads could be blocked indefinitely.

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 the examples take the following arguments:

  • ipAddress: The IPv6 address of the container. This can be obtained by running csadmin list --esn <module-esn>, assuming that the SEE machine has been started.

  • UUID: This can be obtained by running csadmin list.

  • see-signing-key-hash (without spaces): This can be obtained by running npkgtool inspect with the signed SEE machine.

    The key hash is on the .data.hash= line.

    For example:

    $ npkgtool inspect hello-signed.cs5
....
NpkgRecord.item.tag= KeyData
               .value.keyname= ask
                     .use= FileSignature
                     .hashid.mech= SHA1Hash
                            .data.hash= xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx
....

All examples can be run with the following help options:

  • -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 benchmarks.

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

Options:

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

  • -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:

$ java cp .:/opt/nfast/java/classes/nCipherKM.jar com.ncipher.see.hostside.examples.benchmark5.BenchMark5 -i 10 xxxx::xxx:xxxx:xxxx:xxxx%nshield0 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 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] <ipAddress> <UUID> <see-signing-key-hash>
Windows
java cp "%NFAST_HOME%\java\classes\nCipherKM.jar ^
com\ncipher\see\hostside\examples\echo5\Echo5 [options] <ipAddress> <UUID> <see-signing-key-hash>

Options:

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

  • -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:

$ java cp .:/opt/nfast/java/classes/nCipherKM.jar com.ncipher.see.hostside.examples.echo5.Echo5 -i 10 xxxx::xxx:xxxx:xxxx:xxxx%nshield0 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
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> <ipAddress> <UUID> <see-signing-key-hash>
Windows
java cp "%NFAST_HOME%\java\classes\nCipherKM.jar ^
com\ncipher\see\hostside\examples\helloworld5\HelloWorld5 [options] <inputFile> <ipAddress> <UUID> <see-signing-key-hash>"

Options:

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

For example:

$ cat /tmp/testfile.txt
lowercase
$ java cp .:/opt/nfast/java/classes/nCipherKM.jar com.ncipher.see.hostside.examples.helloworld5.HelloWorld5 /tmp/testfile.txt xxxx::xxx:xxxx:xxxx:xxxx%nshield0 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
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] <ipAddress> <UUID> <signing-key-hash>
Windows
java cp "%NFAST_HOME%\java\classes\nCipherKM.jar ^
com\ncipher\see\hostside\examples\hosttickets5\HostTickets5 [options] <ipAddress> <UUID> <see-signing-key-hash>"

Options:

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

  • -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:

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