iaik.pkcs.pkcs11.provider

Class LoginManager

java.lang.Object

iaik.pkcs.pkcs11.provider.Configurable

iaik.pkcs.pkcs11.provider.LoginManager

Direct Known Subclasses:

DefaultLoginManager

public abstract class LoginManager
extends Configurable

This is the interface to a login manager. A login manager is used by the token manager to login the user into sessions, to logout sessions and to change the user PIN. An implementation of this interface may choose to prompt the PIN from the user through a graphical user interface or may retrieve the PIN from other sources. It may even decide to use other means to login the user; e.g. it may use a PIN-pad by calling login with null as PIN value. If the implementation needs information about the token (e.g. for displaying it), it can get it from the provided session object. It may also access the token manager to get certain settings of the token manager or the provider. An implementation may also decide to cache a PIN.

Author:

Karl Scheibelhofer

Field Summary

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

defaultProperties_, properties_

Constructor Summary

Constructors

Constructor and Description
LoginManager()

Method Summary

Modifier and Type	Method and Description
abstract void	login(TokenManager tokenManager, iaik.pkcs.pkcs11.Session session, boolean useSORole, char[] userPIN) Login a certain role into the given session.
abstract void	loginSO(TokenManager tokenManager, iaik.pkcs.pkcs11.Session session, char[] userPIN) Login the Security Officer (SO) into the given session.
abstract void	loginUser(TokenManager tokenManager, iaik.pkcs.pkcs11.Session session, char[] userPIN) Login the user into the given session.
abstract void	logout(TokenManager tokenManager, iaik.pkcs.pkcs11.Session session) Logout the user from the given session.
abstract 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, propertiesChanged, setProperties

Methods inherited from class java.lang.Object

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

Constructor Detail

LoginManager

public LoginManager()

Method Detail

loginUser

public abstract 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.

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 abstract 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.

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 abstract 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.

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 abstract 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.

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 abstract 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.

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)