1. Introduction
   • What is SASL
   • The Java SASL API
   • When to Use SASL
2. API Overview
   • Creating the Mechanisms
   • Passing Input to the Mechanisms
   • Using the Mechanisms
   • Using the Negotiated Security Layer
3. How SASL Mechanisms are Installed and Selected
4. The SunSASL Provider
   • Client Mechanisms
   • Server Mechanisms
   • Debugging and Monitoring
5. Implementing a SASL Security Provider

SASL is used by protocols, such as the Lightweight Directory Access Protocol, version 3 (LDAP v3), and the Internet Message Access Protocol, version 4 (IMAP v4) to enable pluggable authentication. Instead of hardwiring an authentication method into the protocol, LDAP v3 and IMAP v4 use SASL to perform authentication, thus enabling authentication via various SASL mechanisms.

There are a number of standard SASL mechanisms defined by the Internet community for various levels of security and deployment scenarios. These range from no security (e.g., anonymous authentication) to high security (e.g., Kerberos authentication) and levels in between.

The Java SASL API

The Java SASL API also allows developers to use their own, custom SASL mechanisms. SASL mechanisms are installed by using the Java Cryptography Architecture (JCA).

When to Use SASL

When compared with JSSE and Java GSS, SASL is relatively lightweight and is popular among more recent protocols. It also has the advantage that several popular, lightweight (in terms infrastructure support) SASL mechanisms have been defined. Primary JSSE and Java GSS mechanisms, on the other hand, have relatively heavyweight mechanisms that require more elaborate infrastructures (Public Key Infrastructure and Kerberos, respectively).

SASL, JSSE, and Java GSS are often used together. For example, a common pattern is for an application to use JSSE for establishing a secure channel, and to use SASL for client, username/password-based authentication. There are also SASL mechanisms layered on top of GSS-API mechanisms; one popular example is a SASL GSS-API/Kerberos v5 mechanism that is used with LDAP.

Except when defining and building protocols from scratch, often the biggest factor determining which API to use is the protocol definition. For example, LDAP and IMAP are defined to use SASL, so software related to these protocols should use the Java SASL API. When building Kerberos applications and services, the API to use is Java GSS. When building applications and services that use SSL/TLS as their protocol, the API to use is JSSE. See the Java Security Documentation for further details about when to use JSSE versus Java GSS.

API Overview

The Java SASL API is modeled according to this style of interaction and usage. It has interfaces, SaslClient and SaslServer, that represent client-side and server-side mechanisms, respectively. The application interacts with the mechanisms via byte arrays that represent the challenges and responses. The server-side mechanism iterates, issuing challenges and processing responses, until it is satisfied, while the client-side mechanism iterates, evaluating challenges and issuing responses, until the server is satisfied. The application that is using the mechanism drives each iteration. That is, it extracts the challenge or response from a protocol packet and supplies it to the mechanism, and then puts the response or challenge returned by the mechanism into a protocol packet and sends it to the peer.

Creating the Mechanisms

The Sasl class is used for creating instances of SaslClient and SaslServer. Here is an example of how an application creates a SASL client mechanism using a list of possible SASL mechanisms.

String[] mechanisms = new String[]{"DIGEST-MD5", "PLAIN"};
SaslClient sc = Sasl.createSaslClient(mechanisms,
    authzid, protocol, serverName, props, callbackHandler);

The name of the selected mechanism is usually transmitted to the server via the application protocol. Upon receiving the mechanism name, the server creates a corresponding SaslServer object to process client-sent responses. Here is an example of how the server would create an instance of SaslServer.

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

Because the Java SASL API is a general framework, it must be able to accommodate many different types of mechanisms. Each mechanism needs to be initialized with input and may need input to make progress. The API provides three means by which an application gives input to a mechanism.

1. Common input parameters. The application uses predefined parameters to supply information that are defined by the SASL specification and commonly required by mechanisms. For SASL client mechanisms, the input parameters are authorization id, protocol id, and server name. For SASL server mechanisms, the common input parameters are prototol id and (its own fully qualified) server name.

2. Properties parameter. The application uses the properties parameter, a mapping of property names to (possibly non-string) property values, to supply configuration information. The Java SASL API defines some standard properties, such as quality-of-protection, cipher strength, and maximum buffer size. The parameter can also be used to pass in non-standard properties that are specific to particular mechanisms.

