iaik.pkcs.pkcs11.provider

Class DefaultLoginManager

java.lang.Object

iaik.pkcs.pkcs11.provider.Configurable

iaik.pkcs.pkcs11.provider.LoginManager

iaik.pkcs.pkcs11.provider.DefaultLoginManager

public class DefaultLoginManager
extends LoginManager

Author:

freimair

Field Summary

Fields

Modifier and Type	Field and Description
protected static java.lang.String	CONFIGURATION_PROPERTIES The name of the properties file that holds the configuration.
protected static java.lang.String	DEFAULT_CHANGE_DIALOG The name of the properties enrty for the new passphrase dialog.
protected static java.lang.String	DEFAULT_CONFIGURATION_PROPERTIES The name of the properties file that holds the configuration.
protected static java.lang.String	DEFAULT_NEW_PROMPT_MESSAGE_PREFIX The name of the properties enrty for the prefix of the message presented to the user when prompting a new passphrase or PIN.
protected static java.lang.String	DEFAULT_PROMPT_DIALOG The name of the properties enrty for the passphrase prompt dialog.
protected static java.lang.String	DEFAULT_PROMPT_MESSAGE_PREFIX The name of the properties enrty for the prefix of the message presented to the user when prompting a passphrase or PIN.
protected static java.util.Properties	defaultConfiguration_ The default configuation of this login manager.
protected static java.lang.String	FORCE_PROTECTED_AUTHENTICATION_PATH The name of the properties enrty that specifies, if the login manager should always use the protected authentication path (no matter what the token info says).
protected static java.lang.String	INVALID_NEW_PIN_WARNING The name of the properties enrty for the message presented if the user entered an invalid new passphrase or PIN.
protected static java.lang.String	KEY_WORD_TOKEN_LABEL The key word that is substituted with the token label.
protected static java.lang.String	KEY_WORD_TRIALS_LEFT The key word that is substituted with the number of trial left.
protected static java.lang.String	LINE_SEPARATOR The line separator used for debug outputs and in toString() methods.
protected static java.lang.String	NEW_PIN_LENGTH_WARNING The name of the properties enrty for the message presented if the user entered an new passphrase or PIN with an invlaid length.
protected static java.lang.String	NUMBER_OF_USER_LOGIN_RETRIES The name of the properties enrty for the maximum number of wrong passphrase/PIN entries.
protected NewPassphrasePrompt	passphraseChangePrompt_ The object to use for prompting pass phrases or PINs respectively.
protected PassphrasePrompt	passphrasePrompt_ The object to use for prompting pass phrases or PINs respectively.
protected static java.lang.String	PIN_FINAL_TRY_WARNING The name of the properties enrty for the message presented to the user when it is the finaly try for entering a passphrase or PIN.
protected static java.lang.String	USE_PROTECTED_AUTHENTICATION_PATH The name of the properties enrty that specifies, if the login manager should use the protected authentication path if available.
protected static java.lang.String	WRONG_PIN_WARNING The name of the properties enrty for the message presented if the user entered a wrong passphrase or PIN.

Fields inherited from class iaik.pkcs.pkcs11.provider.Configurable

defaultProperties_, properties_

Constructor Summary

Constructors

Constructor and Description
DefaultLoginManager() Default constructor.
DefaultLoginManager(java.util.Properties configuration) The constructor taking configuration parameters which override the configured defaults.

Method Summary

Modifier and Type	Method and Description
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.
protected java.lang.String	replaceKeyWord(java.lang.String message, java.lang.String keyWord, java.lang.String keyWordValue) Replace all ocurrances of the key word in the given message with the given value.
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.
protected boolean	useNullPINs(TokenManager tokenManager, iaik.pkcs.pkcs11.Session session) If this method returns true, the methods for login and PIN change will pass null values to the login and set-PIN functions, no matter if a PIN has been passed by the application or if the token indicates that it has no protected authentication path; i.e.

Methods inherited from class iaik.pkcs.pkcs11.provider.Configurable

addProperties, getProperties, propertiesChanged, setProperties

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_CONFIGURATION_PROPERTIES

protected static final java.lang.String DEFAULT_CONFIGURATION_PROPERTIES

The name of the properties file that holds the configuration.

See Also:

Constant Field Values

CONFIGURATION_PROPERTIES

protected static final java.lang.String CONFIGURATION_PROPERTIES

The name of the properties file that holds the configuration.

See Also:

Constant Field Values

DEFAULT_PROMPT_DIALOG

protected static final java.lang.String DEFAULT_PROMPT_DIALOG

The name of the properties enrty for the passphrase prompt dialog.

See Also:

Constant Field Values

DEFAULT_CHANGE_DIALOG

protected static final java.lang.String DEFAULT_CHANGE_DIALOG

The name of the properties enrty for the new passphrase dialog.

See Also:

Constant Field Values

DEFAULT_NEW_PROMPT_MESSAGE_PREFIX

protected static final java.lang.String DEFAULT_NEW_PROMPT_MESSAGE_PREFIX

