Managing PKCS #11 tokens

The toolkit supports cryptographic operations with hardware tokens such as smart cards. This support is based on PKCS #11 version 3.0, the Cryptographic Token Interface Standard, also known as Cryptoki.

The Cryptoki API defines an interface between portable cryptographic devices, called cryptographic tokens, and software applications.

Installing the PKCS #11 library

Depending on the operating system of your computer, you would need one of the following PKCS #11 libraries distributed in the etjava_90_lib.zip file.

OS

Library path in etjava_90_lib.zip

Library configuration

Windows

etjava/lib/win/x64/JNIPKCS11_64.dll

Move this file to the %windir%\system32 folder on your computer.

Linux

etjava/lib/linux/X86_64/libJNIPKCS11_64.so

Move this file to the LD_LIBRARY_PATH of your computer.

You will also need the PKCS #11 library supplied by your smart card vendor.

Selecting the library

Create a connection to the PKCS #11 library.

PKCS11LibraryConnection pkcs11LC = new PKCS11LibraryConnection("c:\\Windows\\SysWOW64\\JNIPKCS11_64.dll");

Requesting user credentials

Prompt for the user password, the security officer PIN, the authorization code, and the reference number.

SecureStringBuffer pwd = new SecureStringBuffer(new StringBuffer("userInitPwd"));
SecureStringBuffer soPin = new SecureStringBuffer(new StringBuffer("secOffPin"));
AuthorizationCode authCode =new AuthorizationCode(new StringBuffer(<authorization_code>));
SecureStringBuffer refNumber = new SecureStringBuffer(new StringBuffer(<reference_number>));

Getting slot identifiers

Create a PKCS11InformationObject and retrieve information about the available slot IDs.

PKCS11Information pkcs11Information = new PKCS11Information(pkcs11LC);
SlotList slotList = pkcs11Information.getSlotList(true);
long[] slotListIDs = slotList.getSlotListIDs();

Initializing the token creator

Create and instantiate the token creator.

TokenCredentialCreator tcc = new TokenCredentialCreator(refNumber, authCode, slotListIDs[0], pkcs11LC, soPin, "Token Test");

Creating a user

Create a user object.

com.entrust.toolkit.User user = new User();

Connecting to the key management server

Connect to the CA key management server and the Directory, specifying IP addresses and port numbers for both entities.

ManagerTransport mt = new ManagerTransport(<ip>, <port>);
JNDIDirectory jndiDir = new JNDIDirectory(<ip>, <port>);
user.setConnections(jndiDir, mt);

The default timers are set to 0 (no limit). This can cause long wait times if your environment has network-related issues. Use the setters to set reasonable timer values for your network.

Setting the auxiliary profile

Specify the path to the auxiliary profile and a name for the auxiliary profile.

String entrustPath = <profile_path>;
String auxProfName = <auxiliary profile name>;

Initializing the token writer

Instantiate and set a token writer as the credential writer.

TokenWriter tw = new TokenWriter(entrustPath, auxProfName, null, 0);
user.setCredentialWriter(tw);

Logging the user

Log in the user to create the new set of credentials.

user.login(tcc, pwd);

Performing cryptographic operations

Perform encryption and decryption operations.

Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
String data = "Test string.";
cipher.init(Cipher.ENCRYPT_MODE,
user.getEncryptionCertificate().getPublicKey());
byte[] encryptedData = cipher.doFinal(data.getBytes());
cipher.init(Cipher.DECRYPT_MODE, user.getDecryptionKey());
String decryptedData = new String(cipher.doFinal(encryptedData));
System.out.println("Decrypted data: " + decryptedData);

Perform signing and verification operations.

Signature signer = Signature.getInstance("SHA256/RSA");
signer.initSign(user.getSigningKey());
signer.update(data.getBytes());
byte[] signature = signer.sign();
X509Certificate verCert = user.getVerificationCertificate();
signer.initVerify(verCert.getPublicKey());
signer.update(data.getBytes());
boolean test = signer.verify(signature);
if(test)
{
System.out.println("Verification successful!");
}

Logging out the user

Log out and close the connection to the token library.

user.logout();
pkcs11LC.closeConnection();