IAIK PKCS#11 Provider API Documentation
version 1.6

iaik.pkcs.pkcs11.provider
Class TokenManager

java.lang.Object
  extended by iaik.pkcs.pkcs11.provider.TokenManager

public class TokenManager
extends java.lang.Object

One token manager instance is bound to exactly one PKCS#11 slot. This slot is fixed and cannot be changed. It manages the token in this slot, if there is a token present. Token management includes initialization of the PKCS#11 module, and session management (open, login, close, pool). It provides access to the slot it manages, any currently present token and a key store representation of the currently present token. Normally, the application should not need to access this class directly. This is only necessary in very special cases.

Author:
Karl Scheibelhofer
Invariants
(myProvider_ <> null) and (pkcs11ModulePath_ <> null) and (pkcs11module_ <> null) and (slot_ <> null) and (loginLock_ <> null)

Constructor Summary
TokenManager(IAIKPkcs11 myProvider)
          Create and initialize this token manager.
 
Method Summary
 void acquireSessionCloseLock(iaik.pkcs.pkcs11.Session session)
          Acquires a lock on this session which prevents that this token manager will close this session.
 void clearSessionPool(boolean tryToCloseSessions)
          Clears the internal session pool of this token manager.
 void closeSession(iaik.pkcs.pkcs11.Session session)
          This method closes the given session and does not put it in the session pool.
 void closeSessions()
          Close all sessions managed by this provider instance.
 void disposeSession(iaik.pkcs.pkcs11.Session session)
          Dispose the given session that is no longer used.
 void finalize()
          Try to finalize the underlying PKCS#11 module if there is no other token manager that uses the same module.
static TokenManager getDefaultTokenManager()
          Gets the token manager of the first registered pkcs11 provider.
 TokenKeyStore getKeyStore()
          Get a key store that is associated with the slot of this token manager.
 TokenKeyStore getKeyStore(java.lang.String keyStoreName)
          Get a key store that is associated with the slot of this token manager.
 iaik.pkcs.pkcs11.Module getModule()
          Get the PKCS#11 module of this token manager.
 java.lang.String getModulePath()
          Get the PKCS#11 module path of this token manager.
 IAIKPkcs11 getProvider()
          Get the provider of this token manager.
 iaik.pkcs.pkcs11.Session getSession(boolean rwBahavior)
          Get a session with the given read-write behavior.
 iaik.pkcs.pkcs11.Session getSession(boolean rwBahavior, boolean forSessionKey)
          Get a session with the given read-write behavior.
 iaik.pkcs.pkcs11.Slot getSlot()
          Get the slot of this token manager.
 iaik.pkcs.pkcs11.Token getToken()
          Get the token that is in the slot of this token manager.
 boolean isMechanismFeatureSupported(iaik.pkcs.pkcs11.Mechanism[] mechanisms, iaik.pkcs.pkcs11.MechanismInfo[][] mechanismFeatures)
          Check, if the current token supports one of the given mechanism and the given features of this mechanism.
 boolean isMechanismFeatureSupported(iaik.pkcs.pkcs11.Mechanism mechanism, iaik.pkcs.pkcs11.MechanismInfo mechanismFeatures)
          Check, if the current token supports the given mechanism and the given features of this mechanism.
 boolean isRemovable()
          This method returns true if the slot of this token manager is a slot with a removable token.
 boolean isSessionCloseLocked(iaik.pkcs.pkcs11.Session session)
          Check, if the given session is close-locked; i.e. if it must not be closed.
 boolean isTokenPresent()
          Check, if there is a token present in the slot of this token manager.
 boolean login(boolean SORole, char[] PIN)
          Login.
 boolean login(iaik.pkcs.pkcs11.Session session, boolean SORole, char[] PIN)
          Login the user into the given session.
 boolean loginSO(char[] PIN)
          Open a read-only user session and login as SO.
 boolean loginUser(char[] PIN)
          Open a read-only user session and login the user.
 void logout()
          Log out the current user (user or SO).
 void logout(iaik.pkcs.pkcs11.Session session)
          Deprecated.  
 boolean makeAuthorizedSession(iaik.pkcs.pkcs11.Session session, boolean SORole, char[] PIN)
          Make the given session authorized.
 boolean makeAuthorizedSession(iaik.pkcs.pkcs11.Session session, char[] PIN)
          Make the given session authorized.
 void notifyKeyStores()
          Notify all key store which use this token manager that they should refresh their contents.
 void releaseSessionCloseLock(iaik.pkcs.pkcs11.Session session)
          Releases a previously acquired close-lock for the given session.
 void setUserPIN(iaik.pkcs.pkcs11.Session session, char[] oldUserPIN, char[] newUserPIN)
          Set or change the user PIN of the token.
 java.lang.String toString()
          Returns a string with the name and the version number of this provider.
 void waitForSlotEvent()
          This method blocks until an event for the slot of this token manager occurs.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

