Realm


1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    * 
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   * 
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  
19  package org.apache.catalina;
20  
21  import java.beans.PropertyChangeListener  ;
22  import java.io.IOException  ;
23  import java.security.Principal  ;
24  import java.security.cert.X509Certificate  ;
25  
26  import org.apache.catalina.connector.Request;
27  import org.apache.catalina.connector.Response;
28  import org.apache.catalina.deploy.SecurityConstraint;
29  /**
30   * A <b>Realm</b> is a read-only facade for an underlying security realm
31   * used to authenticate individual users, and identify the security roles
32   * associated with those users.  Realms can be attached at any Container
33   * level, but will typically only be attached to a Context, or higher level,
34   * Container.
35   *
36   * @author Craig R. McClanahan
37   * @version $Revision: 467222 $ $Date: 2006-10-24 05:17:11 +0200 (mar., 24 oct. 2006) $
38   */
39  
40  public interface Realm {
41  
42  
43      // ------------------------------------------------------------- Properties
44  
45  
46      /**
47       * Return the Container with which this Realm has been associated.
48       */
49      public Container getContainer();
50  
51  
52      /**
53       * Set the Container with which this Realm has been associated.
54       *
55       * @param container The associated Container
56       */
57      public void setContainer(Container container);
58  
59  
60      /**
61       * Return descriptive information about this Realm implementation and
62       * the corresponding version number, in the format
63       * <code>&lt;description&gt;/&lt;version&gt;</code>.
64       */
65      public String   getInfo();
66  
67  
68      // --------------------------------------------------------- Public Methods
69  
70      
71      /**
72       * Add a property change listener to this component.
73       *
74       * @param listener The listener to add
75       */
76      public void addPropertyChangeListener(PropertyChangeListener   listener);
77  
78  
79      /**
80       * Return the Principal associated with the specified username and
81       * credentials, if there is one; otherwise return <code>null</code>.
82       *
83       * @param username Username of the Principal to look up
84       * @param credentials Password or other credentials to use in
85       *  authenticating this username
86       */
87      public Principal   authenticate(String   username, String   credentials);
88  
89  
90      /**
91       * Return the Principal associated with the specified username and
92       * credentials, if there is one; otherwise return <code>null</code>.
93       *
94       * @param username Username of the Principal to look up
95       * @param credentials Password or other credentials to use in
96       *  authenticating this username
97       */
98      public Principal   authenticate(String   username, byte[] credentials);
99  
100 
101     /**
102      * Return the Principal associated with the specified username, which
103      * matches the digest calculated using the given parameters using the
104      * method described in RFC 2069; otherwise return <code>null</code>.
105      *
106      * @param username Username of the Principal to look up
107      * @param digest Digest which has been submitted by the client
108      * @param nonce Unique (or supposedly unique) token which has been used
109      * for this request
110      * @param realm Realm name
111      * @param md5a2 Second MD5 digest used to calculate the digest :
112      * MD5(Method + ":" + uri)
113      */
114     public Principal   authenticate(String   username, String   digest,
115                                   String   nonce, String   nc, String   cnonce,
116                                   String   qop, String   realm,
117                                   String   md5a2);
118 
119 
120     /**
121      * Return the Principal associated with the specified chain of X509
122      * client certificates.  If there is none, return <code>null</code>.
123      *
124      * @param certs Array of client certificates, with the first one in
125      *  the array being the certificate of the client itself.
126      */
127     public Principal   authenticate(X509Certificate   certs[]);
128     
129     
130     /**
131      * Execute a periodic task, such as reloading, etc. This method will be
132      * invoked inside the classloading context of this container. Unexpected
133      * throwables will be caught and logged.
134      */
135     public void backgroundProcess();
136 
137 
138     /**
139      * Return the SecurityConstraints configured to guard the request URI for
140      * this request, or <code>null</code> if there is no such constraint.
141      *
142      * @param request Request we are processing
143      */
144     public SecurityConstraint [] findSecurityConstraints(Request request,
145                                                      Context context);
146     
147     
148     /**
149      * Perform access control based on the specified authorization constraint.
150      * Return <code>true</code> if this constraint is satisfied and processing
151      * should continue, or <code>false</code> otherwise.
152      *
153      * @param request Request we are processing
154      * @param response Response we are creating
155      * @param constraint Security constraint we are enforcing
156      * @param context The Context to which client of this class is attached.
157      *
158      * @exception IOException if an input/output error occurs
159      */
160     public boolean hasResourcePermission(Request request,
161                                          Response response,
162                                          SecurityConstraint [] constraint,
163                                          Context context)
164         throws IOException  ;
165     
166     
167     /**
168      * Return <code>true</code> if the specified Principal has the specified
169      * security role, within the context of this Realm; otherwise return
170      * <code>false</code>.
171      *
172      * @param principal Principal for whom the role is to be checked
173      * @param role Security role to be checked
174      */
175     public boolean hasRole(Principal   principal, String   role);
176 
177         /**
178      * Enforce any user data constraint required by the security constraint
179      * guarding this request URI.  Return <code>true</code> if this constraint
180      * was not violated and processing should continue, or <code>false</code>
181      * if we have created a response already.
182      *
183      * @param request Request we are processing
184      * @param response Response we are creating
185      * @param constraint Security constraint being checked
186      *
187      * @exception IOException if an input/output error occurs
188      */
189     public boolean hasUserDataPermission(Request request,
190                                          Response response,
191                                          SecurityConstraint []constraint)
192         throws IOException  ;
193     
194     /**
195      * Remove a property change listener from this component.
196      *
197      * @param listener The listener to remove
198      */
199     public void removePropertyChangeListener(PropertyChangeListener   listener);
200 
201 
202 }
203
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags