TokenManager (IAIK PKCS#11 Provider API Documentation)

java.lang.Object
- 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)

Field Summary

Fields
Modifier and Type	Field and Description
`protected java.util.Set`	`activeSessions_` Holds the currently active sessions_.
`protected java.util.Set`	`keyStores_` This is a set of SoftReferences.
`protected java.util.LinkedList`	`lockedSessionROPool_` The pool of PKCS#11 read-only sessions for which there is a close lock.
`protected static java.lang.Object`	`moduleMapsLock_` This is used as synchronization lock for accessing the modules maps.
`protected static java.util.HashMap`	`modulesUsageCounterMap_` The keys are set of already loaded and initialized Modules, to avoid multiple calls to initialize of the same Module.
`protected IAIKPkcs11`	`myProvider_` Get the configuration from this provider.
`protected int`	`openedSessionsTotal_` This is the total number of session that this token manager opened (including any already closed sessions).
`protected int`	`openSessions_` This is the number of currently open sessions in general, not only those we have in our pool.
`protected iaik.pkcs.pkcs11.Module`	`pkcs11module_` Reference to the PKCS#11 module of the wrapper.
`protected java.lang.String`	`pkcs11ModulePath_` Path to the PKCS#11 driver; e.g.
`protected java.util.Map`	`sessionCloseLockCounts_` The sessions of session keys.
`protected int`	`sessionPoolMaxSize_` This is the maximum number of sessions to keep in to pool of open sessions.
`protected java.util.LinkedList`	`sessionROPool_` The pool of PKCS#11 read-only session objects.
`protected java.util.LinkedList`	`sessionRWPool_` The pool of PKCS#11 read-write session objects.
`protected int`	`sessionsInPool_` This is the number of sessions currently in our pool.
`protected java.util.Set`	`sessionsToBeClosed_` This set contains sessions that must be closed when they are no longer used; i.e.
`protected iaik.pkcs.pkcs11.Slot`	`slot_` Reference to the PKCS#11 slot this token manager works with.
`protected static java.util.HashMap`	`usedModulesMap_` A map that contains all modules in use.
`protected static java.util.HashMap`	`usedSlotsMap_` The map of slots already used by n token managers.

Constructor Summary

Constructors
Constructor and Description

TokenManager(IAIKPkcs11 myProvider)
Create and initialize this token manager.

