Package org.apache.catalina.realm
Class RealmBase
- java.lang.Object
- 
- org.apache.catalina.util.LifecycleBase
- 
- org.apache.catalina.util.LifecycleMBeanBase
- 
- org.apache.catalina.realm.RealmBase
 
 
 
- 
- All Implemented Interfaces:
- javax.management.MBeanRegistration,- Contained,- GSSRealm,- JmxEnabled,- Lifecycle,- Realm
 - Direct Known Subclasses:
- CombinedRealm,- DataSourceRealm,- JAASRealm,- JDBCRealm,- JNDIRealm,- MemoryRealm,- NullRealm,- UserDatabaseRealm
 
 public abstract class RealmBase extends LifecycleMBeanBase implements GSSRealm Simple implementation of Realm that reads an XML file to configure the valid users, passwords, and roles. The file format (and default file location) are identical to those currently supported by Tomcat 3.X.- Author:
- Craig R. McClanahan
 
- 
- 
Nested Class SummaryNested Classes Modifier and Type Class Description protected static classRealmBase.AllRolesMode- 
Nested classes/interfaces inherited from interface org.apache.catalina.LifecycleLifecycle.SingleUse
 
- 
 - 
Field SummaryFields Modifier and Type Field Description protected RealmBase.AllRolesModeallRolesModeThe all role mode.protected ContainercontainerThe Container with which this Realm is associated.protected LogcontainerLogContainer logprotected java.lang.StringrealmPathprotected static StringManagersmThe string manager for this package.protected booleanstripRealmForGssWhen processing users authenticated via the GSS-API, should any "@..." be stripped from the end of the user name?protected java.beans.PropertyChangeSupportsupportThe property change support for this component.protected booleanvalidateShould we validate client certificate chains when they are presented?protected X509UsernameRetrieverx509UsernameRetrieverThe object that will extract user names from X509 client certificates.protected java.lang.Stringx509UsernameRetrieverClassNameThe name of the class to use for retrieving user names from X509 certificates.- 
Fields inherited from class org.apache.catalina.util.LifecycleMBeanBasemserver
 - 
Fields inherited from interface org.apache.catalina.LifecycleAFTER_DESTROY_EVENT, AFTER_INIT_EVENT, AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_DESTROY_EVENT, BEFORE_INIT_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, CONFIGURE_START_EVENT, CONFIGURE_STOP_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT
 
- 
 - 
Constructor SummaryConstructors Constructor Description RealmBase()
 - 
