IAIK PKCS#11 Provider API Documentation
version 1.6

iaik.pkcs.pkcs11.provider
Class DefaultLoginManager

java.lang.Object
  extended by iaik.pkcs.pkcs11.provider.Configurable
      extended by iaik.pkcs.pkcs11.provider.LoginManager
          extended by iaik.pkcs.pkcs11.provider.DefaultLoginManager

public class DefaultLoginManager
extends LoginManager

Author:
freimair

Constructor Summary
DefaultLoginManager()
          Default constructor.
DefaultLoginManager(java.util.Properties configuration)
          The constructor taking configuration parameters which override the configured defaults.
 
Method Summary
 int getNumberOfLoginRetries()
          Get the number of allowed login retries.
 NewPassphrasePrompt getPassphraseChangePrompt()
          Get the configured object for changing the PIN or pass phrase.
 PassphrasePrompt getPassphrasePrompt()
          Get the configured object for prompting a PIN or pass phrase.
 boolean isForceProtectedAuthenticationPath()
          Get if the login manager always uses the protected authentication path for prompting the user PIN, no matter what the corresponding flag in the token info is.
 boolean isUseProtectedAuthenticationPath()
          Get if the login manager uses the protected authentication path for prompting the user PIN, if this feature is available.
 void login(TokenManager tokenManager, iaik.pkcs.pkcs11.Session session, boolean useSORole, char[] userPIN)
          Login a certain role into the given session.
 void loginSO(TokenManager tokenManager, iaik.pkcs.pkcs11.Session session, char[] userPIN)
          Login the Security Officer (SO) into the given session.
 void loginUser(TokenManager tokenManager, iaik.pkcs.pkcs11.Session session, char[] userPIN)
          Login the user into the given session.
 void logout(TokenManager tokenManager, iaik.pkcs.pkcs11.Session session)
          Logout the user from the given session.
 void setForceProtectedAuthenticationPath(boolean forceProtectedAuthenticationPath)
          Set if the login manager shall use the protected authentication path for prompting the user PIN, if this feature is available.
 void setNumberOfLoginRetries(int numberOfLoginRetries)
          Set the number of allowed login retries.
 void setPassphraseChangePrompt(NewPassphrasePrompt passphraseChangePrompt)
          Set the handler object for changing the PIN or pass phrase.
 void setPassphrasePrompt(PassphrasePrompt passphrasePrompt)
          Set the handler object for prompting a PIN or pass phrase.
 void setUseProtectedAuthenticationPath(boolean useProtectedAuthenticationPath)
          Set if the login manager shall use the protected authentication path for prompting the user PIN, if this feature is available.
 void setUserPIN(TokenManager tokenManager, iaik.pkcs.pkcs11.Session session, char[] oldPIN, char[] newPIN)
          Change the user PIN.
 
Methods inherited from class iaik.pkcs.pkcs11.provider.Configurable
addProperties, getProperties, setProperties
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DefaultLoginManager

public DefaultLoginManager()
Default constructor. It uses the configuration of the properties file.


DefaultLoginManager

public DefaultLoginManager(java.util.Properties configuration)
The constructor taking configuration parameters which override the configured defaults. The property keys and values are the same as in the properties file of this class. If the provided configuration does not specify all properties, the missing ones will be taken from the configured defaults if they are required.

Parameters:
configuration - The configuraiton properties. May be null.
Method Detail

getPassphrasePrompt

public PassphrasePrompt getPassphrasePrompt()
Get the configured object for prompting a PIN or pass phrase.

Returns:
The object for prompting a PIN or password. Null, if the configured one is unavailable.

setPassphrasePrompt

public void setPassphrasePrompt(PassphrasePrompt passphrasePrompt)
Set the handler object for prompting a PIN or pass phrase.

Parameters:
passphrasePrompt - The object for prompting a PIN or password. Null, to use the statically configured.

getPassphraseChangePrompt

public NewPassphrasePrompt getPassphraseChangePrompt()
Get the configured object for changing the PIN or pass phrase.

Returns:
The object for changing the PIN or password. Null, if the configured one is unavailable.

setPassphraseChangePrompt

public void setPassphraseChangePrompt(NewPassphrasePrompt passphraseChangePrompt)
Set the handler object for changing the PIN or pass phrase.

