com.novell.sasl.client
Class DigestMD5SaslClient

java.lang.Object
  com.novell.sasl.client.DigestMD5SaslClient

All Implemented Interfaces:

SaslClient

class DigestMD5SaslClient

extends java.lang.Object

implements SaslClient

Implements the Client portion of DigestMD5 Sasl mechanism.

Field Summary

private static java.lang.String	DIGEST_METHOD
private java.lang.String	m_authorizationId
private javax.security.auth.callback.CallbackHandler	m_cbh
private java.lang.String	m_clientNonce
private DigestChallenge	m_dc
private java.lang.String	m_digestURI
private char[]	m_HA1
private java.lang.String	m_name
private java.util.Map	m_props
private java.lang.String	m_protocol
private java.lang.String	m_qopValue
private java.lang.String	m_realm
private java.lang.String	m_serverName
private int	m_state
private static int	NONCE_BYTE_COUNT
private static int	NONCE_HEX_COUNT
private static int	STATE_DIGEST_RESPONSE_SENT
private static int	STATE_DISPOSED
private static int	STATE_INITIAL
private static int	STATE_INVALID_SERVER_RESPONSE
private static int	STATE_VALID_SERVER_RESPONSE

Constructor Summary

private

DigestMD5SaslClient(java.lang.String authorizationId, java.lang.String protocol, java.lang.String serverName, java.util.Map props, javax.security.auth.callback.CallbackHandler cbh) Creates an DigestMD5SaslClient object using the parameters supplied.

Method Summary

(package private) boolean	checkServerResponseAuth(byte[] serverResponse) This function validates the server response.
(package private) char[]	convertToHex(byte[] hash) This function takes a 16 byte binary md5-hash value and creates a 32 character (plus a terminating null character) hex-digit representation of binary data.
private java.lang.String	createDigestResponse(byte[] challenge) Creates the intial response to be sent to the server.
(package private) char[]	DigestCalcHA1(java.lang.String algorithm, java.lang.String userName, java.lang.String realm, java.lang.String password, java.lang.String nonce, java.lang.String clientNonce) Calculates the HA1 portion of the response
(package private) char[]	DigestCalcResponse(char[] HA1, java.lang.String serverNonce, java.lang.String nonceCount, java.lang.String clientNonce, java.lang.String qop, java.lang.String method, java.lang.String digestUri, boolean clientResponseFlag) This function calculates the response-value of the response directive of the digest-response as documented in RFC 2831
void	dispose() Disposes of any system resources or security-sensitive information the SaslClient might be using.
byte[]	evaluateChallenge(byte[] challenge) Evaluates the challenge data and generates a response.
static SaslClient	getClient(java.lang.String authorizationId, java.lang.String protocol, java.lang.String serverName, java.util.Map props, javax.security.auth.callback.CallbackHandler cbh) Creates an DigestMD5SaslClient object using the parameters supplied.
(package private) java.lang.String	getClientNonce() Calculates the Nonce value of the Client
private static char	getHexChar(byte value) This function returns hex character representing the value of the input
java.lang.String	getMechanismName() Returns the IANA-registered mechanism name of this SASL client.
java.lang.Object	getNegotiatedProperty(java.lang.String propName) Retrieves the negotiated property.
boolean	hasInitialResponse() Determines if this mechanism has an optional initial response.
boolean	isComplete() Determines if the authentication exchange has completed.
byte[]	unwrap(byte[] incoming, int offset, int len) Unwraps a byte array received from the server.
byte[]	wrap(byte[] outgoing, int offset, int len) Wraps a byte array to be sent to the server.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

m_authorizationId

private java.lang.String m_authorizationId

m_protocol

private java.lang.String m_protocol

m_serverName

private java.lang.String m_serverName

m_props

private java.util.Map m_props

m_cbh

private javax.security.auth.callback.CallbackHandler m_cbh

m_state

private int m_state

m_qopValue

private java.lang.String m_qopValue

m_HA1

private char[] m_HA1

m_digestURI

private java.lang.String m_digestURI

m_dc

private DigestChallenge m_dc

m_clientNonce

private java.lang.String m_clientNonce

m_realm

private java.lang.String m_realm

m_name

private java.lang.String m_name

STATE_INITIAL

private static final int STATE_INITIAL

See Also:

Constant Field Values

STATE_DIGEST_RESPONSE_SENT

private static final int STATE_DIGEST_RESPONSE_SENT

See Also:

Constant Field Values

STATE_VALID_SERVER_RESPONSE

private static final int STATE_VALID_SERVER_RESPONSE

See Also:

Constant Field Values

STATE_INVALID_SERVER_RESPONSE

private static final int STATE_INVALID_SERVER_RESPONSE

See Also:

Constant Field Values

STATE_DISPOSED

private static final int STATE_DISPOSED

See Also:

Constant Field Values

NONCE_BYTE_COUNT

private static final int NONCE_BYTE_COUNT

See Also:

Constant Field Values

NONCE_HEX_COUNT

private static final int NONCE_HEX_COUNT

See Also:

Constant Field Values

DIGEST_METHOD