Method SummaryAll Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods Modifier and Type Method Description voidaddPropertyChangeListener(java.beans.PropertyChangeListener listener)Add a property change listener to this component.java.security.Principalauthenticate(java.lang.String username)Return the Principal associated with the specified username, if there is one; otherwise returnnull.java.security.Principalauthenticate(java.lang.String username, java.lang.String credentials)Return the Principal associated with the specified username and credentials, if there is one; otherwise returnnull.java.security.Principalauthenticate(java.lang.String username, java.lang.String clientDigest, java.lang.String nonce, java.lang.String nc, java.lang.String cnonce, java.lang.String qop, java.lang.String realm, java.lang.String md5a2)Try to authenticate with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 2617 (which is a superset of RFC 2069).java.security.Principalauthenticate(java.security.cert.X509Certificate[] certs)Return the Principal associated with the specified chain of X509 client certificates.java.security.Principalauthenticate(org.ietf.jgss.GSSContext gssContext, boolean storeCred)Try to authenticate using aGSSContextjava.security.Principalauthenticate(org.ietf.jgss.GSSName gssName, org.ietf.jgss.GSSCredential gssCredential)Try to authenticate using aGSSNamevoidbackgroundProcess()Execute a periodic task, such as reloading, etc.static java.lang.StringDigest(java.lang.String credentials, java.lang.String algorithm, java.lang.String encoding)Deprecated.Unused.SecurityConstraint[]findSecurityConstraints(Request request, Context context)Return the SecurityConstraints configured to guard the request URI for this request, ornullif there is no such constraint.java.lang.StringgetAllRolesMode()Return the all roles mode.ContainergetContainer()Return the Container with which this Realm has been associated.CredentialHandlergetCredentialHandler()protected java.lang.StringgetDigest(java.lang.String username, java.lang.String realmName)Return the digest associated with given principal's user name.java.lang.StringgetDomainInternal()Method implemented by sub-classes to identify the domain in which MBeans should be registered.protected abstract java.lang.StringgetName()Deprecated.This will be removed in Tomcat 9 onwards.java.lang.StringgetObjectNameKeyProperties()Allow sub-classes to specify the key properties component of theObjectNamethat will be used to register this component.protected abstract java.lang.StringgetPassword(java.lang.String username)Get the password for the specified user.protected abstract java.security.PrincipalgetPrincipal(java.lang.String username)Get the principal associated with the specified user.protected java.security.PrincipalgetPrincipal(java.lang.String username, org.ietf.jgss.GSSCredential gssCredential)Deprecated.This will be removed in Tomcat 10 onwards.protected java.security.PrincipalgetPrincipal(java.security.cert.X509Certificate usercert)Get the principal associated with the specified certificate.protected java.security.PrincipalgetPrincipal(org.ietf.jgss.GSSName gssName, org.ietf.jgss.GSSCredential gssCredential)Get the principal associated with the specifiedGSSName.java.lang.StringgetRealmPath()protected java.lang.StringgetRealmSuffix()java.lang.String[]getRoles(java.security.Principal principal)Return roles associated with given principalprotected ServergetServer()Return the Server object that is the ultimate parent for the container with which this Realm is associated.intgetTransportGuaranteeRedirectStatus()booleangetValidate()Return the "validate certificate chains" flag.java.lang.StringgetX509UsernameRetrieverClassName()Gets the name of the class that will be used to extract user names from X509 client certificates.protected booleanhasMessageDigest()booleanhasResourcePermission(Request request, Response response, SecurityConstraint[] constraints, Context context)Perform access control based on the specified authorization constraint.booleanhasRole(Wrapper wrapper, java.security.Principal principal, java.lang.String role)Check if the specified Principal has the specified security role, within the context of this Realm.protected booleanhasRoleInternal(java.security.Principal principal, java.lang.String role)Check if the specified Principal has the specified security role, within the context of this Realm.booleanhasUserDataPermission(Request request, Response response, SecurityConstraint[] constraints)Enforce any user data constraint required by the security constraint guarding this request URI.protected voidinitInternal()Sub-classes wishing to perform additional initialization should override this method, ensuring that super.initInternal() is the first call in the overriding method.booleanisAvailable()Return the availability of the realm for authentication.booleanisStripRealmForGss()static voidmain(java.lang.String[] args)Generate a stored credential string for the given password and associated parameters.voidremovePropertyChangeListener(java.beans.PropertyChangeListener listener)Remove a property change listener from this component.voidsetAllRolesMode(java.lang.String allRolesMode)Set the all roles mode.voidsetContainer(Container container)Set the Container with which this Realm has been associated.voidsetCredentialHandler(CredentialHandler credentialHandler)Set the CredentialHandler to be used by this Realm.voidsetRealmPath(java.lang.String theRealmPath)voidsetStripRealmForGss(boolean stripRealmForGss)voidsetTransportGuaranteeRedirectStatus(int transportGuaranteeRedirectStatus)Set the HTTP status code used when the container needs to issue an HTTP redirect to meet the requirements of a configured transport guarantee.voidsetValidate(boolean validate)Set the "validate certificate chains" flag.voidsetX509UsernameRetrieverClassName(java.lang.String className)Sets the name of the class that will be used to extract user names from X509 client certificates.protected voidstartInternal()Prepare for the beginning of active use of the public methods of this component and implement the requirements ofLifecycleBase.startInternal().protected voidstopInternal()Gracefully terminate the active use of the public methods of this component and implement the requirements ofLifecycleBase.stopInternal().java.lang.StringtoString()Return a String representation of this component.- 
Methods inherited from class org.apache.catalina.util.LifecycleMBeanBasedestroyInternal, getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, unregister
 - 
