Apache Tomcat 6.0.43

org.apache.catalina.realm
Class LockOutRealm

java.lang.Object
  extended by org.apache.catalina.realm.RealmBase
      extended by org.apache.catalina.realm.CombinedRealm
          extended by org.apache.catalina.realm.LockOutRealm
All Implemented Interfaces:
javax.management.MBeanRegistration, Lifecycle, Realm

public class LockOutRealm
extends CombinedRealm

This class extends the CombinedRealm (hence it can wrap other Realms) to provide a user lock out mechanism if there are too many failed authentication attempts in a given period of time. To ensure correct operation, there is a reasonable degree of synchronisation in this Realm. This Realm does not require modification to the underlying Realms or the associated user storage mecahisms. It achieves this by recording all failed logins, including those for users that do not exist. To prevent a DOS by deliberating making requests with invalid users (and hence causing this cache to grow) the size of the list of users that have failed authentication is limited.


Nested Class Summary
protected  class LockOutRealm.LockRecord
           
 
Nested classes/interfaces inherited from class org.apache.catalina.realm.RealmBase
RealmBase.AllRolesMode
 
Field Summary
protected  int cacheRemovalWarningTime
          If a failed user is removed from the cache because the cache is too big before it has been in the cache for at least this period of time (in seconds) a warning message will be logged.
protected  int cacheSize
          Number of users that have failed authentication to keep in cache.
protected  java.util.Map<java.lang.String,LockOutRealm.LockRecord> failedUsers
          Users whose last authentication attempt failed.
protected  int failureCount
          The number of times in a row a user has to fail authentication to be locked out.
protected  int lockOutTime
          The time (in seconds) a user is locked out for after too many authentication failures.
 
Fields inherited from class org.apache.catalina.realm.CombinedRealm
realms, sm
 
Fields inherited from class org.apache.catalina.realm.RealmBase
allRolesMode, container, containerLog, controller, digest, digestEncoding, domain, host, info, initialized, lifecycle, md, md5Encoder, md5Helper, mserver, oname, path, realmPath, started, support, type, validate, x509UsernameRetriever, x509UsernameRetrieverClassName
 
Fields inherited from interface org.apache.catalina.Lifecycle
AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, DESTROY_EVENT, INIT_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT
 
Constructor Summary
LockOutRealm()
           
 
Method Summary
 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 clientDigest, java.lang.String once, java.lang.String nc, java.lang.String cnonce, java.lang.String qop, java.lang.String realmName, 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.
 int getCacheRemovalWarningTime()
          Get the minimum period a failed authentication must remain in the cache to avoid generating a warning if it is removed from the cache to make space for a new entry.
 int getCacheSize()
          Get the maximum number of users for which authentication failure will be kept in the cache.
 int getFailureCount()
          Get the number of failed authentication attempts required to lock the user account.
 int getLockOutTime()
          Get the period for which an account will be locked.
 void setCacheRemovalWarningTime(int cacheRemovalWarningTime)
          Set the minimum period a failed authentication must remain in the cache to avoid generating a warning if it is removed from the cache to make space for a new entry.
 void setCacheSize(int cacheSize)
          Set the maximum number of users for which authentication failure will be kept in the cache.
 void setFailureCount(int failureCount)
          Set the number of failed authentication attempts required to lock the user account.
 void setLockOutTime(int lockOutTime)
          Set the period for which an account will be locked.
 void start()
          Prepare for the beginning of active use of the public methods of this component.
 void unlock(java.lang.String username)
          Unlock the specified username.
 
Methods inherited from class org.apache.catalina.realm.CombinedRealm
addRealm, getName, getPassword, getPrincipal, getRealms, setContainer, stop
 
Methods inherited from class org.apache.catalina.realm.RealmBase
addLifecycleListener, addPropertyChangeListener, backgroundProcess, destroy, digest, Digest, findLifecycleListeners, findSecurityConstraints, getAllRolesMode, getContainer, getController, getDigest, getDigest, getDigestEncoding, getDomain, getInfo, getObjectName, getPrincipal, getRealmPath, getRealmSuffix, getType, getValidate, getX509UsernameRetrieverClassName, hasMessageDigest, hasResourcePermission, hasRole, hasUserDataPermission, init, main, postDeregister, postRegister, preDeregister, preRegister, removeLifecycleListener, removePropertyChangeListener, setAllRolesMode, setController, setDigest, setDigestEncoding, setRealmPath, setValidate, setX509UsernameRetrieverClassName
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

