History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/javax/security/auth/spi/LoginModule.java (1 of 18352 files). Show all

Unified · Split

java/pkg/javax/security/auth/spi/LoginModule.java+240−0
@@ -0,0 +1,240 @@
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+}

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t