The JCPROV PKCS#11 Java Wrapper

This section describes how to install and use the JCPROV Java wrapper for the PKCS#11 API. It contains the following topics:

>JCPROV Overview

>Installing JCPROV

>JCPROV Sample Programs

>JCPROV Sample Classes

>JCPROV API Documentation

JCPROV Overview

JCPROV is a Java wrapper for the PKCS#11 API. JCPROV is designed to be as similar to the PKCS#11 API as the Java language allows, allowing developers who are familiar with the PKCS#11 API to rapidly develop Java-based programs that exercise the PKCS#11 API.

AES-GMAC and AES-GCM are supported in JCPROV. Use CK_AES_CMAC_PARAMS.java to define the GMAC operation. Implementation is the same as for PKCS#11.

JDK compatibility

The JCPROV Java API is compatible with JDK 1.5.0 or higher.

The JCPROV library

The JCPROV library is implemented in jcprov.jar, under the namespace com.safenetinc.jcprov. It is accompanied by a shared library that provides the native methods used to access the appropriate PKCS#11 library. The name of the shared library is platform dependent, as follows:

Operating system Shared library
Windows (32 and 64 bit) jcprov.dll
Linux libjcprov.so
Solaris libjcprov.so
AIX libjcprov.so

Installing JCPROV

Use the SafeNet Luna Client Installer to install the JCPROV software (runtime and SDK packages). The software is installed in the location specified in the following table:

Operating system Installation location
Windows

C:\Program Files\safenet\lunaclient\jcprov

Linux

/usr/safenet/lunaclient/jcprov

Solaris /opt/safenet/lunaclient/jcprov
AIX /usr/safenet/lunaclient/jcprov

The installation includes a samples subdirectory ( ) and a javadocs subdirectory ( ).

Changing the Java JNI libraries (AIX only)

The Java VM on AIX does not support mixed mode JNI libraries. Mixed mode libraries are shared libraries that provide both 32-bit and 64-bit interfaces. It is therefore essential that you select the correct JNI library to use with your Java VM.

CAUTION!   When JCPROV is installed, links are automatically created to use the 32-bit versions of the JNI libraries. You need to update the links if you are using a 64-bit operating system.

To configure the JNI library for use with a 32-bit Java VM:

1.Ensure that the /usr/safenet/lunaclient/jcprov/lib/libjcprov.a symbolic link points to a 32-bit version of the library (libjcprov_32.a), for example /usr/safenet/lunaclient/jcprov/lib/libjcprov_32.a.

2.Ensure that the /usr/safenet/lunaclient/jcprov/lib/libjcryptoki.a symbolic link points to a 32-bit version of the library(libjcryptoki_32.a), for example /usr/safenet/lunaclient/jcprov/lib/libjcryptoki_32.a.

To configure the JNI library for use with a 64-bit Java VM:

1.Ensure that the /usr/safenet/lunaclient/jcprov/lib/libjcprov.a symbolic link points to a 64-bit version of the library (libjcprov_64.a), for example /usr/safenet/lunaclient/jcprov/lib/libjcprov_64.a.

2.Ensure that the /usr/safenet/lunaclient/jcprov/lib/libjcryptoki.a symbolic link points to a 64-bit version of the library (libjcryptoki_64.a), for example /usr/safenet/lunaclient/jcprov/lib/libjcryptoki_64.a.

JCPROV Sample Programs

Several sample programs are included to help you become familiar with JCPROV. The binaries for the sample programs are included in the jcprovsamples.jar file. You must compile the binaries before you can use the sources provided.

Compiling and running the JCPROV sample programs

CAUTION!   You require JDK 1.5.0 or newer to compile the JCPROV sample programs.

It is recommended that you compile the samples in their installed locations, so that the path leading to the samples directory in the installation location will allow them to be executed as documented below.

Prerequisites

For best results, perform the following actions before attempting to compile the sample programs:

>Add jcprov.jar to your CLASSPATH environment variable

>Add a path to the CLASSPATH environment variable that allows JCPROV to use the com.safenetinc.jcprov.sample namespace. This is required since all of the applications are registered under this namespace.

To compile the JCPROV sample programs on UNIX/Linux:

