Package org.xipki.pkcs11.wrapper

Class 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 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. 
    
   long[] supportedMechanisms = token.getMechanismList();

   // check, if the token supports the required mechanism
   if (!contains(supportedMechanisms, CKM_RSA_PKCS)) {
     System.out.print("This token does not support the RSA PKCS mechanism!");
     System.out.flush();
     throw new PKCS11Exception("RSA not supported!");
   } else {
     MechanismInfo rsaMechanismInfo = token.getMechanismInfo(CKM_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 PKCS11Exception("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(readWrite);
    to open a read-only session for readWrite = false, or a read-write session if readWrite = true.
    Author:
    Karl Scheibelhofer (SIC), Lijun Liao (xipki)

    • 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

      • 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 PKCS11Exception
        Get information about this token.
        Returns:
        An object containing information about this token.
        Throws:
        PKCS11Exception - If reading the information fails.

      • getMechanismList

        public long[] getMechanismList()
                        throws PKCS11Exception
        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:
        PKCS11Exception - If reading the list of supported mechanisms fails.

      • getMechanismInfo

        public MechanismInfo getMechanismInfo​(long mechanism)
                               throws PKCS11Exception
        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:
        PKCS11Exception - If reading the information fails, or if the mechanism is not supported by this token.

      • openSession

        public Session openSession​(boolean rwSession)
                    throws PKCS11Exception
        Open a new session to perform operations on this token. Notice that all sessions within one application (system process) have the same login state.
        Parameters:
        rwSession - Must be either SessionReadWriteBehavior.RO_SESSION for read-only sessions or SessionReadWriteBehavior.RW_SESSION for read-write sessions.
        Returns:
        The newly opened session.
        Throws:
        PKCS11Exception - If the session could not be opened.

      • openSession

        public Session openSession​(boolean rwSession,
                           Object application)
                    throws PKCS11Exception
        Open a new session to perform operations on this token. Notice that all sessions within one application (system process) have the same login state.
        Parameters:
        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!).
        Returns:
        The newly opened session.
        Throws:
        PKCS11Exception - 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