This exception is thrown by a SASL mechanism implementation
to indicate that the SASL
exchange has failed due to reasons related to authentication, such as
an invalid identity, passphrase, or key.

Note that the lack of an AuthenticationException does not mean that
the failure was not due to an authentication error.  A SASL mechanism
implementation might throw the more general SaslException instead of
AuthenticationException if it is unable to determine the nature
of the failure, or if does not want to disclose the nature of
the failure, for example, due to security reasons.

This callback is used by SaslServer to determine whether
one entity (identified by an authenticated authentication id)
can act on
behalf of another entity (identified by an authorization id).

This callback is used by SaslClient and SaslServer
to retrieve realm information.

This callback is used by SaslClient and SaslServer
to obtain a realm given a list of realm choices.

A static class for creating SASL clients and servers.

This class defines the policy of how to locate, load, and instantiate
SASL clients and servers.

For example, an application or library gets a SASL client by doing
something like:


SaslClient sc = Sasl.createSaslClient(mechanisms,
    authorizationId, protocol, serverName, props, callbackHandler);
It can then proceed to use the instance to create an authentication connection.

Similarly, a server gets a SASL server by using code that looks as follows:


SaslServer ss = Sasl.createSaslServer(mechanism,
    protocol, serverName, props, callbackHandler);

 // 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);

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
evaluateChallenge() with an empty
challenge and to get initial response.
Protocols such as IMAP4, which do not include an initial response with
their first authentication command to the server, initiates the
authentication without first calling hasInitialResponse()
or evaluateChallenge().
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 evaluateChallenge() with an empty challenge.

An interface for creating instances of SaslClient.
A class that implements this interface
must be thread-safe and handle multiple simultaneous
requests. It must also have a public constructor that accepts no
argument.

This interface is not normally accessed directly by a client, which will use the
Sasl static methods
instead. However, a particular environment may provide and install a
new or different SaslClientFactory.

This class represents an error that has occurred when using SASL.

 // Use SaslServer.wrap() and SaslServer.unwrap() for future
 // communication with client
 ldap.in = new SecureInputStream(ss, ldap.in);
 ldap.out = new SecureOutputStream(ss, ldap.out);

Performs SASL authentication as a server.

A server such an LDAP server gets an instance of this
class in order to perform authentication defined by a specific SASL
mechanism. Invoking methods on the SaslServer instance
generates challenges according to the SASL
mechanism implemented by the SaslServer.
As the authentication proceeds, the instance
encapsulates the state of a SASL server's authentication exchange.

Here's an example of how an LDAP server might use a SaslServer.
It first gets an instance of a SaslServer for the SASL mechanism
requested by the client:


SaslServer ss = Sasl.createSaslServer(mechanism,
    "ldap", myFQDN, props, callbackHandler);
It can then proceed to use the server for authentication.
For example, suppose the LDAP server received an LDAP BIND request
containing the name of the SASL mechanism and an (optional) initial
response. It then might use the server as follows:


while (!ss.isComplete()) {
    try {
        byte[] challenge = ss.evaluateResponse(response);
        if (ss.isComplete()) {
            status = ldap.sendBindResponse(mechanism, challenge, SUCCESS);
        } else {
            status = ldap.sendBindResponse(mechanism, challenge,
                  SASL_BIND_IN_PROGRESS);
            response = ldap.readBindRequest();
        }
    } catch (SaslException e) {
         status = ldap.sendErrorResponse(e);
         break;
    }
}
if (ss.isComplete() && status == SUCCESS) {
   String qop = (String) sc.getNegotiatedProperty(Sasl.QOP);
   if (qop != null
       && (qop.equalsIgnoreCase("auth-int")
           || qop.equalsIgnoreCase("auth-conf"))) {

     // Use SaslServer.wrap() and SaslServer.unwrap() for future
     // communication with client
     ldap.in = new SecureInputStream(ss, ldap.in);
     ldap.out = new SecureOutputStream(ss, ldap.out);
   }
}

An interface for creating instances of SaslServer.
A class that implements this interface
must be thread-safe and handle multiple simultaneous
requests. It must also have a public constructor that accepts no
argument.

This interface is not normally accessed directly by a server, which will use the
Sasl static methods
instead. However, a particular environment may provide and install a
new or different SaslServerFactory.