Methods inherited from class org.apache.catalina.util.LifecycleBaseaddLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, getThrowOnFailure, init, removeLifecycleListener, setState, setState, setThrowOnFailure, start, stop
 
- 
 
- 
- 
- 
Field Detail- 
containerprotected Container container The Container with which this Realm is associated.
 - 
containerLogprotected Log containerLog Container log
 - 
smprotected static final StringManager sm The string manager for this package.
 - 
supportprotected final java.beans.PropertyChangeSupport support The property change support for this component.
 - 
validateprotected boolean validate Should we validate client certificate chains when they are presented?
 - 
x509UsernameRetrieverClassNameprotected java.lang.String x509UsernameRetrieverClassName The name of the class to use for retrieving user names from X509 certificates.
 - 
x509UsernameRetrieverprotected X509UsernameRetriever x509UsernameRetriever The object that will extract user names from X509 client certificates.
 - 
allRolesModeprotected RealmBase.AllRolesMode allRolesMode The all role mode.
 - 
stripRealmForGssprotected boolean stripRealmForGss When processing users authenticated via the GSS-API, should any "@..." be stripped from the end of the user name?
 - 
realmPathprotected java.lang.String realmPath 
 
- 
 - 
Method Detail- 
getTransportGuaranteeRedirectStatuspublic int getTransportGuaranteeRedirectStatus() - Returns:
- The HTTP status code used when the container needs to issue an HTTP redirect to meet the requirements of a configured transport guarantee.
 
 - 
setTransportGuaranteeRedirectStatuspublic void setTransportGuaranteeRedirectStatus(int transportGuaranteeRedirectStatus) Set the HTTP status code used when the container needs to issue an HTTP redirect to meet the requirements of a configured transport guarantee.- Parameters:
- transportGuaranteeRedirectStatus- The status to use. This value is not validated
 
 - 
getCredentialHandlerpublic CredentialHandler getCredentialHandler() - Specified by:
- getCredentialHandlerin interface- Realm
- Returns:
- the CredentialHandler configured for this Realm.
 
 - 
setCredentialHandlerpublic void setCredentialHandler(CredentialHandler credentialHandler) Description copied from interface:RealmSet the CredentialHandler to be used by this Realm.- Specified by:
- setCredentialHandlerin interface- Realm
- Parameters:
- credentialHandler- the- CredentialHandlerto use
 
 - 
getContainerpublic Container getContainer() Return the Container with which this Realm has been associated.- Specified by:
- getContainerin interface- Contained
- Returns:
- The Container with which this instance is associated or
         nullif not associated with a Container
 
 - 
setContainerpublic void setContainer(Container container) Set the Container with which this Realm has been associated.- Specified by:
- setContainerin interface- Contained
- Parameters:
- container- The associated Container
 
 - 
getAllRolesModepublic java.lang.String getAllRolesMode() Return the all roles mode.- Returns:
- A string representation of the current all roles mode
 
 - 
setAllRolesModepublic void setAllRolesMode(java.lang.String allRolesMode) Set the all roles mode.- Parameters:
- allRolesMode- A string representation of the new all roles mode
 
 - 
getValidatepublic boolean getValidate() Return the "validate certificate chains" flag.- Returns:
- The value of the validate certificate chains flag
 
 - 
setValidatepublic void setValidate(boolean validate) Set the "validate certificate chains" flag.- Parameters:
- validate- The new validate certificate chains flag
 
 - 
getX509UsernameRetrieverClassNamepublic java.lang.String getX509UsernameRetrieverClassName() Gets the name of the class that will be used to extract user names from X509 client certificates.- Returns:
- The name of the class that will be used to extract user names from X509 client certificates.
 
 - 
setX509UsernameRetrieverClassNamepublic void setX509UsernameRetrieverClassName(java.lang.String className) Sets the name of the class that will be used to extract user names from X509 client certificates. The class must implement X509UsernameRetriever.- Parameters:
- className- The name of the class that will be used to extract user names from X509 client certificates.
- See Also:
- X509UsernameRetriever
 
 - 
isStripRealmForGsspublic boolean isStripRealmForGss() 
 - 
setStripRealmForGsspublic void setStripRealmForGss(boolean stripRealmForGss) 
 - 
