Home » openjdk-7 » javax.security » auth » spi » [javadoc | source]

    1   /*
    2    * Copyright (c) 1998, 2004, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   
   26   package javax.security.auth.spi;
   27   
   28   import javax.security.auth.Subject;
   29   import javax.security.auth.AuthPermission;
   30   import javax.security.auth.callback;
   31   import javax.security.auth.login;
   32   import java.util.Map;
   33   
   34   /**
   35    * <p> <code>LoginModule</code> describes the interface
   36    * implemented by authentication technology providers.  LoginModules
   37    * are plugged in under applications to provide a particular type of
   38    * authentication.
   39    *
   40    * <p> While applications write to the <code>LoginContext</code> API,
   41    * authentication technology providers implement the
   42    * <code>LoginModule</code> interface.
   43    * A <code>Configuration</code> specifies the LoginModule(s)
   44    * to be used with a particular login application.  Therefore different
   45    * LoginModules can be plugged in under the application without
   46    * requiring any modifications to the application itself.
   47    *
   48    * <p> The <code>LoginContext</code> is responsible for reading the
   49    * <code>Configuration</code> and instantiating the appropriate
   50    * LoginModules.  Each <code>LoginModule</code> is initialized with
   51    * a <code>Subject</code>, a <code>CallbackHandler</code>, shared
   52    * <code>LoginModule</code> state, and LoginModule-specific options.
   53    *
   54    * The <code>Subject</code> represents the
   55    * <code>Subject</code> currently being authenticated and is updated
   56    * with relevant Credentials if authentication succeeds.
   57    * LoginModules use the <code>CallbackHandler</code> to
   58    * communicate with users.  The <code>CallbackHandler</code> may be
   59    * used to prompt for usernames and passwords, for example.
   60    * Note that the <code>CallbackHandler</code> may be null.  LoginModules
   61    * which absolutely require a <code>CallbackHandler</code> to authenticate
   62    * the <code>Subject</code> may throw a <code>LoginException</code>.
   63    * LoginModules optionally use the shared state to share information
   64    * or data among themselves.
   65    *
   66    * <p> The LoginModule-specific options represent the options
   67    * configured for this <code>LoginModule</code> by an administrator or user
   68    * in the login <code>Configuration</code>.
   69    * The options are defined by the <code>LoginModule</code> itself
   70    * and control the behavior within it.  For example, a
   71    * <code>LoginModule</code> may define options to support debugging/testing
   72    * capabilities.  Options are defined using a key-value syntax,
   73    * such as <i>debug=true</i>.  The <code>LoginModule</code>
   74    * stores the options as a <code>Map</code> so that the values may
   75    * be retrieved using the key.  Note that there is no limit to the number
   76    * of options a <code>LoginModule</code> chooses to define.
   77    *
   78    * <p> The calling application sees the authentication process as a single
   79    * operation.  However, the authentication process within the
   80    * <code>LoginModule</code> proceeds in two distinct phases.
   81    * In the first phase, the LoginModule's
   82    * <code>login</code> method gets invoked by the LoginContext's
   83    * <code>login</code> method.  The <code>login</code>
   84    * method for the <code>LoginModule</code> then performs
   85    * the actual authentication (prompt for and verify a password for example)
   86    * and saves its authentication status as private state
   87    * information.  Once finished, the LoginModule's <code>login</code>
   88    * method either returns <code>true</code> (if it succeeded) or
   89    * <code>false</code> (if it should be ignored), or throws a
   90    * <code>LoginException</code> to specify a failure.
   91    * In the failure case, the <code>LoginModule</code> must not retry the
   92    * authentication or introduce delays.  The responsibility of such tasks
   93    * belongs to the application.  If the application attempts to retry
   94    * the authentication, the LoginModule's <code>login</code> method will be
   95    * called again.
   96    *
   97    * <p> In the second phase, if the LoginContext's overall authentication
   98    * succeeded (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL
   99    * LoginModules succeeded), then the <code>commit</code>
  100    * method for the <code>LoginModule</code> gets invoked.
  101    * The <code>commit</code> method for a <code>LoginModule</code> checks its
  102    * privately saved state to see if its own authentication succeeded.
  103    * If the overall <code>LoginContext</code> authentication succeeded
  104    * and the LoginModule's own authentication succeeded, then the
  105    * <code>commit</code> method associates the relevant
  106    * Principals (authenticated identities) and Credentials (authentication data
  107    * such as cryptographic keys) with the <code>Subject</code>
  108    * located within the <code>LoginModule</code>.
  109    *
  110    * <p> If the LoginContext's overall authentication failed (the relevant
  111    * REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules did not succeed),
  112    * then the <code>abort</code> method for each <code>LoginModule</code>
  113    * gets invoked.  In this case, the <code>LoginModule</code> removes/destroys
  114    * any authentication state originally saved.
  115    *
  116    * <p> Logging out a <code>Subject</code> involves only one phase.
  117    * The <code>LoginContext</code> invokes the LoginModule's <code>logout</code>
  118    * method.  The <code>logout</code> method for the <code>LoginModule</code>
  119    * then performs the logout procedures, such as removing Principals or
  120    * Credentials from the <code>Subject</code> or logging session information.
  121    *
  122    * <p> A <code>LoginModule</code> implementation must have a constructor with
  123    * no arguments.  This allows classes which load the <code>LoginModule</code>
  124    * to instantiate it.
  125    *
  126    * @see javax.security.auth.login.LoginContext
  127    * @see javax.security.auth.login.Configuration
  128    */
  129   public interface LoginModule {
  130   
  131       /**
  132        * Initialize this LoginModule.
  133        *
  134        * <p> This method is called by the <code>LoginContext</code>
  135        * after this <code>LoginModule</code> has been instantiated.
  136        * The purpose of this method is to initialize this
  137        * <code>LoginModule</code> with the relevant information.
  138        * If this <code>LoginModule</code> does not understand
  139        * any of the data stored in <code>sharedState</code> or
  140        * <code>options</code> parameters, they can be ignored.
  141        *
  142        * <p>
  143        *
  144        * @param subject the <code>Subject</code> to be authenticated. <p>
  145        *
  146        * @param callbackHandler a <code>CallbackHandler</code> for communicating
  147        *                  with the end user (prompting for usernames and
  148        *                  passwords, for example). <p>
  149        *
  150        * @param sharedState state shared with other configured LoginModules. <p>
  151        *
  152        * @param options options specified in the login
  153        *                  <code>Configuration</code> for this particular
  154        *                  <code>LoginModule</code>.
  155        */
  156       void initialize(Subject subject, CallbackHandler callbackHandler,
  157                       Map<String,?> sharedState,
  158                       Map<String,?> options);
  159   
  160       /**
  161        * Method to authenticate a <code>Subject</code> (phase 1).
  162        *
  163        * <p> The implementation of this method authenticates
  164        * a <code>Subject</code>.  For example, it may prompt for
  165        * <code>Subject</code> information such
  166        * as a username and password and then attempt to verify the password.
  167        * This method saves the result of the authentication attempt
  168        * as private state within the LoginModule.
  169        *
  170        * <p>
  171        *
  172        * @exception LoginException if the authentication fails
  173        *
  174        * @return true if the authentication succeeded, or false if this
  175        *                  <code>LoginModule</code> should be ignored.
  176        */
  177       boolean login() throws LoginException;
  178   
  179       /**
  180        * Method to commit the authentication process (phase 2).
  181        *
  182        * <p> This method is called if the LoginContext's
  183        * overall authentication succeeded
  184        * (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules
  185        * succeeded).
  186        *
  187        * <p> If this LoginModule's own authentication attempt
  188        * succeeded (checked by retrieving the private state saved by the
  189        * <code>login</code> method), then this method associates relevant
  190        * Principals and Credentials with the <code>Subject</code> located in the
  191        * <code>LoginModule</code>.  If this LoginModule's own
  192        * authentication attempted failed, then this method removes/destroys
  193        * any state that was originally saved.
  194        *
  195        * <p>
  196        *
  197        * @exception LoginException if the commit fails
  198        *
  199        * @return true if this method succeeded, or false if this
  200        *                  <code>LoginModule</code> should be ignored.
  201        */
  202       boolean commit() throws LoginException;
  203   
  204       /**
  205        * Method to abort the authentication process (phase 2).
  206        *
  207        * <p> This method is called if the LoginContext's
  208        * overall authentication failed.
  209        * (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules
  210        * did not succeed).
  211        *
  212        * <p> If this LoginModule's own authentication attempt
  213        * succeeded (checked by retrieving the private state saved by the
  214        * <code>login</code> method), then this method cleans up any state
  215        * that was originally saved.
  216        *
  217        * <p>
  218        *
  219        * @exception LoginException if the abort fails
  220        *
  221        * @return true if this method succeeded, or false if this
  222        *                  <code>LoginModule</code> should be ignored.
  223        */
  224       boolean abort() throws LoginException;
  225   
  226       /**
  227        * Method which logs out a <code>Subject</code>.
  228        *
  229        * <p>An implementation of this method might remove/destroy a Subject's
  230        * Principals and Credentials.
  231        *
  232        * <p>
  233        *
  234        * @exception LoginException if the logout fails
  235        *
  236        * @return true if this method succeeded, or false if this
  237        *                  <code>LoginModule</code> should be ignored.
  238        */
  239       boolean logout() throws LoginException;
  240   }

Home » openjdk-7 » javax.security » auth » spi » [javadoc | source]