3. Callbacks. The application uses the callback handler parameter to supply input that cannot be predetermined or might not be common across mechanisms. When a mechanism requires input data, it uses the callback handler supplied by the application to collect the data, possibly from the end-user of the application. For example, a mechanism might require the end-user of the application to supply a name and password.

   Mechanisms can use the callbacks defined in the javax.security.auth.callback package; these are generic callbacks useful for building applications that perform authentication. Mechanisms might also need SASL-specific callbacks, such as those for collecting realm and authorization information, or even (non-standardized) mechanism-specific callbacks. The application should be able to accommodate a variety of mechanisms. Consequently, its callback handler must be able to service all of the callbacks that the mechanisms might request. This is not possible in general for arbitrary mechanisms, but is usually feasible due to the limited number of mechanisms that are typically deployed and used.

// Get optional initial response
byte[] response = 
    (sc.hasInitialResponse() ? sc.evaluateChallenge(new byte[]) : null);

String mechanism = sc.getName();

// Send selected mechanism name and optional initial response to server
send(mechanism, response);

// Read response
msg = receive();

while (!sc.isComplete() && (msg.status == CONTINUE || msg.status == SUCCESS)) {

    // Evaluate server challenge
    response = sc.evaluateChallenge(msg.contents);

    if (msg.status == SUCCESS) {
        // done; server doesn't expect any more SASL data
        if (response != null) {
           throw new IOException(
               "Protocol error: attempting to send response after completion");
        }
	break;
    } else {
        send(mechanism, response);
	msg = receive();
    }
}

Here is an example of how a server might use SaslServer.

// Read request that contains mechanism name and optional initial response
msg.receive();

// Obtain a SaslServer to perform authentication
SaslServer ss = Sasl.createSaslServer(msg.mechanism, 
    protocol, myName, props, callbackHandler);

// Perform authentication steps until done
while (!ss.isComplete()) {

    try {
        // Process response
        byte[] challenge = sc.evaluateResponse(msg.contents);

        if (ss.isComplete()) {
            send(mechanism, challenge, SUCCESS);
        } else {
            send(mechanism, challenge, CONTINUE);
	    msg.receive();
        }
    } catch (SaslException e) {
        send(ERROR);
	sc.dispose();
	break;
    }
}

When a security layer has been negotiated, all subsequent communication with the peer must take place using the security layer. To determine whether a security layer has been negotiated, get the negotiated quality-of-protection (QOP) from the mechanism. Here is an example of how to determine whether a security layer has been negotiated.

String qop = (String) sc.getNegotiatedProperty(Sasl.QOP);
boolean hasSecurityLayer = (qop != null && 
    (qop.equals("auth-int") || qop.equals("auth-conf")));

To communicate with the peer using the negotiated layer, the application first uses the wrap method to encode the data to be sent to the peer to produce a "wrapped" buffer. It then transfers a length field representing the number of octets in the wrapped buffer followed by the contents of the wrapped buffer to the peer. The peer receiving the stream of octets passes the buffer (without the length field) to unwrap to obtain the decoded bytes sent by the peer. Details of this protocol are described in RFC 2222. Here is an example of how a client application sends and receives application data using a security layer.

// Send outgoing application data to peer
byte[] outgoing = ...;
byte[] netOut = sc.wrap(outgoing, 0, outgoing.length);

send(netOut.length, netOut);   // send to peer

// Receive incoming application data from peer
byte[] netIn = receive();      // read length and ensuing bytes from peer

byte[] incoming = sc.unwrap(netIn, 0, netIn.length);

security.provider.7=com.sun.security.sasl.Provider

To add or remove a SASL provider, you add or remove the corresponding line in the Security Properties file. For example, if you want to add a SASL provider and have its mechanisms be chosen over the same ones implemented by the SunSASL provider, then you would add a line to the Security Properties file with a lower number.

security.provider.7=com.example.MyProvider
security.provider.8=com.sun.security.sasl.Provider

Alternatively, you can programmatically add your own provider using the java.security.Security class. For example, the following sample code registers the com.example.MyProvider to the list of available SASL security providers.

Security.addProvider(new com.example.MyProvider());

The selection policy properties specify the security aspects of a mechanism, such as its susceptibility to certain attacks. These are characteristics of the mechanism (definition), rather than its implementation so all providers should come to the same conclusion about a particular mechanism. For example, the PLAIN mechanism is susceptible to plaintext attacks regardless of how it is implemented. If no selection policy properties are supplied, there are no restrictions on the selected mechanism. Using these properties, an application can ensure that it does not use unsuitable mechanisms that might be deployed in the execution environment. For example, an application might use the following sample code if it does not want to allow the use of mechanisms susceptible to plaintext attacks.