TokenManager

public TokenManager(IAIKPkcs11 myProvider)
             throws java.io.IOException,
                    iaik.pkcs.pkcs11.TokenException,
                    IAIKPkcs11Exception
Create and initialize this token manager. Specify the provider it should get its configuration from and work with.

Parameters:
myProvider - The provider to get the configuration from.
Throws:
java.io.IOException - If loading the module fails.
iaik.pkcs.pkcs11.TokenException - If investigating the slots fails.
IAIKPkcs11Exception - If the configured module is unavailable.
Preconditions
(myProvider <> null)
Method Detail

clearSessionPool

public void clearSessionPool(boolean tryToCloseSessions)
Clears the internal session pool of this token manager. If tries to close each session before throwing them away.

Parameters:
tryToCloseSessions - If true, the method tries to close each session in the pool before throwing the object away.

disposeSession

public void disposeSession(iaik.pkcs.pkcs11.Session session)
Dispose the given session that is no longer used. This method tries to put the session in the session pool. If the pool is full, the session will be closed unless there is close-lock on this session; e.g. because there exists a session key which would be destroyed if the session is closed. In this case, this method does not close the session but remembers it for later closing when the close-lock gets released.

Parameters:
session - The session to dispose.

closeSession

public void closeSession(iaik.pkcs.pkcs11.Session session)
This method closes the given session and does not put it in the session pool. If there is a close-lock on this session, this method marks the session as to-be-closed. The marked session will be closed automatically when the close-lock is released. This features is used for session keys to avoid that they are destroyed while the key is still in use.

Parameters:
session - The session to close.

getKeyStore

public TokenKeyStore getKeyStore()
Get a key store that is associated with the slot of this token manager. If there is a token in the slot, this key store will hold keys and certificates corresponding to those on the token. If there is currently no token in the slot, the returned key store will be empty. However, the key store's contents will update automatically.

Returns:
The key store associated with the slot of this token manager.
Postconditions
(result <> null)

getKeyStore

public TokenKeyStore getKeyStore(java.lang.String keyStoreName)
Get a key store that is associated with the slot of this token manager. If there is a token in the slot, this key store will hold keys and certificates corresponding to those on the token. If there is currently no token in the slot, the returned key store will be empty. However, the key store's contents will update automatically.

Parameters:
keyStoreName - name of the keystore to create (e.g. PKCS11 for standard keystore, FastPKCS11 for fastPKCS11Keystore)
Returns:
The key store associated with the slot of this token manager.
Postconditions
(result <> null)

getModule

public iaik.pkcs.pkcs11.Module getModule()
Get the PKCS#11 module of this token manager.

Returns:
The PKCS#11 module of this manager.
Postconditions
(result <> null)

getModulePath

public java.lang.String getModulePath()
Get the PKCS#11 module path of this token manager.

Returns:
The PKCS#11 module path of this manager.
Postconditions
(result <> null)

getProvider

public IAIKPkcs11 getProvider()
Get the provider of this token manager.

Returns:
The provider this manager gets its configuration from.
Postconditions
(result <> null)

getSession

public iaik.pkcs.pkcs11.Session getSession(boolean rwBahavior)
                                    throws iaik.pkcs.pkcs11.TokenException,
                                           IAIKPkcs11TokenUnavailableException
Get a session with the given read-write behavior.

Parameters:
rwBahavior - Must be either Token.SessionReadWriteBehavior.RO_SESSION for read-only sessions or Token.SessionReadWriteBehavior.RW_SESSION for read-write sessions.
Returns:
An appropriate session object.
Throws:
iaik.pkcs.pkcs11.TokenException - If getting such a session fails.
IAIKPkcs11TokenUnavailableException - If there is no token in the slot.
Postconditions
(result <> null)

getSession

public iaik.pkcs.pkcs11.Session getSession(boolean rwBahavior,
                                           boolean forSessionKey)
                                    throws iaik.pkcs.pkcs11.TokenException,
                                           IAIKPkcs11TokenUnavailableException
Get a session with the given read-write behavior.
This method allows to specify that the requested session is intended for the creation or generation of a session key. Knowledge of this fact allows for a better session management.

Parameters:
rwBahavior - Must be either Token.SessionReadWriteBehavior.RO_SESSION for read-only sessions or Token.SessionReadWriteBehavior.RW_SESSION for read-write sessions.
forSessionKey - true signals that the requested session will be used for the creation or generation of a session key object.
Returns:
An appropriate session object.
Throws:
iaik.pkcs.pkcs11.TokenException - If getting such a session fails.
IAIKPkcs11TokenUnavailableException - If there is no token in the slot.
Postconditions
(result <> null)

getSlot

public iaik.pkcs.pkcs11.Slot getSlot()
Get the slot of this token manager.

Returns:
The slot of this manager.
Postconditions
(result <> null)

getToken

public iaik.pkcs.pkcs11.Token getToken()
                                throws iaik.pkcs.pkcs11.TokenException
Get the token that is in the slot of this token manager.

Returns:
The token that is currently in the slot of this manager or null if there is no token in the slot.
Throws:
iaik.pkcs.pkcs11.TokenException - If getting the token object fails.

acquireSessionCloseLock

public void acquireSessionCloseLock(iaik.pkcs.pkcs11.Session session)
Acquires a lock on this session which prevents that this token manager will close this session. This is used by session keys to ensure that the session remains open as long as the key is used. Closing such a session would cause the session key to be destroyed. This method can be called several times for the same session. This manager keeps a lock counter for each locked session. Thus, the release method must be called as often as the acquire method to actually release the lock on a session.

Parameters:
session - The session to acquire a lock.
Preconditions
(session <> null)

releaseSessionCloseLock

public void releaseSessionCloseLock(iaik.pkcs.pkcs11.Session session)
Releases a previously acquired close-lock for the given session. This method can be called several times for the same session. This manager keeps a lock counter for each locked session. Thus, the release method must be called as often as the acquire method to actually release the lock on a session. For sessions for which are not close-locked, this method does nothing.

Parameters:
session - The session to release the lock.
Preconditions
(session <> null)

isSessionCloseLocked

public boolean isSessionCloseLocked(iaik.pkcs.pkcs11.Session session)
Check, if the given session is close-locked; i.e. if it must not be closed.

Parameters:
session - The session to release the lock.
Returns:
True, if the session is close-locked. False, if it is not.
Preconditions
(session <> null)

isMechanismFeatureSupported

public boolean isMechanismFeatureSupported(iaik.pkcs.pkcs11.Mechanism mechanism,
                                           iaik.pkcs.pkcs11.MechanismInfo mechanismFeatures)
                                    throws iaik.pkcs.pkcs11.TokenException
