Client Mechanisms

The IBMSASL provider supports several SASL mechanisms used in popular protocols such as LDAP, IMAP, and SMTP. The following table summarizes the client mechanisms and their required input.

An application that uses these mechanisms from the IBMSASL 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

The Cram-MD5 client mechanism uses the authorization ID parameter, if supplied, as the default username in the NameCallback

to solicit the application/end-user for the authentication ID. The authorization ID is otherwise not used by the Cram-MD5 mechanism; only the authentication ID is exchanged with the server.

Digest-MD5

The Digest-MD5 mechanism is used for digest authentication and optional establishment of a security layer. It specifies the following ciphers for use with the security layer: Triple DES, DES and RC4 (128, 56, and 40 bits). The Digest-MD5 mechanism can support only ciphers that are available on the platform. For example, if the platform does not support the RC4 ciphers, then the Digest-MD5 mechanism will not use those ciphers.

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.

Table 2. Mapping of strength settings to ciphers

Strength	Cipher	Cipher Id
high	TripleDES RC4128bits	3des rc4
medium	DES RC456bits	des rc4-56
low	RC440bits	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.ibm.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.ibm.security.sasl.digest.cipher being set to 3des are incompatible. The com.ibm.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 peers maximum receive buffer size.

GSSAPI

The GSSAPI mechanism is used for Kerberos v5 authentication and optional establishment of a security layer. The mechanism expects the calling threads Subject to contain the clients Kerberos credentials or that the credentials could be obtained by implicitly logging in to Kerberos. To obtain the clients Kerberos credentials, use the Java™ Authentication and Authorization Service (JAAS) to log in using the Kerberos login module. See the Java GSS-API and JAAS Tutorials for Use with Kerberos for details and examples. After using JAAS authentication to obtain the Kerberos credentials, you put the code that uses the SASL GSSAPI mechanism within doAs or doAsPrivileged.

    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);
          ...
         }
    }

To obtain Kerberos credentials without doing explicit JAAS programming, see the Java GSS-API and JAAS Tutorials for Use with Kerberos. When using this approach, there is no need to wrap the code within doAs or doAsPrivileged.

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 peers maximum receive buffer size.

NTLM

The NTLM mechanism uses the authorization id parameter, to solicit user for the authentication ID. It also uses domain ID to solicit the server domain.

The com.ibm.security.sasl.ntlm.version String property, names a specific version to use; it can be:

• LM/NTLM: Original NTLM v1
• LM: Original NTLM v1,
• LM only NTLM: Original NTLM v1,
• NTLM only
• NTLM2: NTLM v1 with Client Challenge
• LMv2/NTLMv2: NTLM v2
• LMv2: NTLM v2, LM only
• NTLMv2: NTLM v2, NTLM only

If not specified, use system property ntlm.version. If still not specified, use default value LMv2/NTLMv2.

The com.ibm.security.sasl.ntlm.random, the nonce source to be used in NTLM v2 or NTLM v1 with Client Challenge. Default null, an internal java.util.Random object will be used