Constructors
Constructor and Description
`TokenManager(IAIKPkcs11 myProvider)` Create and initialize this token manager.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`acquireSessionCloseLock(iaik.pkcs.pkcs11.Session session)` Acquires a lock on this session which prevents that this token manager will close this session.
`protected void`	`addKeyStoreReference(TokenKeyStoreSpi keyStore)` Notify this token manager that a new key store object has been created.
`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.
`protected void`	`closeSessionNow(iaik.pkcs.pkcs11.Session session)` This method definitely closes the given session unconditionally.
`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)`
`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.
`protected boolean`	`isToBeClosed(iaik.pkcs.pkcs11.Session session)` Check if the given session is to 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.
`protected void`	`setToBeClosed(iaik.pkcs.pkcs11.Session session)` Remember the given session to be closed.
`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
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - moduleMapsLock_
```
protected static final java.lang.Object moduleMapsLock_
```
    This is used as synchronization lock for accessing the modules maps.
  - usedModulesMap_
```
protected static final java.util.HashMap usedModulesMap_
```
    A map that contains all modules in use. The token manager uses this to ensure that it uses always the same module instance object to access one module.
  - modulesUsageCounterMap_
```
protected static final java.util.HashMap modulesUsageCounterMap_
```
    The keys are set of already loaded and initialized Modules, to avoid multiple calls to initialize of the same Module. The value it the Integer counter that tells how many token manager use the Module.
  - usedSlotsMap_
```
protected static final java.util.HashMap usedSlotsMap_
```
    The map of slots already used by n token managers. The map key is the Module, the value a map of Slot objects and number of token managers.
  - myProvider_
```
protected IAIKPkcs11 myProvider_
```
    Get the configuration from this provider.
  - pkcs11ModulePath_
```
protected java.lang.String pkcs11ModulePath_
```
    Path to the PKCS#11 driver; e.g. cryptoki.dll
  - pkcs11module_
```
protected iaik.pkcs.pkcs11.Module pkcs11module_
```
    Reference to the PKCS#11 module of the wrapper.
  - slot_
```
protected iaik.pkcs.pkcs11.Slot slot_
```
    Reference to the PKCS#11 slot this token manager works with.
  - activeSessions_
```
protected java.util.Set activeSessions_
```
    Holds the currently active sessions_.
  - sessionROPool_
```
protected java.util.LinkedList sessionROPool_
```
    The pool of PKCS#11 read-only session objects. We manage them to ensure optimal use of session objects. Tests showed that we cannot rely on finalize() methods to be called regularly to achieve session disposal. This is the pool of read-only sessions.
  - lockedSessionROPool_
```
protected java.util.LinkedList lockedSessionROPool_
```
    The pool of PKCS#11 read-only sessions for which there is a close lock. These sessions are used for the creation of sessions keys to keep the amount of close-locked sessions small.
  - sessionRWPool_
```
protected java.util.LinkedList sessionRWPool_
```
    The pool of PKCS#11 read-write session objects. We manage them to ensure optimal use of session objects. Tests showed that we cannot rely on finalize() methods to be called regularly to achieve session disposal. This is the pool of read-write sessions.
  - sessionPoolMaxSize_
```
protected int sessionPoolMaxSize_
```
    This is the maximum number of sessions to keep in to pool of open sessions. If engines return additional open sessions, we close and discard them.
  - openSessions_
```
protected int openSessions_
```
    This is the number of currently open sessions in general, not only those we have in our pool.
  - sessionsInPool_
```
protected int sessionsInPool_
```
    This is the number of sessions currently in our pool.
  - openedSessionsTotal_
```
protected int openedSessionsTotal_
```
    This is the total number of session that this token manager opened (including any already closed sessions). For debugging.
  - sessionCloseLockCounts_
```
protected java.util.Map sessionCloseLockCounts_
```
    The sessions of session keys. We must keep a reference counter for each session used by a session key to know when we can release it.
  - sessionsToBeClosed_
```
protected java.util.Set sessionsToBeClosed_
```
    This set contains sessions that must be closed when they are no longer used; i.e. when there is no more close-lock on them.
  - keyStores_
```
protected java.util.Set keyStores_
```
    This is a set of SoftReferences. Each of them refers to a TokenKeyStoreSpi object which uses this token manager. These references are used to notify the key stores about a logout, which enables them to refresh their contents. Access should be synchronized.
- 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.
  - closeSessionNow
```
protected void closeSessionNow(iaik.pkcs.pkcs11.Session session)
```
    This method definitely closes the given session unconditionally.
    
    Parameters:
    
    session - The session to dispose.
  - 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
```
    Throws:
    
    iaik.pkcs.pkcs11.TokenException
    
    IAIKPkcs11TokenUnavailableException
  - 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)
  - setToBeClosed
```
protected void setToBeClosed(iaik.pkcs.pkcs11.Session session)
```
    Remember the given session to be closed.
    
    Parameters:
    
    session - The session to remember.
    
    Preconditions:
    
    (session <> null)
  - isToBeClosed
```
protected boolean isToBeClosed(iaik.pkcs.pkcs11.Session session)
```
    Check if the given session is to be closed.
    
    Parameters:
    
    session - The session to check.
    
    Returns:
    
    True, if this session is to be closed.
    
    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.
  - addKeyStoreReference
```
protected void addKeyStoreReference(TokenKeyStoreSpi keyStore)
```
    Notify this token manager that a new key store object has been created. This method is for internal use.
    
    Parameters:
    
    keyStore - The new key store object.
    
    Preconditions:
    
    (keyStore <> null)
  - 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 JavaSecurity Website https://jce.iaik.tugraz.at/

IAIK at Graz University of Technology, Austria, Europe
Copyright 2001-2023 IAIK, Graz University of Technology, Inffeldgasse 16a, 8010 Graz, Austria. All Rights Reserved. Version 1.9.4

Class TokenManager

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

moduleMapsLock_

usedModulesMap_

modulesUsageCounterMap_

usedSlotsMap_

myProvider_

pkcs11ModulePath_

pkcs11module_

slot_

activeSessions_

sessionROPool_

lockedSessionROPool_

sessionRWPool_

sessionPoolMaxSize_

openSessions_

sessionsInPool_

openedSessionsTotal_

sessionCloseLockCounts_

sessionsToBeClosed_

keyStores_

Constructor Detail

TokenManager

Method Detail

clearSessionPool

disposeSession

closeSession

closeSessionNow

getKeyStore

getKeyStore

getModule

getModulePath

getProvider

getSession

getSession

getSlot

getToken

acquireSessionCloseLock

releaseSessionCloseLock

setToBeClosed

isToBeClosed

isSessionCloseLocked

isMechanismFeatureSupported

isMechanismFeatureSupported

isRemovable

isTokenPresent

loginUser

loginSO

login

login

logout

logout

setUserPIN

makeAuthorizedSession

makeAuthorizedSession

waitForSlotEvent

addKeyStoreReference

notifyKeyStores

toString

finalize

closeSessions

getDefaultTokenManager