/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.catalina;
import java.beans.PropertyChangeListener;
import java.io.IOException;
import java.security.Principal;
import java.security.cert.X509Certificate;
import org.apache.catalina.connector.Request;
import org.apache.catalina.connector.Response;
import org.apache.catalina.deploy.SecurityConstraint;
/**
* A <b>Realm</b> is a read-only facade for an underlying security realm
* used to authenticate individual users, and identify the security roles
* associated with those users. Realms can be attached at any Container
* level, but will typically only be attached to a Context, or higher level,
* Container.
*
* @author Craig R. McClanahan
*
*/
public interface Realm {
// ------------------------------------------------------------- Properties
/**
* Return the Container with which this Realm has been associated.
*/
public Container getContainer();
/**
* Set the Container with which this Realm has been associated.
*
* @param container The associated Container
*/
public void setContainer(Container container);
/**
* Return descriptive information about this Realm implementation and
* the corresponding version number, in the format
* <code><description>/<version></code>.
*/
public String getInfo();
// --------------------------------------------------------- Public Methods
/**
* Add a property change listener to this component.
*
* @param listener The listener to add
*/
public void addPropertyChangeListener(PropertyChangeListener listener);
/**
* Return the Principal associated with the specified username and
* credentials, if there is one; otherwise return <code>null</code>.
*
* @param username Username of the Principal to look up
* @param credentials Password or other credentials to use in
* authenticating this username
*/
public Principal authenticate(String username, String credentials);
/**
* Return the Principal associated with the specified username and
* credentials, if there is one; otherwise return <code>null</code>.
*
* @param username Username of the Principal to look up
* @param credentials Password or other credentials to use in
* authenticating this username
*/
public Principal authenticate(String username, byte[] credentials);
/**
* Return the Principal associated with the specified username, which
* matches the digest calculated using the given parameters using the
* method described in RFC 2069; otherwise return <code>null</code>.
*
* @param username Username of the Principal to look up
* @param digest Digest which has been submitted by the client
* @param nonce Unique (or supposedly unique) token which has been used
* for this request
* @param realm Realm name
* @param md5a2 Second MD5 digest used to calculate the digest :
* MD5(Method + ":" + uri)
*/
public Principal authenticate(String username, String digest,
String nonce, String nc, String cnonce,
String qop, String realm,
String md5a2);
/**
* Return the Principal associated with the specified chain of X509
* client certificates. If there is none, return <code>null</code>.
*
* @param certs Array of client certificates, with the first one in
* the array being the certificate of the client itself.
*/
public Principal authenticate(X509Certificate certs[]);
/**
* Execute a periodic task, such as reloading, etc. This method will be
* invoked inside the classloading context of this container. Unexpected
* throwables will be caught and logged.
*/
public void backgroundProcess();
/**
* Return the SecurityConstraints configured to guard the request URI for
* this request, or <code>null</code> if there is no such constraint.
*
* @param request Request we are processing
*/
public SecurityConstraint [] findSecurityConstraints(Request request,
Context context);
/**
* Perform access control based on the specified authorization constraint.
* Return <code>true</code> if this constraint is satisfied and processing
* should continue, or <code>false</code> otherwise.
*
* @param request Request we are processing
* @param response Response we are creating
* @param constraint Security constraint we are enforcing
* @param context The Context to which client of this class is attached.
*
* @exception IOException if an input/output error occurs
*/
public boolean hasResourcePermission(Request request,
Response response,
SecurityConstraint [] constraint,
Context context)
throws IOException;
/**
* Return <code>true</code> if the specified Principal has the specified
* security role, within the context of this Realm; otherwise return
* <code>false</code>.
*
* @param principal Principal for whom the role is to be checked
* @param role Security role to be checked
*/
public boolean hasRole(Principal principal, String role);
/**
* Enforce any user data constraint required by the security constraint
* guarding this request URI. Return <code>true</code> if this constraint
* was not violated and processing should continue, or <code>false</code>
* if we have created a response already.
*
* @param request Request we are processing
* @param response Response we are creating
* @param constraint Security constraint being checked
*
* @exception IOException if an input/output error occurs
*/
public boolean hasUserDataPermission(Request request,
Response response,
SecurityConstraint []constraint)
throws IOException;
/**
* Remove a property change listener from this component.
*
* @param listener The listener to remove
*/
public void removePropertyChangeListener(PropertyChangeListener listener);
}