The name of the properties enrty for the prefix of the message presented to the user when prompting a new passphrase or PIN.

See Also:

Constant Field Values

DEFAULT_PROMPT_MESSAGE_PREFIX

protected static final java.lang.String DEFAULT_PROMPT_MESSAGE_PREFIX

The name of the properties enrty for the prefix of the message presented to the user when prompting a passphrase or PIN.

See Also:

Constant Field Values

WRONG_PIN_WARNING

protected static final java.lang.String WRONG_PIN_WARNING

The name of the properties enrty for the message presented if the user entered a wrong passphrase or PIN.

See Also:

Constant Field Values

PIN_FINAL_TRY_WARNING

protected static final java.lang.String PIN_FINAL_TRY_WARNING

The name of the properties enrty for the message presented to the user when it is the finaly try for entering a passphrase or PIN.

See Also:

Constant Field Values

KEY_WORD_TRIALS_LEFT

protected static final java.lang.String KEY_WORD_TRIALS_LEFT

The key word that is substituted with the number of trial left. This can be used in the wrong passphrase/PIN warning.

See Also:

Constant Field Values

KEY_WORD_TOKEN_LABEL

protected static final java.lang.String KEY_WORD_TOKEN_LABEL

The key word that is substituted with the token label. This can be used in the passphrase/PIN prompt message.

See Also:

Constant Field Values

NUMBER_OF_USER_LOGIN_RETRIES

protected static final java.lang.String NUMBER_OF_USER_LOGIN_RETRIES

The name of the properties enrty for the maximum number of wrong passphrase/PIN entries.

See Also:

Constant Field Values

INVALID_NEW_PIN_WARNING

protected static final java.lang.String INVALID_NEW_PIN_WARNING

The name of the properties enrty for the message presented if the user entered an invalid new passphrase or PIN.

See Also:

Constant Field Values

NEW_PIN_LENGTH_WARNING

protected static final java.lang.String NEW_PIN_LENGTH_WARNING

The name of the properties enrty for the message presented if the user entered an new passphrase or PIN with an invlaid length.

See Also:

Constant Field Values

USE_PROTECTED_AUTHENTICATION_PATH

protected static final java.lang.String USE_PROTECTED_AUTHENTICATION_PATH

The name of the properties enrty that specifies, if the login manager should use the protected authentication path if available.

See Also:

Constant Field Values

FORCE_PROTECTED_AUTHENTICATION_PATH

protected static final java.lang.String FORCE_PROTECTED_AUTHENTICATION_PATH

The name of the properties enrty that specifies, if the login manager should always use the protected authentication path (no matter what the token info says).

See Also:

Constant Field Values

LINE_SEPARATOR

protected static java.lang.String LINE_SEPARATOR

The line separator used for debug outputs and in toString() methods.

defaultConfiguration_

protected static java.util.Properties defaultConfiguration_

The default configuation of this login manager.

passphrasePrompt_

protected PassphrasePrompt passphrasePrompt_

The object to use for prompting pass phrases or PINs respectively.

passphraseChangePrompt_

protected NewPassphrasePrompt passphraseChangePrompt_

The object to use for prompting pass phrases or PINs respectively.

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.

Postconditions:

"the user PIN set"

Preconditions:

(tokenManager <> null)

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.

Postconditions:

"user is logged out"

Preconditions:

(tokenManager <> null)

useNullPINs

protected boolean useNullPINs(TokenManager tokenManager,
                              iaik.pkcs.pkcs11.Session session)
                       throws iaik.pkcs.pkcs11.TokenException

If this method returns true, the methods for login and PIN change will pass null values to the login and set-PIN functions, no matter if a PIN has been passed by the application or if the token indicates that it has no protected authentication path; i.e. this method can force the use of a protected authentication path. This implementation checks if the protected authentication path flag is set in the token info and if the use of the protected authentication path is enabled. If both are true or if isForceProtectedAuthenticationPath() is true, it returns true.

Parameters:

tokenManager - The token manager for the concernde token.

session - The session used for the operation.

Returns:

True, to use null values as PINs; false otherwise.

Throws:

iaik.pkcs.pkcs11.TokenException - If getting the token info fails.

See Also:

isUseProtectedAuthenticationPath(), setUseProtectedAuthenticationPath(boolean), isForceProtectedAuthenticationPath(), setForceProtectedAuthenticationPath(boolean)

Preconditions:

(tokenManager <> null) and (session <> null)

replaceKeyWord

protected java.lang.String replaceKeyWord(java.lang.String message,
                                          java.lang.String keyWord,
                                          java.lang.String keyWordValue)

Replace all ocurrances of the key word in the given message with the given value.

Parameters:

message - The message which may contain the key word.

keyWord - The key word to search for.

keyWordValue - The value to replace for the key word.

Returns:

The message with the key word repleaced with the value.

Postconditions:

(result <> null)

Preconditions:

(message <> null) and (keyWord <> null)