org.opends.server.extensions
Class DigestMD5SASLMechanismHandler

java.lang.Object
  extended by org.opends.server.api.SASLMechanismHandler<DigestMD5SASLMechanismHandlerCfg>
      extended by org.opends.server.extensions.DigestMD5SASLMechanismHandler
All Implemented Interfaces:
ConfigurationChangeListener<DigestMD5SASLMechanismHandlerCfg>

public class DigestMD5SASLMechanismHandler
extends SASLMechanismHandler<DigestMD5SASLMechanismHandlerCfg>
implements ConfigurationChangeListener<DigestMD5SASLMechanismHandlerCfg>

This class provides an implementation of a SASL mechanism that uses digest authentication via DIGEST-MD5. This is a password-based mechanism that does not expose the password itself over the wire but rather uses an MD5 hash that proves the client knows the password. This is similar to the CRAM-MD5 mechanism, and the primary differences are that CRAM-MD5 only obtains random data from the server whereas DIGEST-MD5 uses random data from both the server and the client, CRAM-MD5 does not allow for an authorization ID in addition to the authentication ID where DIGEST-MD5 does, and CRAM-MD5 does not define any integrity and confidentiality mechanisms where DIGEST-MD5 does. This implementation is based on the specification in RFC 2831 and updates from draft-ietf-sasl-rfc2831bis-06.


Constructor Summary
DigestMD5SASLMechanismHandler()
          Creates a new instance of this SASL mechanism handler.
 
Method Summary
 ConfigChangeResult applyConfigurationChange(DigestMD5SASLMechanismHandlerCfg configuration)
          Applies the configuration changes to this change listener.
 void finalizeSASLMechanismHandler()
          Performs any finalization that may be necessary for this SASL mechanism handler.
 byte[] generateResponseAuthDigest(java.lang.String userName, java.lang.String authzID, byte[] password, java.lang.String realm, java.lang.String nonce, java.lang.String cnonce, java.lang.String nonceCount, java.lang.String digestURI, java.lang.String qop, java.lang.String charset)
          Generates the appropriate DIGEST-MD5 rspauth digest using the provided information.
 byte[] generateResponseDigest(java.lang.String userName, java.lang.String authzID, byte[] password, java.lang.String realm, java.lang.String nonce, java.lang.String cnonce, java.lang.String nonceCount, java.lang.String digestURI, java.lang.String qop, java.lang.String charset)
          Generates the appropriate DIGEST-MD5 response for the provided set of information.
 void initializeSASLMechanismHandler(DigestMD5SASLMechanismHandlerCfg configuration)
          Initializes this SASL mechanism handler based on the information in the provided configuration entry.
 boolean isConfigurationAcceptable(SASLMechanismHandlerCfg configuration, java.util.List<Message> unacceptableReasons)
          Indicates whether the provided configuration is acceptable for this SASL mechanism handler.
 boolean isConfigurationChangeAcceptable(DigestMD5SASLMechanismHandlerCfg configuration, java.util.List<Message> unacceptableReasons)
          Indicates whether the proposed change to the configuration is acceptable to this change listener.
 boolean isPasswordBased(java.lang.String mechanism)
          Indicates whether the specified SASL mechanism is password-based or uses some other form of credentials (e.g., an SSL client certificate or Kerberos ticket).
 boolean isSecure(java.lang.String mechanism)
          Indicates whether the specified SASL mechanism should be considered secure (i.e., it does not expose the authentication credentials in a manner that is useful to a third-party observer, and other aspects of the authentication are generally secure).
 void processSASLBind(BindOperation bindOperation)
          Processes the SASL bind operation.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DigestMD5SASLMechanismHandler

public DigestMD5SASLMechanismHandler()
Creates a new instance of this SASL mechanism handler. No initialization should be done in this method, as it should all be performed in the initializeSASLMechanismHandler method.

Method Detail

initializeSASLMechanismHandler

public void initializeSASLMechanismHandler(DigestMD5SASLMechanismHandlerCfg configuration)
                                    throws ConfigException,
                                           InitializationException
Initializes this SASL mechanism handler based on the information in the provided configuration entry. It should also register itself with the Directory Server for the particular kinds of SASL mechanisms that it will process.

Specified by:
initializeSASLMechanismHandler in class SASLMechanismHandler<DigestMD5SASLMechanismHandlerCfg>
Parameters:
configuration - The configuration to use to initialize this SASL mechanism handler.
Throws:
ConfigException - If an unrecoverable problem arises in the process of performing the initialization.
InitializationException - If a problem occurs during initialization that is not related to the server configuration.

finalizeSASLMechanismHandler

public void finalizeSASLMechanismHandler()
Performs any finalization that may be necessary for this SASL mechanism handler. By default, no finalization is performed.

Overrides:
finalizeSASLMechanismHandler in class SASLMechanismHandler<DigestMD5SASLMechanismHandlerCfg>

processSASLBind

public void processSASLBind(BindOperation bindOperation)
Processes the SASL bind operation. SASL mechanism implementations must ensure that the following actions are taken during the processing of this method:

Specified by:
processSASLBind in class SASLMechanismHandler<DigestMD5SASLMechanismHandlerCfg>
Parameters:
bindOperation - The SASL bind operation to be processed.

generateResponseDigest

