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