addPropertyChangeListenerpublic void addPropertyChangeListener(java.beans.PropertyChangeListener listener) Add a property change listener to this component.- Specified by:
- addPropertyChangeListenerin interface- Realm
- Parameters:
- listener- The listener to add
 
 - 
authenticatepublic java.security.Principal authenticate(java.lang.String username) Return the Principal associated with the specified username, if there is one; otherwise returnnull.- Specified by:
- authenticatein interface- Realm
- Parameters:
- username- Username of the Principal to look up
- Returns:
- the associated principal, or nullif none is associated.
 
 - 
authenticatepublic 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 returnnull.- Specified by:
- authenticatein interface- Realm
- Parameters:
- username- Username of the Principal to look up
- credentials- Password or other credentials to use in authenticating this username
- Returns:
- the associated principal, or nullif there is none.
 
 - 
authenticatepublic java.security.Principal authenticate(java.lang.String username, java.lang.String clientDigest, java.lang.String nonce, java.lang.String nc, java.lang.String cnonce, java.lang.String qop, java.lang.String realm, java.lang.String md5a2)Try to authenticate with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 2617 (which is a superset of RFC 2069).- Specified by:
- authenticatein interface- Realm
- Parameters:
- username- Username of the Principal to look up
- clientDigest- Digest which has been submitted by the client
- nonce- Unique (or supposedly unique) token which has been used for this request
- nc- the nonce counter
- cnonce- the client chosen nonce
- qop- the "quality of protection" (- ncand- cnoncewill only be used, if- qopis not- null).
- realm- Realm name
- md5a2- Second MD5 digest used to calculate the digest : MD5(Method + ":" + uri)
- Returns:
- the associated principal, or nullif there is none.
 
 - 
authenticatepublic 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, returnnull.- Specified by:
- authenticatein interface- Realm
- Parameters:
- certs- Array of client certificates, with the first one in the array being the certificate of the client itself.
- Returns:
- the associated principal, or nullif there is none
 
 - 
authenticatepublic java.security.Principal authenticate(org.ietf.jgss.GSSContext gssContext, boolean storeCred)Try to authenticate using aGSSContext- Specified by:
- authenticatein interface- Realm
- Parameters:
- gssContext- The gssContext processed by the- Authenticator.
- storeCred- Should the realm attempt to store the delegated credentials in the returned Principal?
- Returns:
- the associated principal, or nullif there is none
 
 - 
authenticatepublic java.security.Principal authenticate(org.ietf.jgss.GSSName gssName, org.ietf.jgss.GSSCredential gssCredential)Try to authenticate using aGSSName- Specified by:
- authenticatein interface- GSSRealm
- Parameters:
- gssName- The- GSSNameof the principal to look up
- gssCredential- The- GSSCredentialof the principal, may be- null
- Returns:
- the associated principal, or nullif there is none
 
 - 
backgroundProcesspublic void backgroundProcess() 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.- Specified by:
- backgroundProcessin interface- Realm
 
 - 
findSecurityConstraintspublic SecurityConstraint[] findSecurityConstraints(Request request, Context context) Return the SecurityConstraints configured to guard the request URI for this request, ornullif there is no such constraint.- Specified by:
- findSecurityConstraintsin interface- Realm
- Parameters:
- request- Request we are processing
- context- Context the Request is mapped to
- Returns:
- the configured SecurityConstraint, ofnullif there is none
 
 - 
hasResourcePermissionpublic boolean hasResourcePermission(Request request, Response response, SecurityConstraint[] constraints, Context context) throws java.io.IOException Perform access control based on the specified authorization constraint. Returntrueif this constraint is satisfied and processing should continue, orfalseotherwise.- Specified by:
- hasResourcePermissionin interface- Realm
- Parameters:
- request- Request we are processing
- response- Response we are creating
- constraints- Security constraint we are enforcing
- context- The Context to which client of this class is attached.
- Returns:
- trueif this constraint is satisfied and processing should continue, or- falseotherwise
- Throws:
- java.io.IOException- if an input/output error occurs
 
 - 
