/*

 * 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>&lt;description&gt;/&lt;version&gt;</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);

}