Map props = new HashMap();
props.add(Sasl.POLICY_NOPLAINTEXT, "true");
SaslClient sc = Sasl.createSaslClient(mechanisms,
    authzid, protocol, serverName, props, callbackHandler);

• Client Mechanisms
  • PLAIN (RFC 2595). This mechanism supports cleartext username/password authentication.
  • CRAM-MD5 (RFC 2195). This mechanism supports a hashed username/password authentication scheme.
  • DIGEST-MD5 (RFC 2831). This mechanism defines how HTTP Digest Authentication can be used as a SASL mechanism.
  • GSSAPI (RFC 2222). This mechanism uses the GSSAPI for obtaining authentication information. It supports Kerberos v5 authentication.
  • EXTERNAL (RFC 2222). This mechanism obtains authentication information from an external channel (such as TLS or IPsec).

• Server Mechanisms
  • CRAM-MD5
  • DIGEST-MD5
  • GSSAPI (Kerberos v5)

Client Mechanism Name	Parameters/Input	Callbacks	Configuration Properties	Selection Policy
CRAM-MD5	authorization id (as default username)	NameCallback PasswordCallback		Sasl.POLICY_NOANONYMOUS Sasl.POLICY_NOPLAINTEXT
DIGEST-MD5	authorization id protocol id server name	NameCallback PasswordCallback RealmCallback RealmChoiceCallback	Sasl.QOP Sasl.STRENGTH Sasl.MAX_BUFFER Sasl.SERVER_AUTH "javax.security.sasl.sendmaxbuffer" "com.sun.security.sasl.digest.cipher"	Sasl.POLICY_NOANONYMOUS Sasl.POLICY_NOPLAINTEXT
EXTERNAL	authorization id external channel			Sasl.POLICY_NOPLAINTEXT Sasl.POLICY_NOACTIVE Sasl.POLICY_NODICTIONARY
GSSAPI	JAAS Subject authorization id protocol id server name		Sasl.QOP Sasl.MAX_BUFFER Sasl.SERVER_AUTH "javax.security.sasl.sendmaxbuffer"	Sasl.POLICY_NOACTIVE Sasl.POLICY_NOANONYMOUS Sasl.POLICY_NOPLAINTEXT
PLAIN	authorization id	NameCallback PasswordCallback		Sasl.POLICY_NOANONYMOUS

An application that uses these mechanisms from the SunSASL provider must supply the required parameters, callbacks and properties. The properties have reasonable defaults and only need to be set if the application wants to override the defaults. Most of the parameters, callbacks, and properties are described in the API documentation. The following sections describe mechanism-specific behaviors and parameters not already covered by the API documentation.

Cram-MD5

Digest-MD5

The Sasl.STRENGTH property supports "high", "medium", and "low" settings; its default is "high,medium,low". The ciphers are mapped to the strength settings as follows.

Strength	Cipher	Cipher Id
high	Triple DES RC4 128 bits	3des rc4
medium	DES RC4 56 bits	des rc4-56
low	RC4 40 bits	rc4-40

When there is more than one choice for a particular strength, the cipher selected depends on the availability of the ciphers in the underlying platform. To explicitly name the cipher to use, set the "com.sun.security.sasl.digest.cipher" property to the corresponding cipher id. Note that this property setting must be compatible with Sasl.STRENGTH and the ciphers available in the underlying platform. For example, Sasl.STRENGTH being set to "low" and "com.sun.security.sasl.digest.cipher" being set to "3des" are incompatible. The "com.sun.security.sasl.digest.cipher" property has no default.

The "javax.security.sasl.sendmaxbuffer" property specifies (the string representation of) the maximum send buffer size in bytes. The default is 65536. The actual maximum number of bytes will be the minimum of this number and the peer's maximum receive buffer size.

GSSAPI

LoginContext lc = new LoginContext("JaasSample", new TextCallbackHandler());
lc.login();
lc.getSubject().doAs(new SaslAction());

class SaslAction implements java.security.PrivilegedAction {
   public class run() {
       ...
       String[] mechanisms = new String[]{"GSSAPI"};
       SaslClient sc = Sasl.createSaslClient(mechanisms,
           authzid, protocol, serverName, props, callbackHandler);
       ...
   }
}

The "javax.security.sasl.sendmaxbuffer" property specifies (the string representation of) the maximum send buffer size in bytes. The default is 65536. The actual maximum number of bytes will be the minimum of this number and the peer's maximum receive buffer size.

Server Mechanisms