Check, if the current token supports the given mechanism and the given features of this mechanism. If there is no token present, this method always returns false.

Parameters:
mechanism - The requested mechanism.
mechanismFeatures - The requested features of the mechanism. This is optional and may be null. In this case, the method just checks the mechanism itself.
Returns:
True, if the mechanism is supported by the current token and can be used with the given mechanism features. False, if the token does not support the given mechanism with the given features, of if there is no token present.
Throws:
iaik.pkcs.pkcs11.TokenException - If getting the mechanism infos failed.
Preconditions
(mechanism <> null)

isMechanismFeatureSupported

public boolean isMechanismFeatureSupported(iaik.pkcs.pkcs11.Mechanism[] mechanisms,
                                           iaik.pkcs.pkcs11.MechanismInfo[][] mechanismFeatures)
                                    throws iaik.pkcs.pkcs11.TokenException
Check, if the current token supports one of the given mechanism and the given features of this mechanism. If there is no token present, this method always returns false.

Parameters:
mechanisms - The mechanisms of which at least one must be supported.
mechanismFeatures - The requested features of the mechanisms. The first-dimension length of this parameter must be the same as the length of the mechanisms parameter. The arrays at each index may be null. In this case, the method just checks the mechanism itself.
Returns:
True, if the current token and supports at least one mechanism and supports at least on of the feature combinations of the same mechanism. False, if the token does not support one of the given mechanisms with one of the feature combination of this mechanism, or if there is no token present.
Throws:
iaik.pkcs.pkcs11.TokenException - If getting the mechanism infos failed.
Preconditions
(mechanisms <> null) (mechanismFeatures <> null) (mechanisms.length == mechanismFeatures.length)

isRemovable

public boolean isRemovable()
This method returns true if the slot of this token manager is a slot with a removable token. For smart cards reader, this is usually true. HSMs often have slots with fixed tokens which cannot be removed. In this case, this method returns false, meaning that the token is always present in the slot. This information may be useful for certain applications.

Returns:
true if the token in this slot is removable; e.g. if it is a smart card in a card reader. false if the token is fixed in the slot and cannot be removed during runtime; e.g. a token of a HSM.

isTokenPresent

public boolean isTokenPresent()
                       throws iaik.pkcs.pkcs11.TokenException
Check, if there is a token present in the slot of this token manager.

Returns:
True, if there is a token present in the slot of this token manager, false otherwise.
Throws:
iaik.pkcs.pkcs11.TokenException - If getting the slot info fails.

loginUser

public boolean loginUser(char[] PIN)
                  throws iaik.pkcs.pkcs11.TokenException,
                         IAIKPkcs11AuthenticationCanceledException,
                         IAIKPkcs11AuthenticationException
Open a read-only user session and login the user. According to PKCS#11 all other parallel session also get logged in. This method uses the prompt object given by its provider's getPassphrasePrompt() method to prompt the PIN from the user. It gets additional configuration information like the number of allowed retries from the provider (To be changed to get it from PKCS#11).

Parameters:
PIN - The user PIN if already known, or null if unavailable.
Returns:
true, if this call did actually call the login method of the underlying PKCS#11 module, false, if the user was already logged in and a call to the login method was not required.
Throws:
iaik.pkcs.pkcs11.TokenException - If token or session handling fails.
IAIKPkcs11AuthenticationCanceledException - If user canceled the PIN entry.
IAIKPkcs11AuthenticationException - If the authentication failed.

loginSO

public boolean loginSO(char[] PIN)
                throws iaik.pkcs.pkcs11.TokenException,
                       IAIKPkcs11AuthenticationCanceledException,
                       IAIKPkcs11AuthenticationException
Open a read-only user session and login as SO. According to PKCS#11 all other parallel session also get logged in. This method uses the prompt object given by its provider's getPassphrasePrompt() method to prompt the PIN from the user. It gets additional configuration information like the number of allowed retries from the provider (To be changed to get it from PKCS#11).

