Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| IAIK PKCS#11 Wrapper version 1.2.16
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## iaik.pkcs.pkcs11
Class Module

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

public class Module
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 cotains 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.

See Also:
  `Info`, `Slot`
Invariants
  (pkcs11Module_ <> null)

Nested Class Summary
`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.

Field Summary
`protected PKCS11` | `pkcs11Module_` Interface to the underlying PKCS#11 module.

Constructor Summary
`protected` | `Module(PKCS11 pkcs11Module)` Create a new module the uses the given PKCS11 interface to interact with the token.

Method Summary
`boolean` | `equals(Object otherObject)` Compares the pkcs11Module_ this object with the other object.
`void` | `finalize()` This finalize method tries to finalize the module by calling `finalize()` of the Java object of the PKCS11 module.
`void` | `finalize(Object args)` Finalizes this module.
`Info` | `getInfo()` Gets information about the module; i.e. the PKCS#11 module behind.
`static Module` | `getInstance(String pkcs11ModuleName)` 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. a list of PC/SC smart card readers.
`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.
`Slot` | `waitForSlotEvent(boolean dontBlock, Object reserved)` Waits for an slot event.

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

Field Detail

### pkcs11Module_

    protected PKCS11 pkcs11Module_

  Interface to the underlying PKCS#11 module.

Constructor Detail

### Module

    protected Module(PKCS11 pkcs11Module)

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

Parameters:
  `pkcs11Module` - The interface to interact with the token.
Preconditions
Postconditions

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.
  Preconditions
    (pkcs11ModuleName <> null) and (pkcs11ModuleName is a valid PKCS#11 module name)
  Postconditions

### 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.
  Preconditions
  Postconditions
    (result <> null)

### 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.
  Preconditions
  Postconditions

### finalize

    public void finalize(Object args)
                  throws TokenException

  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:
    `TokenException` - If finalization fails.
  Preconditions
    (args == null)
  Postconditions

### 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 .
  Preconditions
  Postconditions
    (result <> null)

### waitForSlotEvent

    public Slot waitForSlotEvent(boolean dontBlock,
                                 Object reserved)
                          throws TokenException

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

  Parameters:
    `dontBlock` - Can be WaitingBehavior.BLOCK or WaitingBehavior.DONT_BLOCK.
    `reserved` - Should be null for this version.
  Returns:
    The slot for which an event occured.
  Throws:
    `TokenException` - If the method was called with WaitingBehavior.DONT_BLOCK but there was no event available, or if an error occured.
  Preconditions
    (reserved == null)
  Postconditions
    (result <> null)

### getPKCS11Module

    public PKCS11 getPKCS11Module()

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

  Returns:
    The PKCS#11 module behind this object.
  Preconditions
  Postconditions
    (result <> null)

### toString

    public String toString()

  Returns the string representation of this object.

  Returns:
    The string representation of object

### finalize

    public void finalize()
                  throws Throwable

  This finalize method tries to finalize the module by calling `finalize()` of the Java object of the PKCS11 module. Note that this method does not call the `finalize(Object)` (`C_Finalize(Objet)`) method of the PKCS11 module! This method is the reserved Java method called by the garbage collector. Don't get confused by the same name.

  Throws:
    `Throwable` - If finalization fails.
  See Also:
    `finalize(Object)`
  Preconditions
  Postconditions

### 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.

  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.
  Preconditions
  Postconditions

### hashCode

    public int hashCode()

  The overriding of this method should ensure that the objects of this class work correctly in a hashtable.

  Returns:
    The hash code of this object. Gained from the sessionHandle.
  Preconditions
  Postconditions

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| IAIK PKCS#11 Wrapper version 1.2.16
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

IAIK JavaSecurity Website http://jce.iaik.tugraz.at/
IAIK at Graz University of Technology, Austria, Europe
Copyright 2001-2002, IAIK, Graz University of Technology, Inffeldgasse 16a, 8010 Graz, Austria. All Rights Reserved.