2362N/A * Copyright (c) 1998, 2004, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * <p> <code>LoginModule</code> describes the interface 0N/A * implemented by authentication technology providers. LoginModules 0N/A * are plugged in under applications to provide a particular type of 0N/A * <p> While applications write to the <code>LoginContext</code> API, 0N/A * authentication technology providers implement the 0N/A * <code>LoginModule</code> interface. 0N/A * A <code>Configuration</code> specifies the LoginModule(s) 0N/A * to be used with a particular login application. Therefore different 0N/A * LoginModules can be plugged in under the application without 0N/A * requiring any modifications to the application itself. 0N/A * <p> The <code>LoginContext</code> is responsible for reading the 0N/A * <code>Configuration</code> and instantiating the appropriate 0N/A * LoginModules. Each <code>LoginModule</code> is initialized with 0N/A * a <code>Subject</code>, a <code>CallbackHandler</code>, shared 0N/A * <code>LoginModule</code> state, and LoginModule-specific options. 0N/A * The <code>Subject</code> represents the 0N/A * <code>Subject</code> currently being authenticated and is updated 0N/A * with relevant Credentials if authentication succeeds. 0N/A * LoginModules use the <code>CallbackHandler</code> to 0N/A * communicate with users. The <code>CallbackHandler</code> may be 0N/A * used to prompt for usernames and passwords, for example. 0N/A * Note that the <code>CallbackHandler</code> may be null. LoginModules 0N/A * which absolutely require a <code>CallbackHandler</code> to authenticate 0N/A * the <code>Subject</code> may throw a <code>LoginException</code>. 0N/A * LoginModules optionally use the shared state to share information 0N/A * or data among themselves. 0N/A * <p> The LoginModule-specific options represent the options 0N/A * configured for this <code>LoginModule</code> by an administrator or user 0N/A * in the login <code>Configuration</code>. 0N/A * The options are defined by the <code>LoginModule</code> itself 0N/A * and control the behavior within it. For example, a 0N/A * capabilities. Options are defined using a key-value syntax, 0N/A * such as <i>debug=true</i>. The <code>LoginModule</code> 0N/A * stores the options as a <code>Map</code> so that the values may 0N/A * be retrieved using the key. Note that there is no limit to the number 0N/A * of options a <code>LoginModule</code> chooses to define. 0N/A * <p> The calling application sees the authentication process as a single 0N/A * operation. However, the authentication process within the 0N/A * <code>LoginModule</code> proceeds in two distinct phases. 0N/A * In the first phase, the LoginModule's 0N/A * <code>login</code> method gets invoked by the LoginContext's 0N/A * <code>login</code> method. The <code>login</code> 0N/A * method for the <code>LoginModule</code> then performs 0N/A * the actual authentication (prompt for and verify a password for example) 0N/A * and saves its authentication status as private state 0N/A * information. Once finished, the LoginModule's <code>login</code> 0N/A * method either returns <code>true</code> (if it succeeded) or 0N/A * <code>false</code> (if it should be ignored), or throws a 0N/A * <code>LoginException</code> to specify a failure. 0N/A * In the failure case, the <code>LoginModule</code> must not retry the 0N/A * authentication or introduce delays. The responsibility of such tasks 0N/A * belongs to the application. If the application attempts to retry 0N/A * the authentication, the LoginModule's <code>login</code> method will be 0N/A * <p> In the second phase, if the LoginContext's overall authentication 0N/A * succeeded (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL 0N/A * LoginModules succeeded), then the <code>commit</code> 0N/A * method for the <code>LoginModule</code> gets invoked. 0N/A * The <code>commit</code> method for a <code>LoginModule</code> checks its 0N/A * privately saved state to see if its own authentication succeeded. 0N/A * If the overall <code>LoginContext</code> authentication succeeded 0N/A * and the LoginModule's own authentication succeeded, then the 0N/A * <code>commit</code> method associates the relevant 0N/A * Principals (authenticated identities) and Credentials (authentication data 0N/A * such as cryptographic keys) with the <code>Subject</code> 0N/A * located within the <code>LoginModule</code>. 0N/A * <p> If the LoginContext's overall authentication failed (the relevant 0N/A * REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules did not succeed), 0N/A * then the <code>abort</code> method for each <code>LoginModule</code> 0N/A * any authentication state originally saved. 0N/A * <p> Logging out a <code>Subject</code> involves only one phase. 0N/A * The <code>LoginContext</code> invokes the LoginModule's <code>logout</code> 0N/A * method. The <code>logout</code> method for the <code>LoginModule</code> 0N/A * then performs the logout procedures, such as removing Principals or 0N/A * Credentials from the <code>Subject</code> or logging session information. 0N/A * <p> A <code>LoginModule</code> implementation must have a constructor with 0N/A * no arguments. This allows classes which load the <code>LoginModule</code> 0N/A * to instantiate it. 0N/A * @see javax.security.auth.login.LoginContext 0N/A * Initialize this LoginModule. 0N/A * <p> This method is called by the <code>LoginContext</code> 0N/A * after this <code>LoginModule</code> has been instantiated. 0N/A * The purpose of this method is to initialize this 0N/A * <code>LoginModule</code> with the relevant information. 0N/A * If this <code>LoginModule</code> does not understand 0N/A * any of the data stored in <code>sharedState</code> or 0N/A * <code>options</code> parameters, they can be ignored. 0N/A * @param subject the <code>Subject</code> to be authenticated. <p> 0N/A * @param callbackHandler a <code>CallbackHandler</code> for communicating 0N/A * with the end user (prompting for usernames and 0N/A * passwords, for example). <p> 0N/A * @param sharedState state shared with other configured LoginModules. <p> 0N/A * @param options options specified in the login 0N/A * <code>Configuration</code> for this particular 0N/A * <code>LoginModule</code>. 0N/A * Method to authenticate a <code>Subject</code> (phase 1). 0N/A * <p> The implementation of this method authenticates 0N/A * a <code>Subject</code>. For example, it may prompt for 0N/A * <code>Subject</code> information such 0N/A * as a username and password and then attempt to verify the password. 0N/A * This method saves the result of the authentication attempt 0N/A * as private state within the LoginModule. 0N/A * @exception LoginException if the authentication fails 0N/A * @return true if the authentication succeeded, or false if this 0N/A * <code>LoginModule</code> should be ignored. 0N/A * Method to commit the authentication process (phase 2). 0N/A * <p> This method is called if the LoginContext's 0N/A * overall authentication succeeded 0N/A * (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules 0N/A * <p> If this LoginModule's own authentication attempt 0N/A * succeeded (checked by retrieving the private state saved by the 0N/A * <code>login</code> method), then this method associates relevant 0N/A * Principals and Credentials with the <code>Subject</code> located in the 0N/A * <code>LoginModule</code>. If this LoginModule's own 0N/A * any state that was originally saved. 0N/A * @exception LoginException if the commit fails 0N/A * @return true if this method succeeded, or false if this 0N/A * <code>LoginModule</code> should be ignored. 0N/A * Method to abort the authentication process (phase 2). 0N/A * <p> This method is called if the LoginContext's 0N/A * overall authentication failed. 0N/A * (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules 0N/A * <p> If this LoginModule's own authentication attempt 0N/A * succeeded (checked by retrieving the private state saved by the 0N/A * <code>login</code> method), then this method cleans up any state 0N/A * that was originally saved. 0N/A * @exception LoginException if the abort fails 0N/A * @return true if this method succeeded, or false if this 0N/A * <code>LoginModule</code> should be ignored. 0N/A * Method which logs out a <code>Subject</code>. 0N/A * Principals and Credentials. 0N/A * @exception LoginException if the logout fails 0N/A * @return true if this method succeeded, or false if this 0N/A * <code>LoginModule</code> should be ignored.