private static final java.lang.String DIGEST_METHOD

See Also:

Constant Field Values

Constructor Detail

DigestMD5SaslClient

private DigestMD5SaslClient(java.lang.String authorizationId,
                            java.lang.String protocol,
                            java.lang.String serverName,
                            java.util.Map props,
                            javax.security.auth.callback.CallbackHandler cbh)

Creates an DigestMD5SaslClient object using the parameters supplied. Assumes that the QOP, STRENGTH, and SERVER_AUTH properties are contained in props

Parameters:

authorizationId - The possibly null protocol-dependent identification to be used for authorization. If null or empty, the server derives an authorization ID from the client's authentication credentials. When the SASL authentication completes successfully, the specified entity is granted access.

protocol - The non-null string name of the protocol for which the authentication is being performed (e.g. "ldap")

serverName - The non-null fully qualified host name of the server to authenticate to

props - The possibly null set of properties used to select the SASL mechanism and to configure the authentication exchange of the selected mechanism. See the Sasl class for a list of standard properties. Other, possibly mechanism-specific, properties can be included. Properties not relevant to the selected mechanism are ignored.

cbh - The possibly null callback handler to used by the SASL mechanisms to get further information from the application/library to complete the authentication. For example, a SASL mechanism might require the authentication ID, password and realm from the caller. The authentication ID is requested by using a NameCallback. The password is requested by using a PasswordCallback. The realm is requested by using a RealmChoiceCallback if there is a list of realms to choose from, and by using a RealmCallback if the realm must be entered.

Method Detail

getClient

public static SaslClient getClient(java.lang.String authorizationId,
                                   java.lang.String protocol,
                                   java.lang.String serverName,
                                   java.util.Map props,
                                   javax.security.auth.callback.CallbackHandler cbh)

Creates an DigestMD5SaslClient object using the parameters supplied. Assumes that the QOP, STRENGTH, and SERVER_AUTH properties are contained in props

Parameters:

authorizationId - The possibly null protocol-dependent identification to be used for authorization. If null or empty, the server derives an authorization ID from the client's authentication credentials. When the SASL authentication completes successfully, the specified entity is granted access.

protocol - The non-null string name of the protocol for which the authentication is being performed (e.g. "ldap")

serverName - The non-null fully qualified host name of the server to authenticate to

props - The possibly null set of properties used to select the SASL mechanism and to configure the authentication exchange of the selected mechanism. See the Sasl class for a list of standard properties. Other, possibly mechanism-specific, properties can be included. Properties not relevant to the selected mechanism are ignored.

cbh - The possibly null callback handler to used by the SASL mechanisms to get further information from the application/library to complete the authentication. For example, a SASL mechanism might require the authentication ID, password and realm from the caller. The authentication ID is requested by using a NameCallback. The password is requested by using a PasswordCallback. The realm is requested by using a RealmChoiceCallback if there is a list of realms to choose from, and by using a RealmCallback if the realm must be entered.

Returns:

A possibly null SaslClient created using the parameters supplied. If null, this factory cannot produce a SaslClient using the parameters supplied.

Throws:

SaslException - If a SaslClient instance cannot be created because of an error

hasInitialResponse

public boolean hasInitialResponse()

Determines if this mechanism has an optional initial response. If true, caller should call evaluateChallenge() with an empty array to get the initial response.

Specified by:

hasInitialResponse in interface SaslClient

Returns:

true if this mechanism has an initial response

isComplete

public boolean isComplete()

Determines if the authentication exchange has completed. This method may be called at any time, but typically, it will not be called until the caller has received indication from the server (in a protocol- specific manner) that the exchange has completed.

Specified by:

isComplete in interface SaslClient

Returns:

true if the authentication exchange has completed; false otherwise.

unwrap

public byte[] unwrap(byte[] incoming,
                     int offset,
                     int len)
              throws SaslException

Unwraps a byte array received from the server. This method can be called only after the authentication exchange has completed (i.e., when isComplete() returns true) and only if the authentication exchange has negotiated integrity and/or privacy as the quality of protection; otherwise, an IllegalStateException is thrown. incoming is the contents of the SASL buffer as defined in RFC 2222 without the leading four octet field that represents the length. offset and len specify the portion of incoming to use.

Specified by:

unwrap in interface SaslClient

Parameters:

incoming - A non-null byte array containing the encoded bytes from the server

offset - The starting position at incoming of the bytes to use

len - The number of bytes from incoming to use

Returns:

A non-null byte array containing the decoded bytes

Throws:

SaslException - If this method is called before the authentictaion process has completed.A SaslException is thrown also if incoming cannot be successfully unwrapped

wrap

public byte[] wrap(byte[] outgoing,
                   int offset,
                   int len)
            throws SaslException

Wraps a byte array to be sent to the server. This method can be called only after the authentication exchange has completed (i.e., when isComplete() returns true) and only if the authentication exchange has negotiated integrity and/or privacy as the quality of protection; otherwise, an IllegalStateException is thrown. The result of this method will make up the contents of the SASL buffer as defined in RFC 2222 without the leading four octet field that represents the length. offset and len specify the portion of outgoing to use.