Server Mechanism Name	Parameters/Input	Callbacks	Configuration Properties	Selection Policy
CRAM-MD5	server name	AuthorizeCallback NameCallback PasswordCallback		Sasl.POLICY_NOANONYMOUS Sasl.POLICY_NOPLAINTEXT
DIGEST-MD5	protocol id server name	AuthorizeCallback NameCallback PasswordCallback RealmCallback	Sasl.QOP Sasl.STRENGTH Sasl.MAX_BUFFER "javax.security.sasl.sendmaxbuffer" "com.sun.security.sasl.digest.realm" "com.sun.security.sasl.digest.utf8"	Sasl.POLICY_NOANONYMOUS Sasl.POLICY_NOPLAINTEXT
GSSAPI	JAAS Subject protocol id server name	AuthorizeCallback	Sasl.QOP Sasl.MAX_BUFFER "javax.security.sasl.sendmaxbuffer"	Sasl.POLICY_NOACTIVE Sasl.POLICY_NOANONYMOUS Sasl.POLICY_NOPLAINTEXT

An application that uses these mechanisms from the SunSASL provider must supply the required parameters, callbacks and properties. The properties have reasonable defaults and only need to be set if the application wants to override the defaults.

All users of server mechanisms must have a callback handler that deals with the AuthorizeCallback. This is used by the mechanisms to determine whether the authenticated user is allowed to act on behalf of the requested authorization id, and also to obtain the canonicalized name of the authorized user (if canonicalization is applicable).

Most of the parameters, callbacks, and properties are described in the API documentation. The following sections describe mechanism-specific behaviors and parameters not already covered by the API documentation.

Cram-MD5

Digest-MD5

The "javax.security.sasl.sendmaxbuffer" property is described in the Digest-MD5 client section.

The "com.sun.security.sasl.digest.realm" property is used to specify a list of space-separated realm names that the server supports. The list is sent to the client as part of the challenge. If this property has not been set, the default realm is the server's name (supplied as a parameter).

The "com.sun.security.sasl.digest.utf8" property is used to specify the character encoding to use. "true" means to use UTF-8 encoding; "false" means to use ISO Latin 1 (ISO-8859-1). The default is "true".

GSSAPI

javax.security.sasl.level=FINEST
handlers=java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.level=FINEST

The table below shows the mechanisms and the logging output that they generate.

Mechanism	Logging Level	Information Logged
CRAM-MD5	FINE	Configuration properties; challenge/response messages
DIGEST-MD5	INFO	Message discarded due to encoding problem (e.g., unmatched MACs, incorrect padding)
DIGEST-MD5	FINE	Configuration properties; challenge/response messages
DIGEST-MD5	FINER	More detailed information about challenge/response messages
DIGEST-MD5	FINEST	Buffers exchanged at the security layer
GSSAPI	FINE	Configuration properties; challenge/response messages
GSSAPI	FINER	More detailed information about challenge/response messages
GSSAPI	FINEST	Buffers exchanged at the security layer

Implementing a SASL Security Provider

1. Write a class that implements the SaslClient or SaslServer interface.
2. Write a factory class (that implements SaslClientFactory or SaslServerFactory) that creates instances of the class.
3. Write a JCA provider that registers the factory.

The first step involves providing an implementation for the SASL mechanism. To implement a client mechanism, you need to implement the methods declared in the SaslClient interface. Similarly, for a server mechanism, you need to implement the methods declared in the SaslServer interface. For the purposes of this discussion, suppose you are developing an implementation for the client mechanism "SAMPLE-MECH", implemented by the class, com.example.SampleMechClient. You must decide what input are needed by the mechanism and how the implementation is going to collect them. For example, if the mechanism is username/password-based, then the implementation would likely need to collect that information via the callback handler parameter.

The next step involves providing a factory class that will create instances of com.example.SampleMechClient. The factory needs to determine the characteristics of the mechanism that it supports (as described by the Sasl.POLICY_* properties) so that it can return an instance of the mechanism when the API user requests it using compatible policy properties. The factory may also check for validity of the parameters before creating the mechanism. For the purposes of this discussion, suppose the factory class is named com.example.MySampleClientFactory. Although our sample factory is responsible for only one mechanism, a single factory can be responsible for any number of mechanisms.

The final step involves creating a JCA provider. The steps for creating a JCA provider is described in detail in the document, How to Implement a Provider for the Java Cryptography Architecture. SASL client factories are registered using property names of the form

SaslClientFactory.mechName

SaslServerFactory.mechName

put("SaslClientFactory.SAMPLE-MECH",  "com.example.MySampleClientFactory");