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
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 ( 64 bit) | jcprov.dll |
| Linux | libjcprov.so |
| Solaris | libjcprov.so |
| AIX | libjcprov.so |
Installing JCPROV
| 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.
NOTE Luna HSM Client 10.1 and newer includes libraries for 64-bit operating systems only.
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:
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 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 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 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.