failureCount

protected int failureCount
The number of times in a row a user has to fail authentication to be locked out. Defaults to 5.


lockOutTime

protected int lockOutTime
The time (in seconds) a user is locked out for after too many authentication failures. Defaults to 300 (5 minutes).


cacheSize

protected int cacheSize
Number of users that have failed authentication to keep in cache. Over time the cache will grow to this size and may not shrink. Defaults to 1000.


cacheRemovalWarningTime

protected int cacheRemovalWarningTime
If a failed user is removed from the cache because the cache is too big before it has been in the cache for at least this period of time (in seconds) a warning message will be logged. Defaults to 3600 (1 hour).


failedUsers

protected java.util.Map<java.lang.String,LockOutRealm.LockRecord> failedUsers
Users whose last authentication attempt failed. Entries will be ordered in access order from least recent to most recent.

Constructor Detail

LockOutRealm

public LockOutRealm()
Method Detail

start

public void start()
           throws LifecycleException
Prepare for the beginning of active use of the public methods of this component. This method should be called before any of the public methods of this component are utilized. It should also send a LifecycleEvent of type START_EVENT to any registered listeners.

Specified by:
start in interface Lifecycle
Overrides:
start in class CombinedRealm
Throws:
LifecycleException - if this component detects a fatal error that prevents this component from being used

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
Overrides:
authenticate in class CombinedRealm
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 clientDigest,
                                            java.lang.String once,
                                            java.lang.String nc,
                                            java.lang.String cnonce,
                                            java.lang.String qop,
                                            java.lang.String realmName,
                                            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
Overrides:
authenticate in class CombinedRealm
Parameters:
username - Username of the Principal to look up
clientDigest - Digest which has been submitted by the client
once - Unique (or supposedly unique) token which has been used for this request
realmName - Realm name
md5a2 - Second MD5 digest used to calculate the digest : MD5(Method + ":" + uri)

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
Overrides:
authenticate in class CombinedRealm
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.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
Overrides:
authenticate in class CombinedRealm
Parameters:
certs - Array of client certificates, with the first one in the array being the certificate of the client itself.

unlock

public void unlock(java.lang.String username)
Unlock the specified username. This will remove all records of authentication failures for this user.

Parameters:
username - The user to unlock

getFailureCount

public int getFailureCount()
Get the number of failed authentication attempts required to lock the user account.

Returns:
the failureCount

setFailureCount

public void setFailureCount(int failureCount)
Set the number of failed authentication attempts required to lock the user account.

Parameters:
failureCount - the failureCount to set

getLockOutTime

public int getLockOutTime()
Get the period for which an account will be locked.

Returns:
the lockOutTime

setLockOutTime

public void setLockOutTime(int lockOutTime)
Set the period for which an account will be locked.

Parameters:
lockOutTime - the lockOutTime to set

getCacheSize

public int getCacheSize()
Get the maximum number of users for which authentication failure will be kept in the cache.

Returns:
the cacheSize

setCacheSize

public void setCacheSize(int cacheSize)
Set the maximum number of users for which authentication failure will be kept in the cache.

Parameters:
cacheSize - the cacheSize to set

getCacheRemovalWarningTime

public int getCacheRemovalWarningTime()
Get the minimum period a failed authentication must remain in the cache to avoid generating a warning if it is removed from the cache to make space for a new entry.

Returns:
the cacheRemovalWarningTime

setCacheRemovalWarningTime

public void setCacheRemovalWarningTime(int cacheRemovalWarningTime)
Set the minimum period a failed authentication must remain in the cache to avoid generating a warning if it is removed from the cache to make space for a new entry.

Parameters:
cacheRemovalWarningTime - the cacheRemovalWarningTime to set

Apache Tomcat 6.0.43

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