1.Set the CLASSPATH environment variable to point to jcprov.jar and the root path for the sample programs.
export CLASSPATH=<jcprov_installation_directory>/*

2. Change directory to the sample programs path.
cd /usr/safenet/lunaclient/jcprov/samples/com/safenetinc/jcprov/sample

3.Use the javac program to compile the examples.
javac GetInfo.java

4.Use the java program to run the samples.
java com.safenetinc.jcprov.sample.GetInfo -slot 0 -info

To compile the JCPROV sample programs on Windows

1.Set the CLASSPATH environment variable to point to jcprov.jar and the root path for the sample programs:
C:\> set “CLASSPATH= C:\Program Files\safenet\lunaclient\jcprov\jcprov.jar; C:\program files\safenet\jcprov\samples”

2. Use the javac program to compile the examples:
C:\Program Files\safenet\lunaclient\jcprov\samples> javac GetInfo.java

3.Use the java program to run the samples:
C:\Program Files\safenet\lunaclient\jcprov\samples> java com.safenetinc.jcprov.sample.GetInfo -info -slot 0

JCPROV Sample Classes

JCPROV provides sample classes in the <jcprov_installation_directory>/samples directory. These include:

>DeleteKey

>EncDec

>GenerateKey

>GetInfo

>Threading

Other samples contained in the samples directory may be more or less useful to you depending on what you need. Each relevant sample has a description of both its purpose and its parameters in the header section of its file.

DeleteKey

Demonstrates the deletion of keys.

A generated key is required to use this script. To generate a key, use GenerateKey or refer to Using Java Keytool with SafeNet Luna PCIe HSM

Usage

java com.safenetinc.jcprov.sample.DeleteKey -keyType <keytype> -keyName <keyname> [-slot <slotId>] [-password <password>]

Parameters
Parameter Description
-keytype

Specifies the type of key you want to delete. Enter this parameter followed by one of the following supported key types:

>des - single DES key

>des2 - double-length, triple-DES key

>des3 - triple-length, triple-DES key

>rsa - RSA key pair

-keyName Specifies the name (label) of the key you want to delete. Enter this parameter followed by the name (label) of the key you want to delete.
-slot Specifies the slot for the HSM or partition that contains the key you want to delete. Optionally enter this parameter followed by the slot identifier for the HSM or partition that contains the key you want to delete. If this parameter is not specified, the default slot is used.
Default: 1
-password Specifies the password for the slot. Optionally enter this parameter followed by the slot password to delete a private key.

EncDec

Demonstrates encryption and decryption operations by encrypting and decrypting a string.

A generated key is required to use this script. To generate a key, use GenerateKey or refer to Using Java Keytool with SafeNet Luna PCIe HSM

Usage

java com.safenetinc.jcprov.sample.EncDec -keyType <keytype> -keyName <keyname> [-slot <slotId>] [-password <password>]

Parameters
Parameter Description
-keytype

Specifies the type of key you want to use to perform the encryption/decryption operation. Enter this parameter followed by one of the following supported key types:

>des - single DES key

>des2 - double-length, triple-DES key

>des3 - triple-length, triple-DES key

>rsa - RSA key pair

-keyName Specifies the name (label) of the key you want to use to perform the encryption/decryption operation. Enter this parameter followed by the name (label) of the key you want to use to perform the encryption/decryption operation.
-slot Specifies the slot for the HSM or partition that contains the key you want to use to perform the encryption/decryption operation. Optionally enter this parameter followed by the slot identifier for the HSM or partition that contains the key you want to use to perform the encryption/decryption operation. If this parameter is not specified, the default slot is used.
Default: 1
-password Specifies the password for the slot. Optionally enter this parameter followed by the slot password to encrypt/decrypt a private key.

GenerateKey

Demonstrates the generation of keys.

Usage

java com.safenetinc.jcprov.sample.GenerateKey -keyType <keytype> -keyName <keyname> [-slot <slotId>] [-password <password>]

Parameters
Parameter Description
-keytype

Specifies the type of key you want to generate. Enter this parameter followed by one of the following supported key types:

>des - single DES key

>des2 - double-length, triple-DES key

>des3 - triple-length, triple-DES key

>rsa - RSA key pair

-keyName Specifies the name (label) of the key you want to generate. Enter this parameter followed by the name (label) of the key you want to generate.
-slot Specifies the slot for the HSM or partition where you want to generate the key. Optionally enter this parameter followed by the slot identifier for the HSM or partition where you want to generate the key. If this parameter is not specified, the default slot is used.
Default: 1
-password Specifies the password for the slot. Optionally enter this parameter followed by the slot password to generate a private key.

GetInfo

Demonstrates the retrieval of slot and token information.

Usage

java com.safenetinc.jcprov.sample.GetInfo {-info | -slot [<slotId>] | -token [<slotId>]}

Parameters
Parameter Description
-info Retrieve general information.
-slot Retrieve slot information for the specified slot. Enter this parameter followed by the slot identifier for the slot you want to retrieve information from. If <slotId> is not specified, information is retrieved for all available slots.
-token Retrieve token information for the HSM or partition in the specified slot. Enter this parameter followed by the slot identifier for the HSM or partition you want to retrieve information from. If <slotId> is not specified, information is retrieved for all available slots.

Threading

This sample program demonstrates different ways to handle multi-threading.

This program initializes the Cryptoki library according to the specified locking model. Then a shared handle to the specified key is created. The specified number of threads is started, where each thread opens a session and then enters a loop which does a triple DES encryption operation using the shared key handle.

It is assumed that the key exists in slot 1, and is a Public Token object.

A generated key is required to use this script. To generate a key, use GenerateKey or refer to Using Java Keytool with SafeNet Luna PCIe HSM

Usage

java com.safenetinc.jcprov.sample.Threading -numThreads <numthreads> -keyName <keyname> -locking { none | os | functions } [-v]

Parameters
Parameter Description
-numthreads Specifies the number of threads you want to start. Enter this parameter followed by an integer that specifies the number of threads you want to start.
-keyName Specifies the triple-DES key to use for the encryption operation. Enter this parameter followed by the name (label) of the key to use for the encryption operation.
-locking

Specifies the locking model used when initializing the Cryptoki library. Enter this parameter followed by one of the following locking models:

>none - do not use locking when initializing the Cryptoki library. If you choose this option, some threads should report failures.

>os - use the native operating system mechanisms to perform locking.

>functions - use Java functions to perform locking

-v Specifies the password for the slot. Optionally enter this parameter followed by the slot password to generate a private key.

JCPROV API Documentation

The JCPROV API is documented in a series of javadocs. The documentation is located in the <jcprov_installation_directory>/javadocs directory.