Parameters:
passphraseChangePrompt - The object for prompting a PIN or password. Null, to use the statically configured.

getNumberOfLoginRetries

public int getNumberOfLoginRetries()
Get the number of allowed login retries.

Returns:
The number of allowed login retries.
Postconditions
(result >= 1)

setNumberOfLoginRetries

public void setNumberOfLoginRetries(int numberOfLoginRetries)
Set the number of allowed login retries.

Parameters:
numberOfLoginRetries - The number of allowed login retries.
Preconditions
(numberOfLoginRetries >= 1)

isUseProtectedAuthenticationPath

public boolean isUseProtectedAuthenticationPath()
Get if the login manager uses the protected authentication path for prompting the user PIN, if this feature is available. A protected authentication path is a PIN pad on the reader or a fingerprint reader for instance. If this is true, this login manager will use the protected authentication path, if the token indicates that it provides it using the corresponding flag in its token info structure. If you want to force the login manager to use a protected authentication path, no matter what the token info flag is, you can use the setForceProtectedAuthenticationPath(boolean) method.

Returns:
True, if the login manager shall use the protected authentication if available, false otherwise.
See Also:
setUseProtectedAuthenticationPath(boolean), setForceProtectedAuthenticationPath(boolean), isForceProtectedAuthenticationPath()

setUseProtectedAuthenticationPath

public void setUseProtectedAuthenticationPath(boolean useProtectedAuthenticationPath)
Set if the login manager shall use the protected authentication path for prompting the user PIN, if this feature is available. A protected authentication path is a PIN pad on the reader or a fingerprint reader for instance. If you want to force the login manager to use a protected authentication path, no matter what the token info flag is, you can use the setForceProtectedAuthenticationPath(boolean) method.

Parameters:
useProtectedAuthenticationPath - True, if the login manager shall use the protected authentication if available, false otherwise.
See Also:
isUseProtectedAuthenticationPath(), setForceProtectedAuthenticationPath(boolean), isForceProtectedAuthenticationPath()

isForceProtectedAuthenticationPath

public boolean isForceProtectedAuthenticationPath()
Get if the login manager always uses the protected authentication path for prompting the user PIN, no matter what the corresponding flag in the token info is. A protected authentication path is a PIN pad on the reader or a fingerprint reader for instance. If this is true, this login manager will use null values for all PINs when calling login or PIN change functions of the PKCS#11 module.

Returns:
True, if the login manager shall always use the protected authentication path, false otherwise.
See Also:
setForceProtectedAuthenticationPath(boolean), isUseProtectedAuthenticationPath(), setUseProtectedAuthenticationPath(boolean)

setForceProtectedAuthenticationPath

public void setForceProtectedAuthenticationPath(boolean forceProtectedAuthenticationPath)
Set if the login manager shall use the protected authentication path for prompting the user PIN, if this feature is available. A protected authentication path is a PIN pad on the reader or a fingerprint reader for instance.

Parameters:
forceProtectedAuthenticationPath - True, if the login manager shall always use the protected authentication path, false otherwise.
See Also:
isForceProtectedAuthenticationPath(), isUseProtectedAuthenticationPath(), setUseProtectedAuthenticationPath(boolean)

loginUser

public void loginUser(TokenManager tokenManager,
                      iaik.pkcs.pkcs11.Session session,
                      char[] userPIN)
               throws IAIKPkcs11AuthenticationCanceledException,
                      IAIKPkcs11AuthenticationException,
                      iaik.pkcs.pkcs11.TokenException
Login the user into the given session. If the user PIN has been passed by the application, the token manager will pass it to this method. The implementation may ignore this PIN if it has reasons. It is also up to the implementations to make more than one attempt if the first attempt to login fails. After a successful call to this method, the user is logged in to the token of the given token manager. If this could not be done, the method must throw an exception.

Specified by:
loginUser in class LoginManager
Parameters:
tokenManager - The token manager that requests the login.
session - The session to login the user. If the session is null, the method may open a new session.
Throws:
iaik.pkcs.pkcs11.TokenException
IAIKPkcs11AuthenticationCanceledException - If the login has been canceled.
IAIKPkcs11AuthenticationException - If the user PIN could not be changed; e.g. wrong PIN.