Parameters:
PIN - The PIN if already known, or null if unavailable.
Returns:
true, if this call did actually call the login method of the underlying PKCS#11 module, false, if the user was already logged in and a call to the login method was not required.
Throws:
iaik.pkcs.pkcs11.TokenException - If token or session handling fails.
IAIKPkcs11AuthenticationCanceledException - If user canceled the PIN entry.
IAIKPkcs11AuthenticationException - If the authentication failed.

login

public boolean login(boolean SORole,
                     char[] PIN)
              throws iaik.pkcs.pkcs11.TokenException,
                     IAIKPkcs11AuthenticationCanceledException,
                     IAIKPkcs11AuthenticationException
Login. According to PKCS#11 all parallel session get logged in. This method uses the prompt object given by its provider's getPassphrasePrompt() method to prompt the PIN from the user. It gets additional configuration information like the number of allowed retries from the provider (To be changed to get it from PKCS#11).

If the session has already been logged in, this method will not try to login the session again and return false.

Parameters:
SORole - Whether or not to login as Security Officer (SO)
PIN - The user PIN if already known, or null if unavailable.
Returns:
true, if this call did actually call the login method of the underlying PKCS#11 module, false, if the user was already logged in and a call to the login method was not required.
Throws:
iaik.pkcs.pkcs11.TokenException - If token or session handling fails.
IAIKPkcs11AuthenticationCanceledException - If user canceled the PIN entry.
IAIKPkcs11AuthenticationException - If the authentication failed.

login

public boolean login(iaik.pkcs.pkcs11.Session session,
                     boolean SORole,
                     char[] PIN)
              throws iaik.pkcs.pkcs11.TokenException,
                     IAIKPkcs11AuthenticationCanceledException,
                     IAIKPkcs11AuthenticationException
Login the user into the given session. According to PKCS#11 all other parallel session also get logged in. This method uses the prompt object given by its provider's getPassphrasePrompt() method to prompt the PIN from the user. It gets additional configuration information like the number of allowed retries from the provider (To be changed to get it from PKCS#11).

If the session has already been logged in, this method will not try to login the session again and return false.

Parameters:
session - The session to login. If the session is null, this method will open a read-only user session.
SORole - Whether or not to login as Security Officer (SO)
PIN - The user PIN if already known, or null if unavailable.
Returns:
true, if this call did actually call the login method of the underlying PKCS#11 module, false, if the user was already logged in and a call to the login method was not required.
Throws:
iaik.pkcs.pkcs11.TokenException - If token or session handling fails.
IAIKPkcs11AuthenticationCanceledException - If user canceled the PIN entry.
IAIKPkcs11AuthenticationException - If the authentication failed.

logout

public void logout()
            throws iaik.pkcs.pkcs11.TokenException
Log out the current user (user or SO). Attention: any session operating on this token will be logged out, because all sessions for a token have the same login state.

Throws:
iaik.pkcs.pkcs11.TokenException - If logout fails.

logout

public void logout(iaik.pkcs.pkcs11.Session session)
            throws iaik.pkcs.pkcs11.TokenException
Deprecated. 

Log out the current user (user or SO) from the given session. Attention: any other session operating on this token will also be logged out, because all sessions for a token have the same login state.
If the given session is null, the configured login manager may acquire a suitable session for logout.

Parameters:
session - The session to logout or null to just logout from the token using any session.
Throws:
iaik.pkcs.pkcs11.TokenException - If logout fails.

setUserPIN

public void setUserPIN(iaik.pkcs.pkcs11.Session session,
                       char[] oldUserPIN,
                       char[] newUserPIN)
                throws iaik.pkcs.pkcs11.TokenException,
                       IAIKPkcs11AuthenticationCanceledException,
                       IAIKPkcs11AuthenticationException
Set or change the user PIN of the token. This method uses the currently set handler for prompting the new user PIN. This handler can be set in the attached provider instance.

