com.novell.sasl.client
Class ExternalSaslClient

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

All Implemented Interfaces:

SaslClient

class ExternalSaslClient

extends java.lang.Object

implements SaslClient

Implements the ExternalSaslClient mechanism.

Field Summary

private java.lang.String	m_authorizationId
private javax.security.auth.callback.CallbackHandler	m_cbh
private java.util.Map	m_props
private java.lang.String	m_protocol
private java.lang.String	m_serverName
private int	m_state
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

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

Method Summary

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 ExternalSaslClient object using the parameters supplied.
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

STATE_INITIAL

private static final int STATE_INITIAL

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

Constructor Detail

ExternalSaslClient

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

Creates an ExternalSaslClient 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 ExternalSaslClient 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.

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.