public byte[] generateResponseDigest(java.lang.String userName,
                                     java.lang.String authzID,
                                     byte[] password,
                                     java.lang.String realm,
                                     java.lang.String nonce,
                                     java.lang.String cnonce,
                                     java.lang.String nonceCount,
                                     java.lang.String digestURI,
                                     java.lang.String qop,
                                     java.lang.String charset)
                              throws java.io.UnsupportedEncodingException
Generates the appropriate DIGEST-MD5 response for the provided set of information.

Parameters:
userName - The username from the authentication request.
authzID - The authorization ID from the request, or null if there is none.
password - The clear-text password for the user.
realm - The realm for which the authentication is to be performed.
nonce - The random data generated by the server for use in the digest.
cnonce - The random data generated by the client for use in the digest.
nonceCount - The 8-digit hex string indicating the number of times the provided nonce has been used by the client.
digestURI - The digest URI that specifies the service and host for which the authentication is being performed.
qop - The quality of protection string for the authentication.
charset - The character set used to encode the information.
Returns:
The DIGEST-MD5 response for the provided set of information.
Throws:
java.io.UnsupportedEncodingException - If the specified character set is invalid for some reason.

generateResponseAuthDigest

public byte[] generateResponseAuthDigest(java.lang.String userName,
                                         java.lang.String authzID,
                                         byte[] password,
                                         java.lang.String realm,
                                         java.lang.String nonce,
                                         java.lang.String cnonce,
                                         java.lang.String nonceCount,
                                         java.lang.String digestURI,
                                         java.lang.String qop,
                                         java.lang.String charset)
                                  throws java.io.UnsupportedEncodingException
Generates the appropriate DIGEST-MD5 rspauth digest using the provided information.

Parameters:
userName - The username from the authentication request.
authzID - The authorization ID from the request, or null if there is none.
password - The clear-text password for the user.
realm - The realm for which the authentication is to be performed.
nonce - The random data generated by the server for use in the digest.
cnonce - The random data generated by the client for use in the digest.
nonceCount - The 8-digit hex string indicating the number of times the provided nonce has been used by the client.
digestURI - The digest URI that specifies the service and host for which the authentication is being performed.
qop - The quality of protection string for the authentication.
charset - The character set used to encode the information.
Returns:
The DIGEST-MD5 response for the provided set of information.
Throws:
java.io.UnsupportedEncodingException - If the specified character set is invalid for some reason.

isPasswordBased

public boolean isPasswordBased(java.lang.String mechanism)
Indicates whether the specified SASL mechanism is password-based or uses some other form of credentials (e.g., an SSL client certificate or Kerberos ticket).

Specified by:
isPasswordBased in class SASLMechanismHandler<DigestMD5SASLMechanismHandlerCfg>
Parameters:
mechanism - The name of the mechanism for which to make the determination. This will only be invoked with names of mechanisms for which this handler has previously registered.
Returns:
true if this SASL mechanism is password-based, or false if it uses some other form of credentials.

isSecure

public boolean isSecure(java.lang.String mechanism)
Indicates whether the specified SASL mechanism should be considered secure (i.e., it does not expose the authentication credentials in a manner that is useful to a third-party observer, and other aspects of the authentication are generally secure).

Specified by:
isSecure in class SASLMechanismHandler<DigestMD5SASLMechanismHandlerCfg>
Parameters:
mechanism - The name of the mechanism for which to make the determination. This will only be invoked with names of mechanisms for which this handler has previously registered.
Returns:
true if this SASL mechanism should be considered secure, or false if not.

isConfigurationAcceptable

public boolean isConfigurationAcceptable(SASLMechanismHandlerCfg configuration,
                                         java.util.List<Message> unacceptableReasons)
Indicates whether the provided configuration is acceptable for this SASL mechanism handler. It should be possible to call this method on an uninitialized SASL mechanism handler instance in order to determine whether the SASL mechanism handler would be able to use the provided configuration.

Note that implementations which use a subclass of the provided configuration class will likely need to cast the configuration to the appropriate subclass type.

Overrides:
isConfigurationAcceptable in class SASLMechanismHandler<DigestMD5SASLMechanismHandlerCfg>
Parameters:
configuration - The SASL mechanism handler configuration for which to make the determination.
unacceptableReasons - A list that may be used to hold the reasons that the provided configuration is not acceptable.
Returns:
true if the provided configuration is acceptable for this SASL mechanism handler, or false if not.

isConfigurationChangeAcceptable

public boolean isConfigurationChangeAcceptable(DigestMD5SASLMechanismHandlerCfg configuration,
                                               java.util.List<Message> unacceptableReasons)
Indicates whether the proposed change to the configuration is acceptable to this change listener.

Specified by:
isConfigurationChangeAcceptable in interface ConfigurationChangeListener<DigestMD5SASLMechanismHandlerCfg>
Parameters:
configuration - The new configuration containing the changes.
unacceptableReasons - A list that can be used to hold messages about why the provided configuration is not acceptable.
Returns:
Returns true if the proposed change is acceptable, or false if it is not.

applyConfigurationChange

public ConfigChangeResult applyConfigurationChange(DigestMD5SASLMechanismHandlerCfg configuration)
Applies the configuration changes to this change listener.

Specified by:
applyConfigurationChange in interface ConfigurationChangeListener<DigestMD5SASLMechanismHandlerCfg>
Parameters:
configuration - The new configuration containing the changes.
Returns:
Returns information about the result of changing the configuration.