1
2
3 /*
4 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
5 *
6 * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
7 *
8 * Portions Copyright Apache Software Foundation.
9 *
10 * The contents of this file are subject to the terms of either the GNU
11 * General Public License Version 2 only ("GPL") or the Common Development
12 * and Distribution License("CDDL") (collectively, the "License"). You
13 * may not use this file except in compliance with the License. You can obtain
14 * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
15 * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
16 * language governing permissions and limitations under the License.
17 *
18 * When distributing the software, include this License Header Notice in each
19 * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
20 * Sun designates this particular file as subject to the "Classpath" exception
21 * as provided by Sun in the GPL Version 2 section of the License file that
22 * accompanied this code. If applicable, add the following below the License
23 * Header, with the fields enclosed by brackets [] replaced by your own
24 * identifying information: "Portions Copyrighted [year]
25 * [name of copyright owner]"
26 *
27 * Contributor(s):
28 *
29 * If you wish your version of this file to be governed by only the CDDL or
30 * only the GPL Version 2, indicate your decision by adding "[Contributor]
31 * elects to include this software in this distribution under the [CDDL or GPL
32 * Version 2] license." If you don't indicate a single choice of license, a
33 * recipient has the option to distribute your version of this file under
34 * either the CDDL, the GPL Version 2 or to extend the choice of license to
35 * its licensees as provided above. However, if you add GPL Version 2 code
36 * and therefore, elected the GPL Version 2 license, then the option applies
37 * only if the new code is made subject to such option by the copyright
38 * holder.
39 */
40
41
42 package org.apache.catalina;
43
44 import java.beans.PropertyChangeListener;
45 import java.io.IOException;
46 import java.security.Principal;
47 import java.security.cert.X509Certificate;
48 import java.util.List;
49
50 import org.apache.catalina.deploy.SecurityConstraint;
51 /**
52 * A <b>Realm</b> is a read-only facade for an underlying security realm
53 * used to authenticate individual users, and identify the security roles
54 * associated with those users. Realms can be attached at any Container
55 * level, but will typically only be attached to a Context, or higher level,
56 * Container.
57 *
58 * @author Craig R. McClanahan
59 * @version $Revision: 1.7 $ $Date: 2007/05/05 05:31:51 $
60 */
61
62 public interface Realm {
63
64 // ------------------------------------------------------------- Constants
65
66 //START SJSAS 6202703
67 /**
68 * Flag indicating authentication is needed for current request. Used by
69 * preAuthenticateCheck method.
70 */
71 public static final int AUTHENTICATE_NEEDED = 1;
72
73 /**
74 * Flag indicating authentication is not needed for current request. Used
75 * by preAuthenticateCheck method.
76 */
77 public static final int AUTHENTICATE_NOT_NEEDED = 0;
78
79 /**
80 * Flag indicating the user has been authenticated but been denied access
81 * to the requested resource.
82 */
83 public static final int AUTHENTICATED_NOT_AUTHORIZED = -1;
84
85 //END SJSAS 6202703
86
87 // ------------------------------------------------------------- Properties
88
89
90 /**
91 * Return the Container with which this Realm has been associated.
92 */
93 public Container getContainer();
94
95
96 /**
97 * Set the Container with which this Realm has been associated.
98 *
99 * @param container The associated Container
100 */
101 public void setContainer(Container container);
102
103
104 /**
105 * Return descriptive information about this Realm implementation and
106 * the corresponding version number, in the format
107 * <code><description>/<version></code>.
108 */
109 public String getInfo();
110
111
112 // --------------------------------------------------------- Public Methods
113
114
115 /**
116 * Add a property change listener to this component.
117 *
118 * @param listener The listener to add
119 */
120 public void addPropertyChangeListener(PropertyChangeListener listener);
121
122
123 /**
124 * Return the Principal associated with the specified username and
125 * credentials, if there is one; otherwise return <code>null</code>.
126 *
127 * @param username Username of the Principal to look up
128 * @param credentials Password or other credentials to use in
129 * authenticating this username
130 */
131 public Principal authenticate(String username, String credentials);
132
133
134 /**
135 * Return the Principal associated with the specified username and
136 * credentials, if there is one; otherwise return <code>null</code>.
137 *
138 * @param username Username of the Principal to look up
139 * @param credentials Password or other credentials to use in
140 * authenticating this username
141 */
142 public Principal authenticate(String username, byte[] credentials);
143
144
145 /**
146 * Return the Principal associated with the specified username, which
147 * matches the digest calculated using the given parameters using the
148 * method described in RFC 2069; otherwise return <code>null</code>.
149 *
150 * @param username Username of the Principal to look up
151 * @param digest Digest which has been submitted by the client
152 * @param nonce Unique (or supposedly unique) token which has been used
153 * for this request
154 * @param realm Realm name
155 * @param md5a2 Second MD5 digest used to calculate the digest :
156 * MD5(Method + ":" + uri)
157 */
158 public Principal authenticate(String username, String digest,
159 String nonce, String nc, String cnonce,
160 String qop, String realm,
161 String md5a2);
162
163
164 /**
165 * Return the Principal associated with the specified chain of X509
166 * client certificates. If there is none, return <code>null</code>.
167 *
168 * @param certs Array of client certificates, with the first one in
169 * the array being the certificate of the client itself.
170 */
171 public Principal authenticate(X509Certificate certs[]);
172
173 /**
174 * Return the SecurityConstraints configured to guard the request URI for
175 * this request, or <code>null</code> if there is no such constraint.
176 *
177 * @param request Request we are processing
178 */
179 public SecurityConstraint [] findSecurityConstraints(HttpRequest request,
180 Context context);
181 /**
182 * Perform access control based on the specified authorization constraint.
183 * Return <code>true</code> if this constraint is satisfied and processing
184 * should continue, or <code>false</code> otherwise.
185 *
186 * @param request Request we are processing
187 * @param response Response we are creating
188 * @param constraint Security constraint we are enforcing
189 * @param The Context to which client of this class is attached.
190 *
191 * @exception IOException if an input/output error occurs
192 */
193 public boolean hasResourcePermission(HttpRequest request,
194 HttpResponse response,
195 SecurityConstraint[] constraint,
196 Context context)
197 throws IOException;
198
199
200 /**
201 * Return <code>true</code> if the specified Principal has the specified
202 * security role, within the context of this Realm; otherwise return
203 * <code>false</code>.
204 *
205 * @param principal Principal for whom the role is to be checked
206 * @param role Security role to be checked
207 */
208 public boolean hasRole(Principal principal, String role);
209
210 //START SJSAS 6232464
211 /**
212 * Return <code>true</code> if the specified Principal has the specified
213 * security role, within the context of this Realm; otherwise return
214 * <code>false</code>.
215 *
216 * @param request Request we are processing
217 * @param response Response we are creating
218 * @param principal Principal for whom the role is to be checked
219 * @param role Security role to be checked
220 */
221 public boolean hasRole(HttpRequest request,
222 HttpResponse response,
223 Principal principal,
224 String role);
225 //END SJSAS 6232464
226
227 //START SJSAS 6202703
228 /**
229 * Checks whether or not authentication is needed.
230 * Returns an int, one of AUTHENTICATE_NOT_NEEDED, AUTHENTICATE_NEEDED,
231 * or AUTHENTICATED_NOT_AUTHORIZED.
232 *
233 * @param request Request we are processing
234 * @param response Response we are creating
235 * @param constraints Security constraint we are enforcing
236 * @param disableProxyCaching whether or not to disable proxy caching for
237 * protected resources.
238 * @param securePagesWithPragma true if we add headers which
239 * are incompatible with downloading office documents in IE under SSL but
240 * which fix a caching problem in Mozill
241 * @param ssoEnabled true if sso is enabled
242 * @exception IOException if an input/output error occurs
243 */
244 public int preAuthenticateCheck(HttpRequest request,
245 HttpResponse response,
246 SecurityConstraint[] constraints,
247 boolean disableProxyCaching,
248 boolean securePagesWithPragma,
249 boolean ssoEnabled)
250 throws IOException;
251
252
253 /**
254 * Authenticates the user making this request, based on the specified
255 * login configuration. Return <code>true</code> if any specified
256 * requirements have been satisfied, or <code>false</code> if we have
257 * created a response challenge already.
258 *
259 * @param request Request we are processing
260 * @param response Response we are creating
261 * @param context The Context to which client of this class is attached.
262 * @param authenticator the current authenticator.
263 * @exception IOException if an input/output error occurs
264 */
265 public boolean invokeAuthenticateDelegate(HttpRequest request,
266 HttpResponse response,
267 Context context,
268 Authenticator authenticator)
269 throws IOException;
270
271 /**
272 * Post authentication for given request and response.
273 *
274 * @param request Request we are processing
275 * @param response Response we are creating
276 * @param context The Context to which client of this class is attached.
277 * @exception IOException if an input/output error occurs
278 */
279 public boolean invokePostAuthenticateDelegate(HttpRequest request,
280 HttpResponse response,
281 Context context)
282 throws IOException;
283
284 //END SJSAS 6202703
285
286 /**
287 * Enforce any user data constraint required by the security constraint
288 * guarding this request URI. Return <code>true</code> if this constraint
289 * was not violated and processing should continue, or <code>false</code>
290 * if we have created a response already.
291 *
292 * @param request Request we are processing
293 * @param response Response we are creating
294 * @param constraint Security constraint being checked
295 *
296 * @exception IOException if an input/output error occurs
297 */
298 public boolean hasUserDataPermission(HttpRequest request,
299 HttpResponse response,
300 SecurityConstraint[] constraint)
301 throws IOException;
302
303 /**
304 * Remove a property change listener from this component.
305 *
306 * @param listener The listener to remove
307 */
308 public void removePropertyChangeListener(PropertyChangeListener listener);
309
310
311 // BEGIN IASRI 4808401, 4934562
312 /**
313 * Return an alternate principal from the request if available.
314 *
315 * @param req The request object.
316 * @return Alternate principal or null.
317 */
318 public Principal getAlternatePrincipal(HttpRequest req);
319
320
321 /**
322 * Return an alternate auth type from the request if available.
323 *
324 * @param req The request object.
325 * @return Alternate auth type or null.
326 */
327 public String getAlternateAuthType(HttpRequest req);
328 // END IASRI 4808401
329
330
331 // BEGIN IASRI 4856062,4918627,4874504
332 /**
333 * Set the name of the associated realm.
334 *
335 * @param name the name of the realm.
336 */
337 public void setRealmName(String name, String authMethod);
338
339
340 /**
341 * Returns the name of the associated realm.
342 *
343 * @return realm name or null if not set.
344 */
345 public String getRealmName();
346 // END IASRI 4856062,4918627,4874504
347 }
Save This Page