1. /*

  2.  * @(#)LoginModule.java	1.51 03/01/23

  3.  *

  4.  * Copyright 2003 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. package javax.security.auth.spi;

  9. 

  10. import javax.security.auth.Subject;

  11. import javax.security.auth.AuthPermission;

  12. import javax.security.auth.callback.*;

  13. import javax.security.auth.login.*;

  14. import java.util.Map;

  15. 

  16. /**

  17.  * <p> <code>LoginModule</code> describes the interface

  18.  * implemented by authentication technology providers.  LoginModules

  19.  * are plugged in under applications to provide a particular type of

  20.  * authentication.

  21.  *

  22.  * <p> While applications write to the <code>LoginContext</code> API,

  23.  * authentication technology providers implement the

  24.  * <code>LoginModule</code> interface.

  25.  * A <code>Configuration</code> specifies the LoginModule(s)

  26.  * to be used with a particular login application.  Therefore different

  27.  * LoginModules can be plugged in under the application without

  28.  * requiring any modifications to the application itself.

  29.  *

  30.  * <p> The <code>LoginContext</code> is responsible for reading the

  31.  * <code>Configuration</code> and instantiating the appropriate

  32.  * LoginModules.  Each <code>LoginModule</code> is initialized with

  33.  * a <code>Subject</code>, a <code>CallbackHandler</code>, shared

  34.  * <code>LoginModule</code> state, and LoginModule-specific options.

  35.  * 

  36.  * The <code>Subject</code> represents the

  37.  * <code>Subject</code> currently being authenticated and is updated

  38.  * with relevant Credentials if authentication succeeds.

  39.  * LoginModules use the <code>CallbackHandler</code> to

  40.  * communicate with users.  The <code>CallbackHandler</code> may be

  41.  * used to prompt for usernames and passwords, for example.

  42.  * Note that the <code>CallbackHandler</code> may be null.  LoginModules

  43.  * which absolutely require a <code>CallbackHandler</code> to authenticate

  44.  * the <code>Subject</code> may throw a <code>LoginException</code>.

  45.  * LoginModules optionally use the shared state to share information

  46.  * or data among themselves.

  47.  *

  48.  * <p> The LoginModule-specific options represent the options

  49.  * configured for this <code>LoginModule</code> by an administrator or user

  50.  * in the login <code>Configuration</code>.

  51.  * The options are defined by the <code>LoginModule</code> itself

  52.  * and control the behavior within it.  For example, a

  53.  * <code>LoginModule</code> may define options to support debugging/testing

  54.  * capabilities.  Options are defined using a key-value syntax,

  55.  * such as <i>debug=true</i>.  The <code>LoginModule</code>

  56.  * stores the options as a <code>Map</code> so that the values may

  57.  * be retrieved using the key.  Note that there is no limit to the number

  58.  * of options a <code>LoginModule</code> chooses to define.

  59.  *

  60.  * <p> The calling application sees the authentication process as a single

  61.  * operation.  However, the authentication process within the

  62.  * <code>LoginModule</code> proceeds in two distinct phases.

  63.  * In the first phase, the LoginModule's

  64.  * <code>login</code> method gets invoked by the LoginContext's

  65.  * <code>login</code> method.  The <code>login</code>

  66.  * method for the <code>LoginModule</code> then performs

  67.  * the actual authentication (prompt for and verify a password for example)

  68.  * and saves its authentication status as private state

  69.  * information.  Once finished, the LoginModule's <code>login</code>

  70.  * method either returns <code>true</code> (if it succeeded) or

  71.  * <code>false</code> (if it should be ignored), or throws a

  72.  * <code>LoginException</code> to specify a failure.

  73.  * In the failure case, the <code>LoginModule</code> must not retry the

  74.  * authentication or introduce delays.  The responsibility of such tasks

  75.  * belongs to the application.  If the application attempts to retry

  76.  * the authentication, the LoginModule's <code>login</code> method will be

  77.  * called again.

  78.  *

  79.  * <p> In the second phase, if the LoginContext's overall authentication

  80.  * succeeded (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL

  81.  * LoginModules succeeded), then the <code>commit</code>

  82.  * method for the <code>LoginModule</code> gets invoked.

  83.  * The <code>commit</code> method for a <code>LoginModule</code> checks its

  84.  * privately saved state to see if its own authentication succeeded.

  85.  * If the overall <code>LoginContext</code> authentication succeeded

  86.  * and the LoginModule's own authentication succeeded, then the

  87.  * <code>commit</code> method associates the relevant

  88.  * Principals (authenticated identities) and Credentials (authentication data

  89.  * such as cryptographic keys) with the <code>Subject</code>

  90.  * located within the <code>LoginModule</code>.

  91.  *

  92.  * <p> If the LoginContext's overall authentication failed (the relevant

  93.  * REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules did not succeed),

  94.  * then the <code>abort</code> method for each <code>LoginModule</code>

  95.  * gets invoked.  In this case, the <code>LoginModule</code> removes/destroys

  96.  * any authentication state originally saved.

  97.  *

  98.  * <p> Logging out a <code>Subject</code> involves only one phase.

  99.  * The <code>LoginContext</code> invokes the LoginModule's <code>logout</code>

  100.  * method.  The <code>logout</code> method for the <code>LoginModule</code>

  101.  * then performs the logout procedures, such as removing Principals or

  102.  * Credentials from the <code>Subject</code> or logging session information.

  103.  *

  104.  * <p> A <code>LoginModule</code> implementation must have a constructor with

  105.  * no arguments.  This allows classes which load the <code>LoginModule</code>

  106.  * to instantiate it.

  107.  *

  108.  * @version 1.51, 01/23/03

  109.  * @see javax.security.auth.login.LoginContext

  110.  * @see javax.security.auth.login.Configuration

  111.  */

  112. public interface LoginModule {

  113. 

  114.     /**

  115.      * Initialize this LoginModule.

  116.      *

  117.      * <p> This method is called by the <code>LoginContext</code>

  118.      * after this <code>LoginModule</code> has been instantiated.

  119.      * The purpose of this method is to initialize this

  120.      * <code>LoginModule</code> with the relevant information.

  121.      * If this <code>LoginModule</code> does not understand

  122.      * any of the data stored in <code>sharedState</code> or

  123.      * <code>options</code> parameters, they can be ignored.

  124.      *

  125.      * <p>

  126.      *

  127.      * @param subject the <code>Subject</code> to be authenticated. <p>

  128.      *

  129.      * @param callbackHandler a <code>CallbackHandler</code> for communicating

  130.      *			with the end user (prompting for usernames and

  131.      *			passwords, for example). <p>

  132.      *

  133.      * @param sharedState state shared with other configured LoginModules. <p>

  134.      *

  135.      * @param options options specified in the login

  136.      *			<code>Configuration</code> for this particular

  137.      *			<code>LoginModule</code>.

  138.      */

  139.     void initialize(Subject subject, CallbackHandler callbackHandler,

  140. 		Map sharedState, Map options);

  141. 

  142.     /**

  143.      * Method to authenticate a <code>Subject</code> (phase 1).

  144.      *

  145.      * <p> The implementation of this method authenticates

  146.      * a <code>Subject</code>.  For example, it may prompt for

  147.      * <code>Subject</code> information such

  148.      * as a username and password and then attempt to verify the password.

  149.      * This method saves the result of the authentication attempt

  150.      * as private state within the LoginModule.

  151.      *

  152.      * <p>

  153.      *

  154.      * @exception LoginException if the authentication fails

  155.      *

  156.      * @return true if the authentication succeeded, or false if this

  157.      *			<code>LoginModule</code> should be ignored.

  158.      */

  159.     boolean login() throws LoginException;

  160. 

  161.     /**

  162.      * Method to commit the authentication process (phase 2).

  163.      *

  164.      * <p> This method is called if the LoginContext's

  165.      * overall authentication succeeded

  166.      * (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules

  167.      * succeeded).

  168.      *

  169.      * <p> If this LoginModule's own authentication attempt

  170.      * succeeded (checked by retrieving the private state saved by the

  171.      * <code>login</code> method), then this method associates relevant

  172.      * Principals and Credentials with the <code>Subject</code> located in the

  173.      * <code>LoginModule</code>.  If this LoginModule's own

  174.      * authentication attempted failed, then this method removes/destroys

  175.      * any state that was originally saved.

  176.      *

  177.      * <p>

  178.      *

  179.      * @exception LoginException if the commit fails

  180.      *

  181.      * @return true if this method succeeded, or false if this

  182.      *			<code>LoginModule</code> should be ignored.

  183.      */

  184.     boolean commit() throws LoginException;

  185. 

  186.     /**

  187.      * Method to abort the authentication process (phase 2).

  188.      *

  189.      * <p> This method is called if the LoginContext's

  190.      * overall authentication failed.

  191.      * (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules

  192.      * did not succeed).

  193.      *

  194.      * <p> If this LoginModule's own authentication attempt

  195.      * succeeded (checked by retrieving the private state saved by the

  196.      * <code>login</code> method), then this method cleans up any state

  197.      * that was originally saved.

  198.      *

  199.      * <p>

  200.      *

  201.      * @exception LoginException if the abort fails

  202.      *

  203.      * @return true if this method succeeded, or false if this

  204.      *			<code>LoginModule</code> should be ignored.

  205.      */

  206.     boolean abort() throws LoginException;

  207. 

  208.     /**

  209.      * Method which logs out a <code>Subject</code>.  

  210.      *

  211.      * <p>An implementation of this method might remove/destroy a Subject's

  212.      * Principals and Credentials.

  213.      *

  214.      * <p>

  215.      *

  216.      * @exception LoginException if the logout fails

  217.      *

  218.      * @return true if this method succeeded, or false if this

  219.      *			<code>LoginModule</code> should be ignored.

  220.      */

  221.     boolean logout() throws LoginException;

  222. }