Package javax.security.sasl

Contains classes and interfaces for supporting SASL.

See:
Description

Interface Summary

SaslClient	Performs SASL authentication as a client.
SaslClientFactory	An interface for creating instances of SaslClient.
SaslServer	Performs SASL authentication as a server.
SaslServerFactory	An interface for creating instances of SaslServer.

Class Summary

AuthorizeCallback	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).
RealmCallback	This callback is used by SaslClient and SaslServer to retrieve realm information.
RealmChoiceCallback	This callback is used by SaslClient and SaslServer to obtain a realm given a list of realm choices.
Sasl	A static class for creating SASL clients and servers.

Exception Summary

AuthenticationException	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.
SaslException	This class represents an error that has occurred when using SASL.

Package javax.security.sasl Description

Contains classes and interfaces for supporting SASL.

This package defines classes and interfaces for SASL mechanisms. It is used by developers to add authentication support for protocols that use SASL.

Using SASL Client Mechanisms

For developers adding SASL client support to a connection-based protocol, a typical usage pattern is as follows. In this discussion, SaslClient represents a SASL mechanism for the SASL client.

1. Use the Sasl class to create a SaslClient using its mechanism name and information that will be used during the exchange.
2. Invoke getMechanismName() to get the name of the mechanism selected.
3. If the protocol supports sending an initial response, use hasInitialResponse() to see if the mechanism has an initial response. If so, use evaluateChallenge() to get the initial response.
4. Create an authentication command containing the mechanism name and the optional initial response to initiate the exchange with the server. The format of the command is protocol-dependent.
5. Send the command to the server and read the reply from the server. This step is protocol-dependent. For example, in LDAP, the SASL command is sent to the LDAP server by using the LDAP "bind" request.
6. Use isComplete() to check whether authentication has finished.
7. If the client receives a challenge, any challenge data should be processed by invoking evaluateChallenge(). This method returns response data that is be sent in the command to the server (Step 5). Steps 5 through 7 are repeated until there are no more challenges or until evaluateChallenge() throws SaslException.

At the end of these steps, the authentication exchange should have succeeded, failed, or been aborted. If the authentication exchange has succeeded and a security layer was negotiated, the client then encodes and decodes data as per the negotiated security layer in its future communication with the server.

Producing SASL Client Mechanisms

As a developer who produces SASL client mechanisms, you need to define a class that implements the SaslClient interface and provide implementations for its methods. You also need to define a class that implements the SaslClientFactory interface to create instances of SaslClient for the mechanisms that you support.

Using SASL Server Mechanisms

For developers adding SASL server support to a connection-based protocol, a typical usage pattern is as follows. In this discussion, SaslServer represents a SASL mechanism for the SASL server.

1. When a SASL command is received from the client, use the Sasl class to create a SaslServer for handling the SASL mechanism identified by the SASL command.
2. Invoke evaluteResponse() on the SaslServer using the optional initial response that's in the SASL command. The result of evaluteResponse() contains the challenged data to be sent to the SASL client. If the result is null, that means that the protocol exchange has completed successfully. Some protocol profiles also include challenge data in a "success" result. So if the result is non-null, the server can check whether the SaslServer has completed by invoking isComplete().
3. Send the result to the client and, if expecting a response, read the reply from the SaslClient. How the command is sent and the reply read are dependent on the protocol driver. For example, for LDAP, the result is sent to the LDAP client using the LDAP "bind" response. For a challenge, the status code of that "bind" response would be LDAP_SASL_BIND_IN_PROGRESS.
4. Repeat steps 2 and 3 until the protocol exchange terminates.

At the end of these steps, the authentication exchange should have succeeded, failed, or been aborted. If the authentication exchange has succeeded and a security layer was negotiated, the server then encodes and decodes data as per the negotiated security layer in its future communication with the client.

Producing SASL Server Mechanisms

As a developer who produces SASL server mechanisms, you need to define a class that implements the SaslServer interface and provide implementations for its methods. You also need to define a class that implements the SaslServerFactory interface to create instances of SaslServer for the mechanisms that you support.

Using Callback Handlers

When using the Sasl class to create a SaslClient or SaslServer, one of the arguments that you supply is a callback handler. The callback handler is the means by which the SaslClient and SaslServer obtain information they need during the authentication exchange. It must be general enough to handle all of the callbacks that the SaslClient or SaslServer might invoke.

A SaslClient typically uses the callback handler to obtain authentication information from the application user, such as the user's identity, passphrase, PINs, etc. A SaslServer typically uses the callback handler to obtain data to verify the information supplied by the SASL client during the SASL exchange. For example, in order to verify the passphrase supplied by the client, the SaslServer might use the callback handler to obtain the passphrase of the corresponding user from the server's database.

Because the callback handler is responsible for interacting with sources of information, such as the end user or server databases, it can be a useful place to collect data and statistics, for example, for logging and account management purposes.

Security Considerations When Deploying Applications

The algorithm used to locate SASL client and server implementations is designed to be flexible and dynamically adaptable at runtime. Part of the algorithm searches for implementations specified in configuration files in the classpath of the application. When deploying an application that uses SASL, you need to take precaution against unwanted SASL implementations from being added to the application's classpath.