001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package org.apache.catalina;
019:
020: import java.beans.PropertyChangeListener;
021: import java.io.IOException;
022: import java.security.Principal;
023: import java.security.cert.X509Certificate;
024:
025: import org.apache.catalina.connector.Request;
026: import org.apache.catalina.connector.Response;
027: import org.apache.catalina.deploy.SecurityConstraint;
028:
029: /**
030: * A <b>Realm</b> is a read-only facade for an underlying security realm
031: * used to authenticate individual users, and identify the security roles
032: * associated with those users. Realms can be attached at any Container
033: * level, but will typically only be attached to a Context, or higher level,
034: * Container.
035: *
036: * @author Craig R. McClanahan
037: * @version $Revision: 467222 $ $Date: 2006-10-24 05:17:11 +0200 (mar., 24 oct. 2006) $
038: */
039:
040: public interface Realm {
041:
042: // ------------------------------------------------------------- Properties
043:
044: /**
045: * Return the Container with which this Realm has been associated.
046: */
047: public Container getContainer();
048:
049: /**
050: * Set the Container with which this Realm has been associated.
051: *
052: * @param container The associated Container
053: */
054: public void setContainer(Container container);
055:
056: /**
057: * Return descriptive information about this Realm implementation and
058: * the corresponding version number, in the format
059: * <code><description>/<version></code>.
060: */
061: public String getInfo();
062:
063: // --------------------------------------------------------- Public Methods
064:
065: /**
066: * Add a property change listener to this component.
067: *
068: * @param listener The listener to add
069: */
070: public void addPropertyChangeListener(
071: PropertyChangeListener listener);
072:
073: /**
074: * Return the Principal associated with the specified username and
075: * credentials, if there is one; otherwise return <code>null</code>.
076: *
077: * @param username Username of the Principal to look up
078: * @param credentials Password or other credentials to use in
079: * authenticating this username
080: */
081: public Principal authenticate(String username, String credentials);
082:
083: /**
084: * Return the Principal associated with the specified username and
085: * credentials, if there is one; otherwise return <code>null</code>.
086: *
087: * @param username Username of the Principal to look up
088: * @param credentials Password or other credentials to use in
089: * authenticating this username
090: */
091: public Principal authenticate(String username, byte[] credentials);
092:
093: /**
094: * Return the Principal associated with the specified username, which
095: * matches the digest calculated using the given parameters using the
096: * method described in RFC 2069; otherwise return <code>null</code>.
097: *
098: * @param username Username of the Principal to look up
099: * @param digest Digest which has been submitted by the client
100: * @param nonce Unique (or supposedly unique) token which has been used
101: * for this request
102: * @param realm Realm name
103: * @param md5a2 Second MD5 digest used to calculate the digest :
104: * MD5(Method + ":" + uri)
105: */
106: public Principal authenticate(String username, String digest,
107: String nonce, String nc, String cnonce, String qop,
108: String realm, String md5a2);
109:
110: /**
111: * Return the Principal associated with the specified chain of X509
112: * client certificates. If there is none, return <code>null</code>.
113: *
114: * @param certs Array of client certificates, with the first one in
115: * the array being the certificate of the client itself.
116: */
117: public Principal authenticate(X509Certificate certs[]);
118:
119: /**
120: * Execute a periodic task, such as reloading, etc. This method will be
121: * invoked inside the classloading context of this container. Unexpected
122: * throwables will be caught and logged.
123: */
124: public void backgroundProcess();
125:
126: /**
127: * Return the SecurityConstraints configured to guard the request URI for
128: * this request, or <code>null</code> if there is no such constraint.
129: *
130: * @param request Request we are processing
131: */
132: public SecurityConstraint[] findSecurityConstraints(
133: Request request, Context context);
134:
135: /**
136: * Perform access control based on the specified authorization constraint.
137: * Return <code>true</code> if this constraint is satisfied and processing
138: * should continue, or <code>false</code> otherwise.
139: *
140: * @param request Request we are processing
141: * @param response Response we are creating
142: * @param constraint Security constraint we are enforcing
143: * @param context The Context to which client of this class is attached.
144: *
145: * @exception IOException if an input/output error occurs
146: */
147: public boolean hasResourcePermission(Request request,
148: Response response, SecurityConstraint[] constraint,
149: Context context) throws IOException;
150:
151: /**
152: * Return <code>true</code> if the specified Principal has the specified
153: * security role, within the context of this Realm; otherwise return
154: * <code>false</code>.
155: *
156: * @param principal Principal for whom the role is to be checked
157: * @param role Security role to be checked
158: */
159: public boolean hasRole(Principal principal, String role);
160:
161: /**
162: * Enforce any user data constraint required by the security constraint
163: * guarding this request URI. Return <code>true</code> if this constraint
164: * was not violated and processing should continue, or <code>false</code>
165: * if we have created a response already.
166: *
167: * @param request Request we are processing
168: * @param response Response we are creating
169: * @param constraint Security constraint being checked
170: *
171: * @exception IOException if an input/output error occurs
172: */
173: public boolean hasUserDataPermission(Request request,
174: Response response, SecurityConstraint[] constraint)
175: throws IOException;
176:
177: /**
178: * Remove a property change listener from this component.
179: *
180: * @param listener The listener to remove
181: */
182: public void removePropertyChangeListener(
183: PropertyChangeListener listener);
184:
185: }
|