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:
*
* // Get initial response and send to server
*byte[] response = sc.hasInitialResponse()
* ? sc.evaluateChallenge(new byte[0]) : null;
*LdapResult res = ldap.sendBindRequest(dn, sc.getName(), response);
*while (!sc.isComplete()
* && ((res.status == SASL_BIND_IN_PROGRESS) || (res.status == SUCCESS))) {
* response = sc.evaluateChallenge( res.getBytes() );
* if (res.status == SUCCESS) {
* // we're done; don't expect to send another BIND
* if ( response != null ) {
* throw new SaslException(
* "Protocol error: attempting to send response after completion");
* }
* break;
* }
* res = ldap.sendBindRequest(dn, sc.getName(), response);
*}
*if (sc.isComplete() && (res.status == SUCCESS) ) {
* String qop = (String)sc.getNegotiatedProperty(Sasl.QOP);
* if ((qop != null)
* && (qop.equalsIgnoreCase("auth-int")
* || qop.equalsIgnoreCase("auth-conf"))) {
* // Use SaslClient.wrap() and SaslClient.unwrap() for future
* // communication with server
* ldap.in = new SecureInputStream(sc, ldap.in);
* ldap.out = new SecureOutputStream(sc, ldap.out);
* }
*}
*
*
* If the mechanism has an initial response, the library invokes * {@link #evaluateChallenge(byte[])} with an empty challenge to get the initial * response. Protocols such as IMAP4, which do not include an initial response * with their first authentication command to the server, initiate the * authentication without first calling {@link #hasInitialResponse()} or * {@link #evaluateChallenge(byte[])}. When the server responds to the command, * it sends an initial challenge. For a SASL mechanism in which the client sends * data first, the server should have issued a challenge with no data. This will * then result in a call (on the client) to {@link #evaluateChallenge(byte[])} * with an empty challenge.
* * @see Sasl * @see SaslClientFactory * * @since 1.5 */ public interface SaslClient { /** * Returns the IANA-registered mechanism name of this SASL client. (e.g. * "CRAM-MD5", "GSSAPI"). * * @return a non-null string representing the IANA-registered mechanism name. */ String getMechanismName(); /** * Determines if this mechanism has an optional initial response. If *true, caller should call {@link #evaluateChallenge(byte[])}
* with an empty array to get the initial response.
*
* @return true if this mechanism has an initial response.
*/
boolean hasInitialResponse();
/**
* 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.
*
* @param challenge the non-null challenge sent from the server. The
* challenge array may have zero length.
* @return 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.
*/
byte[] evaluateChallenge(byte[] challenge) throws SaslException;
/**
* 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.
*
* @return true if the authentication exchange has completed;
* false otherwise.
*/
boolean isComplete();
/**
* Unwraps a byte array received from the server. This method can be
* called only after the authentication exchange has completed (i.e., when
* {@link #isComplete()} returns true) and only if the
* authentication exchange has negotiated integrity and/or privacy as the
* quality of protection; otherwise, an {@link 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.
incoming of the bytes
* to use.
* @param len the number of bytes from incoming to use.
* @return a non-null byte array containing the decoded bytes.
* @throws SaslException if incoming cannot be successfully
* unwrapped.
* @throws IllegalStateException if the authentication exchange has not
* completed, or if the negotiated quality of protection has neither
* integrity nor privacy.
*/
byte[] unwrap(byte[] incoming, 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
* {@link #isComplete()} returns true) and only if the
* authentication exchange has negotiated integrity and/or privacy as the
* quality of protection; otherwise, an {@link 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.
outgoing of the bytes
* to use.
* @param len the number of bytes from outgoing to use.
* @return a non-null byte array containing the encoded bytes.
* @throws SaslException if outgoing cannot be successfully
* wrapped.
* @throws IllegalStateException if the authentication exchange has not
* completed, or if the negotiated quality of protection has neither
* integrity nor privacy.
*/
byte[] wrap(byte[] outgoing, int offset, int len) throws SaslException;
/**
* Retrieves the negotiated property. This method can be called only after
* the authentication exchange has completed (i.e., when {@link #isComplete()}
* returns true); otherwise, an {@link IllegalStateException} is
* thrown.
*
* @param propName the non-null property name.
* @return the value of the negotiated property. If null, the
* property was not negotiated or is not applicable to this mechanism.
* @throws IllegalStateException if this authentication exchange has not
* completed.
*/
Object getNegotiatedProperty(String propName);
/**
* 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.
*
* @throws SaslException if a problem was encountered while disposing of the
* resources.
*/
void dispose() throws SaslException;
}