loginSO

public void loginSO(TokenManager tokenManager,
                    iaik.pkcs.pkcs11.Session session,
                    char[] userPIN)
             throws iaik.pkcs.pkcs11.TokenException,
                    IAIKPkcs11AuthenticationCanceledException,
                    IAIKPkcs11AuthenticationException
Login the Security Officer (SO) into the given session. If the PIN has been passed by the application, the token manager will pass it to this method. The implementation may ignore this PIN if it has reasons. It is also up to the implementations to make more than one attempt if the first attempt to login fails. After a successful call to this method, the SO is logged in to the token of the given token manager. If this could not be done, the method must throw an exception.

Specified by:
loginSO in class LoginManager
Parameters:
tokenManager - The token manager that requests the login.
session - The session to login the SO. If the session is null, the method may open a new session.
Throws:
IAIKPkcs11AuthenticationCanceledException - If the login has been canceled.
IAIKPkcs11AuthenticationException - If the user PIN could not be changed; e.g. wrong PIN.
iaik.pkcs.pkcs11.TokenException

login

public void login(TokenManager tokenManager,
                  iaik.pkcs.pkcs11.Session session,
                  boolean useSORole,
                  char[] userPIN)
           throws iaik.pkcs.pkcs11.TokenException,
                  IAIKPkcs11AuthenticationCanceledException,
                  IAIKPkcs11AuthenticationException
Login a certain role into the given session. If the PIN has been passed by the application, the token manager will pass it to this method. The implementation may ignore this PIN if it has reasons. It is also up to the implementations to make more than one attempt if the first attempt to login fails. After a successful call to this method, the requested role is logged in to the token of the given token manager. If this could not be done, the method must throw an exception.

Specified by:
login in class LoginManager
Parameters:
tokenManager - The token manager that requests the login.
session - The session to login. If the session is null, the method may open a new session.
useSORole - The role to authenticate to. Use true to authenticate as SO, false to authenticate as user.
Throws:
IAIKPkcs11AuthenticationCanceledException - If the login has been canceled.
IAIKPkcs11AuthenticationException - If the user PIN could not be changed; e.g. wrong PIN.
iaik.pkcs.pkcs11.TokenException

setUserPIN

public void setUserPIN(TokenManager tokenManager,
                       iaik.pkcs.pkcs11.Session session,
                       char[] oldPIN,
                       char[] newPIN)
                throws iaik.pkcs.pkcs11.TokenException,
                       IAIKPkcs11AuthenticationCanceledException,
                       IAIKPkcs11AuthenticationException
Change the user PIN. The implementation should use the given session, unless it has reasons not to use it. If the user is not already logged in to the given session, it is up to the implementation to log the user in if required (PKCS#11 v2.11 or later do not require the session to be logged in for changing the user PIN). If the old and new user PINs are already known, they are also passed as parameters. The implementation should use them, if possible. After a successful call to this method, the user PIN is changed. If this could not be done, the method must throw an exception.

Specified by:
setUserPIN in class LoginManager
Parameters:
tokenManager - The token manager requesting the PIN change.
session - The session to use for changing the PIN. If the session is null, the method may open a new session.
oldPIN - The old (current) user PIN or null if unavailable.
newPIN -
Throws:
iaik.pkcs.pkcs11.TokenException - If the change faild because of an unexpected token error.
IAIKPkcs11AuthenticationCanceledException - If the operation has been canceled.
IAIKPkcs11AuthenticationException - If the user PIN could not be changed; e.g. wrong PIN.
Preconditions
(tokenManager <> null)
Postconditions
"the user PIN set"

logout

public void logout(TokenManager tokenManager,
                   iaik.pkcs.pkcs11.Session session)
            throws iaik.pkcs.pkcs11.TokenException
Logout the user from the given session. After a successful call to this method, the user is logged out. If this could not be done, the method must throw an exception.

Specified by:
logout in class LoginManager
Parameters:
tokenManager - The token manager requesting the logout.
session - The session to logout. If the session is null, the method may open a new session.
Throws:
iaik.pkcs.pkcs11.TokenException - If the logout fails because of an unexpected token error.
Preconditions
(tokenManager <> null)
Postconditions
"user is logged out"

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