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();
     throw new TokenException("RSA not supported!");
   } 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();
        throw new TokenException("RSA signing not supported!");
     }
   }
 

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.

Version:

1.0

Author:

Karl Scheibelhofer

See Also:

Mechanism, MechanismInfo, Session, TokenInfo

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
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.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Token(Slot slot) The constructor that takes a reference to the module and the slot ID.

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object otherObject) Compares the slot of this object with the other object.
MechanismInfo	getMechanismInfo(Mechanism mechanism) Get more 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.
boolean	isUseUtf8Encoding()
Session	openSession(boolean serialSession, boolean rwSession, Object application, Notify notify) Open a new session to perform 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

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.

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.

Overrides:

equals in class Object

Parameters:

otherObject - The other Token object.

Returns:

True, if other is an instance of Token and the slot member variable of both objects are equal. False, otherwise.

getSlot

public Slot getSlot()

Get the slot that created this Token object.

Returns:

The slot of this token.

isUseUtf8Encoding

public boolean isUseUtf8Encoding()

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.

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.

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 mechanism that this token can perform. This array may be empty but not null.

Throws:

TokenException - If reading the list of supported mechanisms fails.

getMechanismInfo

public MechanismInfo getMechanismInfo(Mechanism mechanism)
                               throws TokenException

Get more 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 mechanism is not supported by this token.

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 slot ID.

openSession

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

Open a new session to perform 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 - PKCS11Object 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.

toString

public String toString()

Returns the string representation of this object.

Overrides:

toString in class Object

Returns:

the string representation of this object