Parameters:
session - The session to use for setting the PIN. If this is null, the method will open a read-write use session.
oldUserPIN - The old (current) user PIN if already known, or null if unavailable.
newUserPIN - The new user PIN if already known, or null if unavailable.
Throws:
iaik.pkcs.pkcs11.TokenException - If changing the PIN fails.
IAIKPkcs11AuthenticationCanceledException - If the user PIN has to be prompted and the user canceled the PIN entry.
IAIKPkcs11AuthenticationException - If PIN verification failed.
See Also:
LoginManager.setUserPIN(TokenManager, Session, char[], char[])

makeAuthorizedSession

public boolean makeAuthorizedSession(iaik.pkcs.pkcs11.Session session,
                                     char[] PIN)
                              throws iaik.pkcs.pkcs11.TokenException,
                                     IAIKPkcs11TokenUnavailableException,
                                     IAIKPkcs11AuthenticationException
Make the given session authorized. This means login the user, if a login is required by the token and the session is not already logged in.

Parameters:
session - The session to login, if a login is required.
PIN - The user PIN if already known, or null is unavailable.
Returns:
true, if this call did actually call the login method of the underlying PKCS#11 module, false, if the user was already logged in or a login is not required by the token.
Throws:
iaik.pkcs.pkcs11.TokenException - If disposing the session fails.
IAIKPkcs11TokenUnavailableException - If the token is unavailable
IAIKPkcs11AuthenticationException - If authenticating the user failed.

makeAuthorizedSession

public boolean makeAuthorizedSession(iaik.pkcs.pkcs11.Session session,
                                     boolean SORole,
                                     char[] PIN)
                              throws iaik.pkcs.pkcs11.TokenException,
                                     IAIKPkcs11TokenUnavailableException,
                                     IAIKPkcs11AuthenticationException
Make the given session authorized. This means login the user, if a login is required by the token and the session is not already logged in.

Parameters:
session - The session to login, if a login is required.
PIN - The user PIN if already known, or null is unavailable.
Returns:
true, if this call did actually call the login method of the underlying PKCS#11 module, false, if the user was already logged in or a login is not required by the token.
Throws:
iaik.pkcs.pkcs11.TokenException - If disposing the session fails.
IAIKPkcs11TokenUnavailableException - If the token is unavailable
IAIKPkcs11AuthenticationException - If authenticating the user failed.

waitForSlotEvent

public void waitForSlotEvent()
                      throws iaik.pkcs.pkcs11.TokenException
This method blocks until an event for the slot of this token manager occurs.

Throws:
iaik.pkcs.pkcs11.TokenException - If waiting for an event fails.

notifyKeyStores

public void notifyKeyStores()
Notify all key store which use this token manager that they should refresh their contents. This may be due to a login/logout operation which may alter the list of accessible objects or may change object handles.


toString

public java.lang.String toString()
Returns a string with the name and the version number of this provider.

Overrides:
toString in class java.lang.Object
Returns:
the string with the name and the version number for this provider.

finalize

public void finalize()
              throws java.lang.Throwable
Try to finalize the underlying PKCS#11 module if there is no other token manager that uses the same module.

Overrides:
finalize in class java.lang.Object
Throws:
java.lang.Throwable - If anything fails. Caught by VM.

closeSessions

public void closeSessions()
Close all sessions managed by this provider instance.


getDefaultTokenManager

public static TokenManager getDefaultTokenManager()
Gets the token manager of the first registered pkcs11 provider.

Returns:
the default token manager

IAIK PKCS#11 Provider API Documentation
version 1.6

IAIK JavaSecurity Website http://jce.iaik.tugraz.at/

IAIK at Graz University of Technology, Austria, Europe
Copyright 2001-2004, IAIK, Graz University of Technology, Inffeldgasse 16a, 8010 Graz, Austria. All Rights Reserved.
version 1.6