hasRolepublic boolean hasRole(Wrapper wrapper, java.security.Principal principal, java.lang.String role) Check if the specified Principal has the specified security role, within the context of this Realm. This method orhasRoleInternal(Principal, String)can be overridden by Realm implementations, but the default is adequate when an instance ofGenericPrincipalis used to represent authenticated Principals from this Realm.- Specified by:
- hasRolein interface- Realm
- Parameters:
- wrapper- wrapper context for evaluating role
- principal- Principal for whom the role is to be checked
- role- Security role to be checked
- Returns:
- trueif the specified Principal has the specified security role, within the context of this Realm; otherwise return- false.
 
 - 
hasRoleInternalprotected boolean hasRoleInternal(java.security.Principal principal, java.lang.String role)Check if the specified Principal has the specified security role, within the context of this Realm. This method orhasRoleInternal(Principal, String)can be overridden by Realm implementations, but the default is adequate when an instance ofGenericPrincipalis used to represent authenticated Principals from this Realm.- Parameters:
- principal- Principal for whom the role is to be checked
- role- Security role to be checked
- Returns:
- trueif the specified Principal has the specified security role, within the context of this Realm; otherwise return- false.
 
 - 
hasUserDataPermissionpublic boolean hasUserDataPermission(Request request, Response response, SecurityConstraint[] constraints) throws java.io.IOException Enforce any user data constraint required by the security constraint guarding this request URI. Returntrueif this constraint was not violated and processing should continue, orfalseif we have created a response already.- Specified by:
- hasUserDataPermissionin interface- Realm
- Parameters:
- request- Request we are processing
- response- Response we are creating
- constraints- Security constraint being checked
- Returns:
- trueif this constraint was not violated and processing should continue, or- falseif we have created a response already.
- Throws:
- java.io.IOException- if an input/output error occurs
 
 - 
removePropertyChangeListenerpublic void removePropertyChangeListener(java.beans.PropertyChangeListener listener) Remove a property change listener from this component.- Specified by:
- removePropertyChangeListenerin interface- Realm
- Parameters:
- listener- The listener to remove
 
 - 
isAvailablepublic boolean isAvailable() Description copied from interface:RealmReturn the availability of the realm for authentication.- Specified by:
- isAvailablein interface- Realm
- Returns:
- trueif the realm is able to perform authentication
 
 - 
initInternalprotected void initInternal() throws LifecycleExceptionDescription copied from class:LifecycleMBeanBaseSub-classes wishing to perform additional initialization should override this method, ensuring that super.initInternal() is the first call in the overriding method.- Overrides:
- initInternalin class- LifecycleMBeanBase
- Throws:
- LifecycleException- If the initialisation fails
 
 - 
startInternalprotected void startInternal() throws LifecycleExceptionPrepare for the beginning of active use of the public methods of this component and implement the requirements ofLifecycleBase.startInternal().- Specified by:
- startInternalin class- LifecycleBase
- Throws:
- LifecycleException- if this component detects a fatal error that prevents this component from being used
 
 - 
stopInternalprotected void stopInternal() throws LifecycleExceptionGracefully terminate the active use of the public methods of this component and implement the requirements ofLifecycleBase.stopInternal().- Specified by:
- stopInternalin class- LifecycleBase
- Throws:
- LifecycleException- if this component detects a fatal error that needs to be reported
 
 - 
toStringpublic java.lang.String toString() Return a String representation of this component.- Overrides:
- toStringin class- java.lang.Object
 
 - 
hasMessageDigestprotected boolean hasMessageDigest() 
 - 
getDigestprotected java.lang.String getDigest(java.lang.String username, java.lang.String realmName)Return the digest associated with given principal's user name.- Parameters:
- username- the user name
- realmName- the realm name
- Returns:
- the digest for the specified user
 
 - 
getName@Deprecated protected abstract java.lang.String getName() Deprecated.This will be removed in Tomcat 9 onwards. UseClass.getSimpleName()instead.- Returns:
- a short name for this Realm implementation, for use in log messages.
 
 - 
getPasswordprotected abstract java.lang.String getPassword(java.lang.String username) Get the password for the specified user.- Parameters:
- username- The user name
- Returns:
- the password associated with the given principal's user name.
 
 - 