Specified by:

wrap in interface SaslClient

Parameters:

outgoing - A non-null byte array containing the bytes to encode

offset - The starting position at outgoing of the bytes to use

len - The number of bytes from outgoing to use

Returns:

A non-null byte array containing the encoded bytes

Throws:

SaslException - if incoming cannot be successfully unwrapped.

java.lang.IllegalStateException - if the authentication exchange has not completed, or if the negotiated quality of protection has neither integrity nor privacy.

getNegotiatedProperty

public java.lang.Object getNegotiatedProperty(java.lang.String propName)

Retrieves the negotiated property. This method can be called only after the authentication exchange has completed (i.e., when isComplete() returns true); otherwise, an IllegalStateException is thrown.

Specified by:

getNegotiatedProperty in interface SaslClient

Parameters:

propName - The non-null property name

Returns:

The value of the negotiated property. If null, the property was not negotiated or is not applicable to this mechanism.

Throws:

java.lang.IllegalStateException - if this authentication exchange has not completed

dispose

public void dispose()
             throws SaslException

Disposes of any system resources or security-sensitive information the SaslClient might be using. Invoking this method invalidates the SaslClient instance. This method is idempotent.

Specified by:

dispose in interface SaslClient

Throws:

SaslException - if a problem was encountered while disposing of the resources

evaluateChallenge

public byte[] evaluateChallenge(byte[] challenge)
                         throws SaslException

Evaluates the challenge data and generates a response. If a challenge is received from the server during the authentication process, this method is called to prepare an appropriate next response to submit to the server.

Specified by:

evaluateChallenge in interface SaslClient

Parameters:

challenge - The non-null challenge sent from the server. The challenge array may have zero length.

Returns:

The possibly null reponse to send to the server. It is null if the challenge accompanied a "SUCCESS" status and the challenge only contains data for the client to update its state and no response needs to be sent to the server. The response is a zero-length byte array if the client is to send a response with no data.

Throws:

SaslException - If an error occurred while processing the challenge or generating a response.

convertToHex

char[] convertToHex(byte[] hash)

This function takes a 16 byte binary md5-hash value and creates a 32 character (plus a terminating null character) hex-digit representation of binary data.

Parameters:

hash - 16 byte binary md5-hash value in bytes

Returns:

32 character (plus a terminating null character) hex-digit representation of binary data.

DigestCalcHA1

char[] DigestCalcHA1(java.lang.String algorithm,
                     java.lang.String userName,
                     java.lang.String realm,
                     java.lang.String password,
                     java.lang.String nonce,
                     java.lang.String clientNonce)
               throws SaslException

Calculates the HA1 portion of the response

Parameters:

algorithm - Algorith to use.

userName - User being authenticated

realm - realm information

password - password of teh user

nonce - nonce value

clientNonce - Clients Nonce value

Returns:

HA1 portion of the response in a character array

Throws:

SaslException - If an error occurs

DigestCalcResponse

char[] DigestCalcResponse(char[] HA1,
                          java.lang.String serverNonce,
                          java.lang.String nonceCount,
                          java.lang.String clientNonce,
                          java.lang.String qop,
                          java.lang.String method,
                          java.lang.String digestUri,
                          boolean clientResponseFlag)
                    throws SaslException

This function calculates the response-value of the response directive of the digest-response as documented in RFC 2831

Parameters:

HA1 - H(A1)

serverNonce - nonce from server

nonceCount - 8 hex digits

clientNonce - client nonce

qop - qop-value: "", "auth", "auth-int"

method - method from the request

digestUri - requested URL

clientResponseFlag - request-digest or response-digest

Returns:

Response-value of the response directive of the digest-response

Throws:

SaslException - If an error occurs

createDigestResponse

private java.lang.String createDigestResponse(byte[] challenge)
                                       throws SaslException

Creates the intial response to be sent to the server.

Parameters:

challenge - Challenge in bytes recived form the Server

Returns:

Initial response to be sent to the server

Throws:

SaslException

checkServerResponseAuth

boolean checkServerResponseAuth(byte[] serverResponse)
                          throws SaslException

This function validates the server response. This step performs a modicum of mutual authentication by verifying that the server knows the user's password

Parameters:

serverResponse - Response recived form Server

Returns:

true if the mutual authentication succeeds; else return false

Throws:

SaslException - If an error occurs

getHexChar

private static char getHexChar(byte value)

This function returns hex character representing the value of the input

Parameters:

value - Input value in byte

Returns:

Hex value of the Input byte value

getClientNonce

java.lang.String getClientNonce()
                          throws SaslException

Calculates the Nonce value of the Client

Returns:

Nonce value of the client

Throws:

SaslException - If an error Occurs

getMechanismName

public java.lang.String getMechanismName()

Returns the IANA-registered mechanism name of this SASL client. (e.g. "CRAM-MD5", "GSSAPI")

Specified by:

getMechanismName in interface SaslClient

Returns:

"DIGEST-MD5"the IANA-registered mechanism name of this SASL client.