IAIK PKCS#11 Provider API Documentation
version 1.6

iaik.pkcs.pkcs11.provider
Class LoginManager

java.lang.Object
  extended by iaik.pkcs.pkcs11.provider.Configurable
      extended by 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

Constructor Summary
LoginManager()
           
 
Method Summary
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, setProperties
 
Methods inherited from class java.lang.Object
equals, 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.
Preconditions
(tokenManager <> null)
Postconditions
"the user PIN set"

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