com.netscape.sasl
Interface SaslClient

All Known Implementing Classes:

SaslExternal

public interface SaslClient

Performs SASL authentication as a client.

A protocol library such as one for LDAP gets an instance of this class in order to perform authentication defined by a specific SASL mechanism. Invoking methods on the SaslClient instance process challenges and create responses according to the SASL mechanism implemented by the SaslClient. As the authentication proceeds, the instance encapsulates the state of a SASL client's authentication exchange.

Here's an example of how an LDAP library might use a SaslClient. It first gets an instance of a SaslClient:

 SaslClient sc = Sasl.createSaslClient(mechanisms,
     authorizationId, protocol, serverName, props, callbackHandler);

It can then proceed to use the client for authentication. For example, an LDAP library might use the client as follows:

 InputStream is = ldap.getInputStream();
 OutputStream os = ldap.getOutputStream();
 byte[] toServer = sc.createInitialResponse();
 LdapResult res = ldap.sendBindRequest(dn, sc.getName(), toServer);
 while (!sc.isComplete() && res.status == SASL_BIND_IN_PROGRESS) {
     toServer = sc.evaluateChallenge(res.getBytesFromServer());
     if (toServer != null) {
        res = ldap.sendBindRequest(dn, sc.getName(), toServer);
     }
 }
 if (sc.isComplete() && res.status == SUCCESS) {
     // Get the input and output streams; may be unchanged
     is = sc.getInputStream( is );
     os = sc.getOutputStream( os );
     // Use these streams from now on
     ldap.setInputStream( is );
     ldap.setOutputStream( os );
 }

Note that the call to createInitialResponse() is optional. Protocols such as IMAP4 do not invoke it but instead only use evaluateChallenge(), possibly with an empty challenge. It is the responsibility of the SaslClient implementation for a mechanism to take this into account so that it behaves properly regardless of whether createInitialResponse() is called.

See Also:

Sasl, SaslClientFactory

Method Summary

byte[]	createInitialResponse() Retrieves the initial response.
byte[]	evaluateChallenge(byte[] challenge) Evaluates the challenge data and generates a response.
java.io.InputStream	getInputStream(java.io.InputStream is) Retrieves an input stream for the session.
java.lang.String	getMechanismName() Returns the IANA-registered mechanism name of this SASL client.
java.io.OutputStream	getOutputStream(java.io.OutputStream os) Retrieves an output stream for the session.
boolean	isComplete() Determines whether the authentication exchange has completed.

Method Detail

getMechanismName

public java.lang.String getMechanismName()

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

Returns:

A non-null string representing the IANA-registered mechanism name.

createInitialResponse

public byte[] createInitialResponse()
                             throws SaslException

Retrieves the initial response.

Returns:

The possibly null byte array containing the initial response. It is null if the mechanism does not have an initial response.

Throws:

SaslException - If an error occurred while creating the initial response.

evaluateChallenge

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

Evaluates the challenge data and generates a response.

Parameters:

challenge - The non-null challenge sent from the server.

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.

Throws:

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

isComplete

public boolean isComplete()

Determines whether the authentication exchange has completed.

Returns:

true if the authentication exchange has completed; false otherwise.

getInputStream

public java.io.InputStream getInputStream(java.io.InputStream is)
                                   throws java.io.IOException

Retrieves an input stream for the session. It may return the same stream that is passed in, if no processing is to be done by the client object. This method can only be called if isComplete() returns true.

Parameters:

is - The original input stream for reading from the server.

Returns:

An input stream for reading from the server, which may include processing the original stream.

Throws:

java.io.IOException - If the authentication exchange has not completed or an error occurred while getting the stream.

getOutputStream

public java.io.OutputStream getOutputStream(java.io.OutputStream os)
                                     throws java.io.IOException

Retrieves an output stream for the session. It may return the same stream that is passed in, if no processing is to be done by the client object. This method can only be called if isComplete() returns true.

Parameters:

is - The original output stream for writing to the server.

Returns:

An output stream for writing to the server, which may include processing the original stream.

Throws:

java.io.IOException - If the authentication exchange has not completed or an error occurred while getting the stream.