getPrincipalprotected java.security.Principal getPrincipal(java.security.cert.X509Certificate usercert) Get the principal associated with the specified certificate.- Parameters:
- usercert- The user certificate
- Returns:
- the Principal associated with the given certificate.
 
 - 
getPrincipalprotected abstract java.security.Principal getPrincipal(java.lang.String username) Get the principal associated with the specified user.- Parameters:
- username- The user name
- Returns:
- the Principal associated with the given user name.
 
 - 
getPrincipal@Deprecated protected java.security.Principal getPrincipal(java.lang.String username, org.ietf.jgss.GSSCredential gssCredential)Deprecated.This will be removed in Tomcat 10 onwards. UsegetPrincipal(GSSName, GSSCredential)instead.Get the principal associated with the specified user name.- Parameters:
- username- The user name
- gssCredential- the GSS credential of the principal
- Returns:
- the principal associated with the given user name.
 
 - 
getPrincipalprotected java.security.Principal getPrincipal(org.ietf.jgss.GSSName gssName, org.ietf.jgss.GSSCredential gssCredential)Get the principal associated with the specifiedGSSName.- Parameters:
- gssName- The GSS name
- gssCredential- the GSS credential of the principal
- Returns:
- the principal associated with the given user name.
 
 - 
getServerprotected Server getServer() Return the Server object that is the ultimate parent for the container with which this Realm is associated. If the server cannot be found (eg because the container hierarchy is not complete),nullis returned.- Returns:
- the Server associated with the realm
 
 - 
Digest@Deprecated public static final java.lang.String Digest(java.lang.String credentials, java.lang.String algorithm, java.lang.String encoding)Deprecated.Unused. This will be removed in Tomcat 9.Digest password using the algorithm specified and convert the result to a corresponding hex string.- Parameters:
- credentials- Password or other credentials to use in authenticating this username
- algorithm- Algorithm used to do the digest
- encoding- Character encoding of the string to digest
- Returns:
- The digested credentials as a hex string or the original plain text credentials if an error occurs.
 
 - 
mainpublic static void main(java.lang.String[] args) Generate a stored credential string for the given password and associated parameters.The following parameters are supported: - -a - The algorithm to use to generate the stored credential. If not specified a default of SHA-512 will be used.
- -e - The encoding to use for any byte to/from character
                 conversion that may be necessary. If not specified, the
                 system encoding (Charset.defaultCharset()) will be used.
- -i - The number of iterations to use when generating the stored credential. If not specified, the default for the CredentialHandler will be used.
- -s - The length (in bytes) of salt to generate and store as part of the credential. If not specified, the default for the CredentialHandler will be used.
- -k - The length (in bits) of the key(s), if any, created while generating the credential. If not specified, the default for the CredentialHandler will be used.
- -h - The fully qualified class name of the CredentialHandler to use. If not specified, the built-in handlers will be tested in turn and the first one to accept the specified algorithm will be used.
 This generation process currently supports the following CredentialHandlers, the correct one being selected based on the algorithm specified: - Parameters:
- args- The parameters passed on the command line
 
 - 
getObjectNameKeyPropertiespublic java.lang.String getObjectNameKeyProperties() Description copied from class:LifecycleMBeanBaseAllow sub-classes to specify the key properties component of theObjectNamethat will be used to register this component.- Specified by:
- getObjectNameKeyPropertiesin class- LifecycleMBeanBase
- Returns:
- The string representation of the key properties component of the
          desired ObjectName
 
 - 
getDomainInternalpublic java.lang.String getDomainInternal() Description copied from class:LifecycleMBeanBaseMethod implemented by sub-classes to identify the domain in which MBeans should be registered.- Specified by:
- getDomainInternalin class- LifecycleMBeanBase
- Returns:
- The name of the domain to use to register MBeans.
 
 - 
getRealmPathpublic java.lang.String getRealmPath() 
 - 
setRealmPathpublic void setRealmPath(java.lang.String theRealmPath) 
 - 
getRealmSuffixprotected java.lang.String getRealmSuffix() 
 
- 
 
-