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 Token

    java.lang.Object
      iaik.pkcs.pkcs11.Token

public class Token
extends Object

Objects of this class represent PKCS#11 tokens. The application can get information on the token, manage sessions and initialize the token. Notice that objects of this class can become valid at any time. This is, the user can remove the token at any time and any subsequent calls to the corresponding object will fail with an exception (e.g. an exception with the error code PKCS11Constants.CKR_DEVICE_REMOVED). First, the application may want to find out what cryptographic algorithms the token supports. Implementations of such algorithms on a token are called mechanisms in the context of PKCS#11. The code for this may look something like this.

       List supportedMechanisms = Arrays.asList(token.getMechanismList());

       // check, if the token supports the required mechanism
       if (!supportedMechanisms.contains(Mechanism.RSA_PKCS)) {
         System.out.print("This token does not support the RSA PKCS mechanism!");
         System.out.flush();
         System.exit(1);
       } else {
         MechanismInfo rsaMechanismInfo = token.getMechanismInfo(Mechanism.RSA_PKCS);
         // check, if the mechanism supports the required operation
         if (!rsaMechanismInfo.isDecrypt()) {
            System.out.print("This token does not support RSA decryption according to PKCS!");
            System.out.flush();
            System.exit(1);
         }
       }

Being sure that the token supports the required mechanism, the application can open a session. For example, it may call

      Session session = token.openSession(Token.SessionType.SERIAL_SESSION, Token.SessionReadWriteBehavior.RO_SESSION, null, null);

to open a simple read-only session.

See Also:
  `Mechanism`, `MechanismInfo`, `Session`, `TokenInfo`
Invariants
  (slot_ <> null)

Nested Class Summary
`static interface` | `Token.SessionReadWriteBehavior` This interface defines constants that specify the read/write behavior of a session.
`static interface` | `Token.SessionType` This interface defines constants for the type of session that should be opened upon a call to openSession.

Field Summary
`protected Slot` | `slot_` The reference to the slot.

Constructor Summary
`protected` | `Token(Slot slot)` The constructor that takes a reference to the module and the slot ID.

Method Summary
`void` | `closeAllSessions()` Close all open sessions of this token.
`boolean` | `equals(Object otherObject)` Compares the slot_ of this object with the other object.
`MechanismInfo` | `getMechanismInfo(Mechanism mechanism)` Get mor information about one supported mechanism.
`Mechanism[]` | `getMechanismList()` Get the list of mechanisms that this token supports.
`Slot` | `getSlot()` Get the slot that created this Token object.
`long` | `getTokenID()` Get the ID of this token.
`TokenInfo` | `getTokenInfo()` Get information about this token.
`int` | `hashCode()` The overriding of this method should ensure that the objects of this class work correctly in a hashtable.
`void` | `initToken(char[] pin, String label)` Initialize the token.
`Session` | `openSession(boolean serialSession, boolean rwSession, Object application, Notify notify)` Open a new session to perfom operations on this token.
`String` | `toString()` Returns the string representation of this object.

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

Field Detail

### slot_

    protected Slot slot_

  The reference to the slot.

Constructor Detail

### Token

    protected Token(Slot slot)

  The constructor that takes a reference to the module and the slot ID.

Parameters:
  `slot` - The reference to the slot.
Preconditions
  (module <> null)
Postconditions

Method Detail

### equals

    public boolean equals(Object otherObject)

  Compares the slot_ of this object with the other object. Returns only true, if those are equal in both objects.

  Parameters:
    `otherObject` - The other Token object.
  Returns:
    True, if other is an instance of Token and the slot_ member varialbe of both objects are equal. False, otherwise.
  Preconditions
  Postconditions

### getSlot

    public Slot getSlot()

  Get the slot that created this Token object.

  Returns:
    The slot of this token.
  Preconditions
  Postconditions

### getTokenID

    public long getTokenID()

  Get the ID of this token. This is the ID of the slot this token resides in.

  Returns:
    The ID of this token.
  Preconditions
  Postconditions

### getTokenInfo

    public TokenInfo getTokenInfo()
                           throws TokenException

  Get information about this token.

  Returns:
    An object containing information about this token.
  Throws:
    `TokenException` - If reading the information fails.
  Preconditions
  Postconditions
    (result <> null)

### getMechanismList

    public Mechanism[] getMechanismList()
                                 throws TokenException

  Get the list of mechanisms that this token supports. An application can use this method to determine, if this token supports the required mechanism.

  Returns:
    An array of Mechanism objects. Each describes a mechansim that this token can perform. This array may be empty but not null.
  Throws:
    `TokenException` - If reading the list of supported mechansisms fails.
  Preconditions
  Postconditions
    (result <> null)

### getMechanismInfo

    public MechanismInfo getMechanismInfo(Mechanism mechanism)
                                   throws TokenException

  Get mor information about one supported mechanism. The application can find out, e.g. if an algorithm supports the certain key length.

  Parameters:
    `mechanism` - A mechanism that is supported by this token.
  Returns:
    An information object about the concerned mechanism.
  Throws:
    `TokenException` - If reading the information fails, or if the mechansim is not supported by this token.
  Preconditions
    (mechanism <> null) and (getMechanismList() contains mechanism)
  Postconditions
    (result <> null)

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

### initToken

    public void initToken(char[] pin,
                          String label)
                   throws TokenException

  Initialize the token. Attention: any data on the token will be lost! An token must normally be initialized before its first use.

  Parameters:
    `pin` - If the token is not initialized yet, this PIN becomes the security officer (admin) PIN. If the token is already initialized, this PIN must be the correct security officer PIN of this token. Otherwise the operation will fail. If the token slot has build-in means to verify the user (e.g. a PIN-pad on the card reader), this parameter can be null.
    `label` - The label to give to the token. If this string is longer than 32 characters, it will be cut off at the end to be exactly 32 characters in length. If it is shorter than 32 characters, the label is filled up with the blank character (' ') to be exactly 32 characters in length.
  Throws:
    `TokenException` - If the initialization fails.
  Preconditions
  Postconditions

### openSession

    public Session openSession(boolean serialSession,
                               boolean rwSession,
                               Object application,
                               Notify notify)
                        throws TokenException

  Open a new session to perfom operations on this token. Notice that all session within one application (system process) have the same login state.

  Parameters:
    `serialSession` - Must be SessionType.SERIAL_SESSION. (For the sake of completeness)
    `rwSession` - Must be either SessionReadWriteBehavior.RO_SESSION for read-only sessions or SessionReadWriteBehavior.RW_SESSION for read-write sessions.
    `application` - Object to be supplied upon notify callback. May be null. (Not implemented yet!).
    `notify` - For notifications via callback. may be null. (Not implemented yet!)
  Returns:
    The newly opened session.
  Throws:
    `TokenException` - If the session could not be opened.
  Preconditions
    (serialSession == SessionType.SERIAL_SESSION)
  Postconditions
    (result <> null)

### closeAllSessions

    public void closeAllSessions()
                          throws TokenException

  Close all open sessions of this token. All subsequently opened session will be public sessions (i.e. not logged in) by default.

  Throws:
    `TokenException` - If closing all session fails.
  Preconditions
  Postconditions

### toString

    public String toString()

  Returns the string representation of this object.

  Returns:
    the string representation of this object

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.