Java examples

The example programs and source code described in this section are supplied on your Developer installation media. Several of the utilities are not designed to be executed directly but are used by other programs. For more information on these examples, see the in-line comments in the example source code and the Javadocs installed in your nfast directory.

Extract and compile the Java examples

The Java example files are in subdirectories of the %NFAST_HOME%\java\examples (Windows) or /opt/nfast/java/examples (Linux) directory.

  1. Extract the example files:

    jar xf <path-to-examples-jar-file>

    The JCE-related examples extract into the com/ncipher/provider/examples subtree.

  2. Compile the examples:

    1. If using Java 8 or earlier (using "--class-path or -cp")

      javac -cp <fully-qualified-path-to-JCE-provider-jar-file> *.java

      For example:

      javac -cp /opt/nfast/java/classes/nCipherKM.jar *.java
      javac -cp /opt/nfast/java/classes/nCipherKM.jar com/ncipher/provider/examples/*.java
    2. If using Java 9 or later (using "--module-path or -p")

      javac -p <fully-qualified-path-to-JCE-provider-jar-file> --add-modules ALL-MODULE-PATH *.java

      For example:

      javac -p /opt/nfast/java/classes --add-modules ALL-MODULE-PATH *.java
      javac -p /opt/nfast/java/classes --add-modules ALL-MODULE-PATH com/ncipher/provider/examples/*.java

Java key management example utilities

AppKeyGen.java

This example utility demonstrates application key generation and import.

GenerateExport.java

This example utility generates an RSA Key and optionally exports the public key out of a module as plain text.

It demonstrates the creation of an OCS.

KMJavaFloodTest.java

This example utility demonstrates the use of the mergeKeyIDs method in the Key class.

This method merges all the loaded private keyids into a single keyid that can be used in nCore API calls when load-sharing is required.

NFKMInfo.java

Displays information about the Security World.

This example Java utility is analogous to its C version except that NFKMInfo.java does not return information on world/module generation.

NVRamRTCUtil.java

This is an example program to demonstrate interacting with the NVRAM and RTC. The program allows you to list all files in NVRAM, delete a file in NVRAM, delete all the files in NVRAM, display the current time in the RTC and to set the RTC to the system clock.

SimpleCrypt.java

This is a simple example that graphically encrypts and decrypts data with a Triple-DES (DES3) key from the Security World. Cipher Block Chaining mode (CBC) and initialization vectors are selected randomly. This information is prefixed to the cipher text.

SimpleCrypt.java only works with module protected Triple-DES (DES3) keys.

SlotPoller.java

This example utility polls all the available slots.

You can determine whether the state of the slot has changed by calling getIC() on the slot. This method is more efficient than using update(). The module serial number, slot number, and insertion count are displayed when a card is inserted or removed.

Java JCE/CSP example utilities

AsymmetricEncryptionExample.java

This example generates an RSA key pair and an X509 public key specification. It performs encryption and decryption of random plain text.

DK_ECDHKAExample.java

This example utility demonstrates:

  • Creation of two ECDH key pairs.

  • Key agreement using ECDHWITHSHA1KDF between two parties.

  • Encryption/Decryption using the shared secret key.

ECDHExample.java

This example utility demonstrates:

  • Creation of an ECDH key.

  • ECDH key agreement.

  • Encryption / decryption of a message using AES.

ECIESExample.java

This example utility demonstrates:

  • Creation of an ECDH key pair by the receiver.

  • Key wrapping by the sender using the agreed ECIES parameters and the public half of receiver’s ECDH key pair.

  • Key unwrapping by the receiver using the agreed ECIES parameters.

  • Encryption/Decryption using the shared secret key.

EdDSAExample.java

This example utility demonstrates how to generate and store key for use in Ed25519 and Ed25519ph operations.

The example generates an Ed25519 key pair, creates a KeyStore and stores both halves of the key pair.

This example may require sudo permissions on Linux machines.

JCEChanTest.java

This example measures the data rate achieved by different symmetric encryption and decryption operations. You can use optional program arguments to change the cipher, key, data, and provider parameters.

JCEFloodTest.java

This example utility does performance testing for RSA, DSA, ECDSA and Ed25519 private key operations.

It demonstrates:

  • RSA/DSA/ECDSA/Ed25519 Key Pair generation.

  • RSA/DSA/ECDSA/EdDSA signing.

  • RSA encryption/decryption.

  • Use of the kmjava classes to load a key to use with the nCipherKM JCE provider.

  • Load-balancing using kmjava and KeyStore-loaded keys.

JCESigTest.java

This example measures the data rate achieved by many threads simultaneously performing signing and verifying operations. You can use optional program arguments to change the thread, key, data, provider, and sampling parameters.

KeyLoadTimer.java

This example measures the time taken to get many keys from an nCipher.sworld key store. It also demonstrates how to create, load and store key stores, as well as how to set and get key entries.

This example may require sudo permissions on Linux machines.

KeyStorageExample.java

This example creates a new KeyStore containing an AES key. It performs load-balanced encryption and decryption of random plain text using a KeyStore loaded key.

This example may require sudo permissions on Linux machines.

NCipherLibraryInteropExample.java

This example loads an existing AES key from the Security World across all usable modules and performs load-balanced encryption and decryption of random plain text.

SignaturesExample.java

This example generates RSA, DSA, ECDSA and Ed25519 key pairs. For the associated mechanism of each key type, it performs signing and verification of random plain text.

SslClientExample.java

Before building this example, the user will need to edit SslClientExample.java to insert an appropriate https web site address in the two relevant places. When run, this example connects to the user-specified secure web site over an encrypted SSL connection and dumps the index page to the console.

Before running this example, you must run PrepareSslExamples.java. For more information, see Java JCE/CSP example utilities

SslServerExample.java

This example creates a simple SSL Web server instance on the local host that can be accessed with a Web browser.

Before running this example, you must run PrepareSslExamples.java. For more information, see Java JCE/CSP example utilities

SymmetricEncryptionExample.java

This example generates symmetric keys and uses them to perform encryption and decryption of random plain text with different cipher modes and padding types.

SignatureTest.java

This example utility demonstrates:

  • generation of an RSA/DSA/ECDSA Key Pair

  • export of the PublicKey using X509 encoding

  • signing some random data

  • decoding the PublicKey

  • verification of the signature.

This example requires the Bouncy Castle security provider to be loaded and configured to run properly.

Java generic stub examples

The example utilities described in this section are directly analogous to their namesake C example utilities supplied with the nShield C generic stub. The Java incarnations are shipped as source code only.

BlobInfo.java

This example utility displays information in a blob. It demonstrates how to determine information about the contents of a blob.

BlobInfo.java is analogous to the C Generic Stub call NFast_ExamineBlob.

Channel.java

This example utility is a function-based wrapper to symmetric bulk-encryption channels for use by EasyConnection.java.

CheckMod.java

This example utility checks modulo-exponentiation operations against a test file.

CrypTest.java

This example utility is a test program for some module algorithms. It demonstrates:

  • the use of EasyConnection

  • symmetric cryptography and channels.

DesKat.java

This example utility is for DES known answer tests.

It demonstrates simple nCore key management usage.

DKTest.java

This example utility provides a simple demonstration of the use of DeriveKey.

EasyConnection.java

This example utility is a function-based interface to a subset of nCore.

Enquiry.java

This example utility displays enquiry information.

It demonstrates:

  • simple nCore usage

  • the enquiry command.

FloodTest.java

This example utility does performance testing for modexp code.

It demonstrates:

  • simple bignum usage

  • asynchronous command processing (NFastApp_Wait and NFastApp_Query).

GenCert.java

This example utility generates a certificate.

It demonstrates the use of the BuildCmdCert class.

InitUnit.java

This example utility initializes a module with a dummy HKNSO (like the C initunit utility).

NFEnum.java

This example utility is a helper class used by SigTest. It is an example extension to jnfopt for looking up an nCore Enumeration class. It cannot be invoked by itself.

ReportVersion.java

This example utility reports the embedded version information from the current nfjava component. ReportVersion.java outputs the version of the nfjava library found on the class path.

These examples are not intended to be invoked directly. They are called by other programs. The following two utilities, EasyConnection and Channel, form a Java analog of the nCore simple command functions as shipped to C developers in libexamples.a. You can compare and contrast this example with the C example simplecmd.h.

You cannot invoke EasyConnection and Channel directly; CrypTest invokes them. For more information, see the Javadoc documentation.

ScoreKeeper.java

This example utility is shared code used by SigTest and FloodTest and cannot be invoked on its own. It has helper classes for output reporting by SigTest and FloodTest.

SigTest.java

This example utility does signature performance testing.

It demonstrates asynchronous command processing (NFastApp_Wait and NFastApp_Query).

Java is not a high-performance language. On slow host systems or systems with multiple modules, it is very common to be limited by the CPU of the host machine. As a result, this example often does not show the true performance capabilities of the module. If you want to test module performance, as distinct from application performance, use the C version of SigTest instead.