## org.apache.catalina.realm
Class JAASMemoryLoginModule

    java.lang.Object
      org.apache.catalina.realm.JAASMemoryLoginModule

All Implemented Interfaces:
  javax.security.auth.spi.LoginModule, Realm

public class JAASMemoryLoginModule
extends java.lang.Object
implements javax.security.auth.spi.LoginModule, Realm

Implementation of the JAAS LoginModule interface, primarily for use in testing `JAASRealm`. It utilizes an XML-format data file of username/password/role information identical to that supported by `org.apache.catalina.realm.MemoryRealm` (except that digested passwords are not supported).

This class recognizes the following string-valued options, which are specified in the configuration file (and passed to our constructor in the `options` argument:

- debug - Set to "true" to get debugging messages generated to System.out. The default value is `false`.
- pathname - Relative (to the pathname specified by the "catalina.base" system property) or absolute pahtname to the XML file containing our user information, in the format supported by `MemoryRealm`. The default value matches the MemoryRealm default.

IMPLEMENTATION NOTE - This class implements `Realm` only to satisfy the calling requirements of the `GenericPrincipal` constructor. It does not actually perform the functionality required of a `Realm` implementation.

Version:
  $Revision: 1.2 $ $Date: 2004/08/26 21:37:21 $
Author:
  Craig R. McClanahan

Field Summary
`protected javax.security.auth.callback.CallbackHandler` `callbackHandler` The callback handler responsible for answering our requests.
`protected boolean` `committed` Has our own `commit()` returned successfully?
`protected boolean` `debug` Should we log debugging messages?
`protected java.util.Map` `options` The configuration information for this `LoginModule`.
`protected java.lang.String` `pathname` The absolute or relative pathname to the XML configuration file.
`protected java.security.Principal` `principal` The `Principal` identified by our validation, or `null` if validation falied.
`protected java.util.HashMap` `principals` The set of `Principals` loaded from our configuration file.
`protected java.util.Map` `sharedState` The state information that is shared with other configured `LoginModule` instances.
`protected javax.security.auth.Subject` `subject` The subject for which we are performing authentication.

Constructor Summary
`JAASMemoryLoginModule()`

Method Summary
`boolean` `abort()` Phase 2 of authenticating a `Subject` when Phase 1 fails.
`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.
`boolean` `commit()` Phase 2 of authenticating a `Subject` when Phase 1 was successful.
`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` `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`.
`void` `initialize(javax.security.auth.Subject subject, javax.security.auth.callback.CallbackHandler callbackHandler, java.util.Map sharedState, java.util.Map options)` Initialize this `LoginModule` with the specified configuration information.
`protected void` `load()` Load the contents of our configuration file.
`protected void` `log(java.lang.String message)` Log a message.
`protected void` `log(java.lang.String message, java.lang.Throwable exception)` Log a message and associated exception.
`boolean` `login()` Phase 1 of authenticating a `Subject`.
`boolean` `logout()` Log out this user.
`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.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### callbackHandler

    protected javax.security.auth.callback.CallbackHandler callbackHandler

  The callback handler responsible for answering our requests.

### committed

    protected boolean committed

  Has our own `commit()` returned successfully?

### debug

    protected boolean debug

  Should we log debugging messages?

### options

    protected java.util.Map options

  The configuration information for this `LoginModule`.

### pathname

    protected java.lang.String pathname

  The absolute or relative pathname to the XML configuration file.

### principal

    protected java.security.Principal principal

  The `Principal` identified by our validation, or `null` if validation falied.

### principals

    protected java.util.HashMap principals

  The set of `Principals` loaded from our configuration file.

### sharedState

    protected java.util.Map sharedState

  The state information that is shared with other configured `LoginModule` instances.

### subject

    protected javax.security.auth.Subject subject

  The subject for which we are performing authentication.

Constructor Detail

### JAASMemoryLoginModule

    public JAASMemoryLoginModule()

Method Detail

### abort

    public boolean abort()
                  throws javax.security.auth.login.LoginException

  Phase 2 of authenticating a `Subject` when Phase 1 fails. This method is called if the `LoginContext` failed somewhere in the overall authentication chain.

  Specified by:
    `abort` in interface `javax.security.auth.spi.LoginModule`
  Returns:
    `true` if this method succeeded, or `false` if this `LoginModule` should be ignored
  Throws:
    `javax.security.auth.login.LoginException` - if the abort fails

### commit

    public boolean commit()
                   throws javax.security.auth.login.LoginException

  Phase 2 of authenticating a `Subject` when Phase 1 was successful. This method is called if the `LoginContext` succeeded in the overall authentication chain.

  Specified by:
    `commit` in interface `javax.security.auth.spi.LoginModule`
  Returns:
    `true` if the authentication succeeded, or `false` if this `LoginModule` should be ignored
  Throws:
    `javax.security.auth.login.LoginException` - if the commit fails

### initialize

    public void initialize(javax.security.auth.Subject subject,
                           javax.security.auth.callback.CallbackHandler callbackHandler,
                           java.util.Map sharedState,
                           java.util.Map options)

  Initialize this `LoginModule` with the specified configuration information.

  Specified by:
    `initialize` in interface `javax.security.auth.spi.LoginModule`
  Parameters:
    `subject` - The `Subject` to be authenticated
    `callbackHandler` - A `CallbackHandler` for communicating with the end user as necessary
    `sharedState` - State information shared with other `LoginModule` instances
    `options` - Configuration information for this specific `LoginModule` instance

### login

    public boolean login()
                  throws javax.security.auth.login.LoginException

  Phase 1 of authenticating a `Subject`.

  Specified by:
    `login` in interface `javax.security.auth.spi.LoginModule`
  Returns:
    `true` if the authentication succeeded, or `false` if this `LoginModule` should be ignored
  Throws:
    `javax.security.auth.login.LoginException` - if the authentication fails

### logout

    public boolean logout()
                   throws javax.security.auth.login.LoginException

  Log out this user.

  Specified by:
    `logout` in interface `javax.security.auth.spi.LoginModule`
  Returns:
    `true` in all cases because thie `LoginModule` should not be ignored
  Throws:
    `javax.security.auth.login.LoginException` - if logging out failed

### getContainer

    public Container getContainer()

  Return the Container with which this Realm has been associated.

  Specified by:
    `getContainer` in interface `Realm`

### setContainer

    public void setContainer(Container container)

  Set the Container with which this Realm has been associated.

  Specified by:
    `setContainer` in interface `Realm`
  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>`.

  Specified by:
    `getInfo` in interface `Realm`

### addPropertyChangeListener

    public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

  Add a property change listener to this component.

  Specified by:
    `addPropertyChangeListener` in interface `Realm`
  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`.

  Specified by:
    `authenticate` in interface `Realm`
  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`.

  Specified by:
    `authenticate` in interface `Realm`
  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`.

  Specified by:
    `authenticate` in interface `Realm`
  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`.

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

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

  Specified by:
    `hasRole` in interface `Realm`
  Parameters:
    `principal` - Principal for whom the role is to be checked
    `role` - Security role to be checked

### removePropertyChangeListener

    public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

  Remove a property change listener from this component.

  Specified by:
    `removePropertyChangeListener` in interface `Realm`
  Parameters:
    `listener` - The listener to remove

### load

    protected void load()

  Load the contents of our configuration file.

### log

    protected void log(java.lang.String message)

  Log a message.

  Parameters:
    `message` - The message to be logged

### log

    protected void log(java.lang.String message,
                       java.lang.Throwable exception)

  Log a message and associated exception.

  Parameters:
    `message` - The message to be logged
    `exception` - The associated exception

Copyright ? 2000-2002 Apache Software Foundation. All Rights Reserved.