Module (PKCS#11 wrapper 1.4.7 API)

java.lang.Object
- iaik.pkcs.pkcs11.Module

```
public class Module
extends Object
```
Caution: Unlike the original PKCS#11 wrapper, we only call initialize() once per native .so/.dll. Once finalize(Object) has been called, the module cannot be initialized anymore.
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.
```
      Module pkcs11Module = Module.getInstance("cryptoki.dll");
      pkcs11Module.initialize(null);

      // ... 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(Module.SlotRequirement.ALL_SLOTS);
 
```
to get a list of all available slots or
```
 Slot[] slotsWithToken = pkcs11Module.getSlotList(
                             Module.SlotRequirement.TOKEN_PRESENT);
 
```
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(
                      Module.WaitingBehavior.DONT_BLOCK, null);
 
```
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.
Version:

1.0

Author:

Karl Scheibelhofer

See Also:

Info, Slot

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`Module.SlotRequirement` This interface defines the required properties for a slot.
`static interface`	`Module.WaitingBehavior` This interface defines the allowed constants for the wanted waiting behavior when calling waitForSlotEvent.

Constructor Summary

Constructors
Constructor and Description

Module(String pkcs11ModuleName)
Create a new module that uses the given PKCS11 interface to interact with the token.

Constructors
Constructor and Description
`Module(String pkcs11ModuleName)` Create a new module that uses the given PKCS11 interface to interact with the token.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`equals(Object otherObject)` Compares the pkcs11Module_ this object with the other object.
`void`	`finalize(Object args)` Caution: Unlike the original PKCS#11 wrapper, we only call initialize() once per native .so/.dll.
`Info`	`getInfo()` Gets information about the module; i.e.
`static Module`	`getInstance(String pkcs11ModuleName)` Get an instance of this class by giving the name of the PKCS#11 module; e.g.
`sun.security.pkcs11.wrapper.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.
`int`	`hashCode()` The overriding of this method should ensure that the objects of this class work correctly in a hashtable.
`void`	`initialize(InitializeArgs initArgs)` Initializes the module.
`String`	`toString()` Returns the string representation of this object.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - Module
```
public Module(String pkcs11ModuleName)
```
    Create a new module that uses the given PKCS11 interface to interact with the token.
    
    Parameters:
    
    pkcs11ModuleName - The interface to interact with the token.
- Method Detail
  - getInstance
```
public static Module getInstance(String pkcs11ModuleName)
                          throws IOException
```
    Get an instance of this class by giving the name of the PKCS#11 module; e.g. "slbck.dll".
    
    Parameters:
    
    pkcs11ModuleName - The name of the module; e.g. "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 Info getInfo()
             throws TokenException
```
    Gets information about the module; i.e. the PKCS#11 module behind.
    
    Returns:
    
    A object holding information about the module.
    
    Throws:
    
    TokenException - If getting the information fails.
  - initialize
```
public void initialize(InitializeArgs initArgs)
                throws TokenException
```
    Initializes the module. The application must call this method before calling any other method of the module.
    
    Parameters:
    
    initArgs - The initialization arguments for the module as defined in PKCS#11. May be null.
    
    Throws:
    
    TokenException - If initialization fails.
  - getSlotList
```
public Slot[] getSlotList(boolean tokenPresent)
                   throws TokenException
```
    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 - Can be SlotRequirement.ALL_SLOTS or SlotRequirement.TOKEN_PRESENT.
    
    Returns:
    
    An array of Slot objects. May be an empty array but not null.
    
    Throws:
    
    TokenException - If .
  - getPKCS11Module
```
public sun.security.pkcs11.wrapper.PKCS11 getPKCS11Module()
```
    Gets the PKCS#11 module of the wrapper package behind this object.
    
    Returns:
    
    The PKCS#11 module behind this object.
  - toString
```
public String toString()
```
    Returns the string representation of this object.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    The string representation of object
  - finalize
```
public void finalize(Object args)
              throws TokenException
```
    Caution: Unlike the original PKCS#11 wrapper, we only call initialize() once per native .so/.dll. Once finalize(Object) has been called, the module cannot be initialized anymore.
    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(PKCS11Object) method of the underlying PKCS11 module.
    
    Parameters:
    
    args - Must be null in version 2.x of PKCS#11.
    
    Throws:
    
    TokenException - If finalization fails.
  - equals
```
public boolean equals(Object otherObject)
```
    Compares the pkcs11Module_ this object with the other object. Returns only true, if those are equal in both objects.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    otherObject - The other Module object.
    
    Returns:
    
    True, if other is an instance of Module and the pkcs11Module_ of both objects are equal. False, otherwise.
  - hashCode
```
public int hashCode()
```
    The overriding of this method should ensure that the objects of this class work correctly in a hashtable.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    The hash code of this object. Gained from the sessionHandle.

Class Module

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Module

Method Detail

getInstance

getInfo

initialize

getSlotList

getPKCS11Module

toString

finalize

equals

hashCode