|
Home > |
|---|
This section describes how to install and use the JCPROV Java wrapper for the PKCS#11 API. It contains the following topics:
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.
Note: 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.
The JCPROV Java API is compatible with JDK 1.5.0 or higher.
The JCPROV library is implemented in jcprov.jar, under the namespace safenet.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 |
| HP-UX | libjcprov.sl |
| AIX | libjcprov.so |
Use the SafeNet 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 |
| HP-UX | /opt/safenet/lunaclient/jcprov |
| AIX | /usr/safenet/lunaclient/jcprov |
The installation includes a samples subdirectory ( ) and a javadocs subdirectory ( ).
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.
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.
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.
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.
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.
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 safenet.jcprov.sample namespace. This is required since all of the applications are registered under this namespace.
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
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 safenet.jcprov.samples.GetInfo -info
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.
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 HSM
java safenet.jcprov.sample.DeleteKey -keyType <keytype> -keyName <keyname> [-slot <slotId>] [-password <password>]
| 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. |
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 HSM
java safenet.jcprov.sample.EncDec -keyType <keytype> -keyName <keyname> [-slot <slotId>] [-password <password>]
| 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. |
Demonstrates the generation of keys.
java safenet.jcprov.sample.GenerateKey -keyType <keytype> -keyName <keyname> [-slot <slotId>] [-password <password>]
| 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. |
Demonstrates the retrieval of slot and token information.
java safenet.jcprov.sample.GetInfo {-info | -slot [<slotId>] | -token [<slotId>]}
| 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. |
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 HSM
java ...Threading -numThreads <numthreads> -keyName <keyname> -locking { none | os | functions } [-v]
| 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. |
The JCPROV API is documented in a series of javadocs. The documentation is located in the <jcprov_installation_directory>/javadocs directory.