## org.apache.catalina
Interface Realm

All Known Implementing Classes:
  JAASMemoryLoginModule, RealmBase

public interface Realm

A Realm 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.

Version:
  $Revision: 1.8 $ $Date: 2004/05/26 15:28:28 $
Author:
  Craig R. McClanahan

Method Summary
`void` `addPropertyChangeListener(java.beans.PropertyChangeListener listener)` Add a property change listener to this component.
`java.security.Principal` `authenticate(java.lang.String username, byte[] credentials)` Return the Principal associated with the specified username and credentials, if there is one; otherwise return `null`.
`java.security.Principal` `authenticate(java.lang.String username, java.lang.String credentials)` Return the Principal associated with the specified username and credentials, if there is one; otherwise return `null`.

`java.security.Principal`

`authenticate(java.lang.String username, java.lang.String digest, java.lang.String nonce, java.lang.String nc, java.lang.String cnonce, java.lang.String qop, java.lang.String realm, java.lang.String md5a2)`
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 `null`.

`java.security.Principal` `authenticate(java.security.cert.X509Certificate[] certs)` Return the Principal associated with the specified chain of X509 client certificates.
`SecurityConstraint[]` `findSecurityConstraints(HttpRequest request, Context context)` Return the SecurityConstraints configured to guard the request URI for this request, or `null` if there is no such constraint.
`Container` `getContainer()` Return the Container with which this Realm has been associated.
`java.lang.String` `getInfo()` Return descriptive information about this Realm implementation and the corresponding version number, in the format `<description>/<version>`.
`boolean` `hasResourcePermission(HttpRequest request, HttpResponse response, SecurityConstraint[] constraint, Context context)` Perform access control based on the specified authorization constraint.
`boolean` `hasRole(java.security.Principal principal, java.lang.String role)` Return `true` if the specified Principal has the specified security role, within the context of this Realm; otherwise return `false`.
`boolean` `hasUserDataPermission(HttpRequest request, HttpResponse response, SecurityConstraint[] constraint)` Enforce any user data constraint required by the security constraint guarding this request URI.
`void` `removePropertyChangeListener(java.beans.PropertyChangeListener listener)` Remove a property change listener from this component.
`void` `setContainer(Container container)` Set the Container with which this Realm has been associated.

Method Detail

### getContainer

    public Container getContainer()

  Return the Container with which this Realm has been associated.

### setContainer

    public void setContainer(Container container)

  Set the Container with which this Realm has been associated.

  Parameters:
    `container` - The associated Container

### getInfo

    public java.lang.String getInfo()

  Return descriptive information about this Realm implementation and the corresponding version number, in the format `<description>/<version>`.

### addPropertyChangeListener

    public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

  Add a property change listener to this component.

  Parameters:
    `listener` - The listener to add

### authenticate

    public java.security.Principal authenticate(java.lang.String username,
                                                java.lang.String credentials)

  Return the Principal associated with the specified username and credentials, if there is one; otherwise return `null`.

  Parameters:
    `username` - Username of the Principal to look up
    `credentials` - Password or other credentials to use in authenticating this username

### authenticate

    public java.security.Principal authenticate(java.lang.String username,
                                                byte[] credentials)

  Return the Principal associated with the specified username and credentials, if there is one; otherwise return `null`.

  Parameters:
    `username` - Username of the Principal to look up
    `credentials` - Password or other credentials to use in authenticating this username

### authenticate

    public java.security.Principal authenticate(java.lang.String username,
                                                java.lang.String digest,
                                                java.lang.String nonce,
                                                java.lang.String nc,
                                                java.lang.String cnonce,
                                                java.lang.String qop,
                                                java.lang.String realm,
                                                java.lang.String md5a2)

  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 `null`.

  Parameters:
    `username` - Username of the Principal to look up
    `digest` - Digest which has been submitted by the client
    `nonce` - Unique (or supposedly unique) token which has been used for this request
    `realm` - Realm name
    `md5a2` - Second MD5 digest used to calculate the digest : MD5(Method + ":" + uri)

### authenticate

    public java.security.Principal authenticate(java.security.cert.X509Certificate[] certs)

  Return the Principal associated with the specified chain of X509 client certificates. If there is none, return `null`.

  Parameters:
    `certs` - Array of client certificates, with the first one in the array being the certificate of the client itself.

### findSecurityConstraints

    public SecurityConstraint[] findSecurityConstraints(HttpRequest request,
                                                        Context context)

  Return the SecurityConstraints configured to guard the request URI for this request, or `null` if there is no such constraint.

  Parameters:
    `request` - Request we are processing

### hasResourcePermission

    public boolean hasResourcePermission(HttpRequest request,
                                         HttpResponse response,
                                         SecurityConstraint[] constraint,
                                         Context context)
                                  throws java.io.IOException

  Perform access control based on the specified authorization constraint. Return `true` if this constraint is satisfied and processing should continue, or `false` otherwise.

  Parameters:
    `request` - Request we are processing
    `response` - Response we are creating
    `constraint` - Security constraint we are enforcing
    `context` - The Context to which client of this class is attached.
  Throws:
    `java.io.IOException` - if an input/output error occurs

### hasRole

    public boolean hasRole(java.security.Principal principal,
                           java.lang.String role)

  Return `true` if the specified Principal has the specified security role, within the context of this Realm; otherwise return `false`.

  Parameters:
    `principal` - Principal for whom the role is to be checked
    `role` - Security role to be checked

### hasUserDataPermission

    public boolean hasUserDataPermission(HttpRequest request,
                                         HttpResponse response,
                                         SecurityConstraint[] constraint)
                                  throws java.io.IOException

  Enforce any user data constraint required by the security constraint guarding this request URI. Return `true` if this constraint was not violated and processing should continue, or `false` if we have created a response already.

  Parameters:
    `request` - Request we are processing
    `response` - Response we are creating
    `constraint` - Security constraint being checked
  Throws:
    `java.io.IOException` - if an input/output error occurs

### removePropertyChangeListener

    public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

  Remove a property change listener from this component.

  Parameters:
    `listener` - The listener to remove

Copyright © 2000-2003 Apache Software Foundation. All Rights Reserved.