org.xipki.pkcs11.wrapper

Class PKCS11Module

java.lang.Object

org.xipki.pkcs11.wrapper.PKCS11Module

public class PKCS11Module
extends Object

Objects of this class represent a PKCS#11 module. The application should create an instance by calling getInstance and passing the name of the PKCS#11 module of the desired token; e.g. "slbck.dll". The application must give the full path of the PKCS#11 module unless the module is in the system's search path or in the path of the java.library.path system property.

According to the specification, the application must call the initialize method before calling any other method of the module. This class contains slot and token management functions as defined by the PKCS#11 standard.

All applications using this library will contain the following code.

      PKCS11Module pkcs11Module = PKCS11Module.getInstance("cryptoki.dll");
      pkcs11Module.initialize();

      // ... work with the module

      pkcs11Module.finalize(null);
 

Instead of cryptoki.dll, the application will use the name of the PKCS#11 module of the installed crypto hardware. After the application initialized the module, it can get a list of all available slots. A slot is an object that represents a physical or logical device that can accept a cryptographic token; for instance, the card slot of a smart card reader. The application can call

 Slot[] slots = pkcs11Module.getSlotList(false);
 

to get a list of all available slots or

 Slot[] slotsWithToken = pkcs11Module.getSlotList(true);
 

to get a list of all those slots in which there is a currently a token present.

To wait for the insertion of a token, the application can use the waitForSlotEvent method. For example, the method call

 Slot eventSlot = pkcs11Module.waitForSlotEvent(true);
 

will block until an event for any slot of this module occurred. Usually such an event is the insertion of a token. However, the application should check if the event occurred in the slot of interest and if there is really a token present in the slot.

Author:

Karl Scheibelhofer (SIC), Lijun Liao (xipki)

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	PKCS11Module(PKCS11Implementation pkcs11) Create a new module that uses the given PKCS11 interface to interact with the token.

Method Summary

Modifier and Type	Method and Description
String	codeToName(PKCS11Constants.Category category, long code)
PKCS11Exception	convertException(PKCS11Exception e)
void	finalize(Object args) Finalizes this module.
long	genericToVendorCode(PKCS11Constants.Category category, long genericCode)
ModuleInfo	getInfo() Gets information about the module; i.e.
static PKCS11Module	getInstance(String pkcs11ModulePath) Get an instance of this class by giving the name of the PKCS#11 module; e.g.
PKCS11	getPKCS11Module() Gets the PKCS#11 module of the wrapper package behind this object.
Slot[]	getSlotList(boolean tokenPresent) Gets a list of slots that can accept tokens that are compatible with this module; e.g.
void	initialize() Initializes the module.
Long	nameToCode(PKCS11Constants.Category category, String name)
String	toString() Returns the string representation of this object.
long	vendorToGenericCode(PKCS11Constants.Category category, long vendorCode)
Slot	waitForSlotEvent(boolean dontBlock) Waits for a slot event.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

PKCS11Module

protected PKCS11Module(PKCS11Implementation pkcs11)

Create a new module that uses the given PKCS11 interface to interact with the token.

Parameters:

pkcs11 - The PKCS#11 module to interact with the token.

Method Detail

getInstance

public static PKCS11Module getInstance(String pkcs11ModulePath)
                                throws IOException

Get an instance of this class by giving the name of the PKCS#11 module; e.g. "slbck.dll". Tries to load the PKCS#11 wrapper native library from the class path (jar file) or library path.

Parameters:

pkcs11ModulePath - The path of the module; e.g. "/path/to/slbck.dll".

Returns:

An instance of Module that is connected to the given PKCS#11 module.

Throws:

IOException - If connecting to the named module fails.

getInfo

public ModuleInfo getInfo()
                   throws TokenException

Gets information about the module; i.e. the PKCS#11 module behind.

Returns:

An object holding information about the module.

Throws:

TokenException

initialize

public void initialize()
                throws PKCS11Exception

Initializes the module. The application must call this method before calling any other method of the module.

Throws:

PKCS11Exception - If initialization fails.

finalize

public void finalize(Object args)
              throws PKCS11Exception

Finalizes this module. The application should call this method when it finished using the module. Note that this method is different from the finalize method, which is the reserved Java method called by the garbage collector. This method calls the C_Finalize(Object) method of the underlying PKCS11 module.

Parameters:

args - Must be null in version 2.x of PKCS#11.

Throws:

PKCS11Exception - If finalization fails.

getSlotList

public Slot[] getSlotList(boolean tokenPresent)
                   throws PKCS11Exception

Gets a list of slots that can accept tokens that are compatible with this module; e.g. a list of PC/SC smart card readers. The parameter determines if the method returns all compatible slots or only those in which there is a compatible token present.

Parameters:

tokenPresent - Whether only slots with present token are returned.

Returns:

An array of Slot objects, may be an empty array but not null.

Throws:

PKCS11Exception - If error occurred.

waitForSlotEvent

public Slot waitForSlotEvent(boolean dontBlock)
                      throws PKCS11Exception

Waits for a slot event. That can be that a token was inserted or removed. It returns the Slot for which an event occurred. The dontBlock parameter can have the value false (BLOCK) or true (DONT_BLOCK). If there is no event present and the method is called with true this method throws an exception with the error code CKR_NO_EVENT (0x00000008).

Parameters:

dontBlock - Can false (BLOCK) or true (DONT_BLOCK).

Returns:

The slot for which an event occurred.

Throws:

PKCS11Exception - If the method was called with WaitingBehavior.DONT_BLOCK but there was no event available, or if an error occurred.

getPKCS11Module

public PKCS11 getPKCS11Module()

Gets the PKCS#11 module of the wrapper package behind this object.

Returns:

The PKCS#11 module behind this object.

genericToVendorCode

public long genericToVendorCode(PKCS11Constants.Category category,
                                long genericCode)

vendorToGenericCode

public long vendorToGenericCode(PKCS11Constants.Category category,
                                long vendorCode)

codeToName

public String codeToName(PKCS11Constants.Category category,
                         long code)

nameToCode

public Long nameToCode(PKCS11Constants.Category category,
                       String name)

toString

public String toString()

Returns the string representation of this object.

Overrides:

toString in class Object

Returns:

The string representation of object

convertException

public PKCS11Exception convertException(PKCS11Exception e)