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 matchworldid_pubname
inconfig
) 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 examplesimple 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