CRAM-MD5 Authentication

CRAM-MD5 authentication is one of the SASL mechanisms (RFC 2222) that was at one point proposed as a required mechanism for LDAP v3 servers. It has since been superceded by DIGEST-MD5, but some existing servers, such as the Netscape Directory Server, support CRAM-MD5.
Because the use of SASL is part of the LDAP v3 (RFC 2251), servers that support only the LDAP v2 do not support CRAM-MD5.
When using the CRAM-MD5 mechanism, the LDAP server sends some data to the LDAP client, and the client responds by encrypting the data with its password using the MD5 algorithm. The LDAP server then uses the client's stored password to determine whether the client used the right password.
To use the CRAM-MD5 authentication mechanism, you must set the authentication environment properties as follows:

Context.SECURITY_AUTHENTICATION("java.naming.security.authentication")
The value is the string "CRAM-MD5".

Context.SECURITY_PRINCIPAL("java.naming.security.principal")
According to draft-ietf-ldapext-authmeth-04.txt, the name here should be the string "dn:" followed by the fully qualified distinguished name of the entity being authenticated, or the string "u:" followed by the user id. Which of these two forms is required depends on the LDAP server implementation. Examples of each are "dn: cn=C. User, ou=NewHires, o=JNDITutorial" and "u: cuser". An earlier draft of this proposal did not have the "dn:" prefix, so some servers might simply accept the fully qualified distinguished name of the entity being authenticated (e.g., "cn=C. User, ou=NewHires, o=JNDITutorial"). Check with the LDAP server that you are using to see what name it expects. In any case, the data type of this property must be java.lang.String.

Context.SECURITY_CREDENTIALS("java.naming.security.credentials")
The password of the principal (e.g., "mysecret"). It is of type java.lang.String, char array (char[]), or byte array (byte[]). If the password is a java.lang.String or char[], it is encoded using UTF-8 for transmission to the server. If the password is a byte[], it is transmitted as is to the server.

Note: If you supply an empty string, an empty byte/char array or null to the Context.SECURITY_CREDENTIALS environment property, the authentication mechanism will be "none" regardless of the setting of Context.SECURITY_AUTHENTICATION. This is because the LDAP requires the password to be nonempty for doing any type of authentication and so the protocol automatically converts the authentication to "none" if a password is not supplied.

The following example shows how a client performs authentication using CRAM-MD5 to an LDAP server.
// Set up environment for creating initial context
Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY, 
    "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.PROVIDER_URL, "ldap://localhost:389/o=JNDITutorial");

// Authenticate as C. User and password "mysecret"
env.put(Context.SECURITY_AUTHENTICATION, "CRAM-MD5");
env.put(Context.SECURITY_PRINCIPAL, "cn=C. User, ou=NewHires, o=JNDITutorial");
env.put(Context.SECURITY_CREDENTIALS, "mysecret");

// Create initial context
DirContext ctx = new InitialDirContext(env);

// ... do something useful with ctx
Note: The Netscape Directory Server 4.1 supports the CRAM-MD5 authentication mechanism only if you install some additional software on the server. Otherwise, attempting to use CRAM-MD5 with the server results in a CommunicationException being thrown.

Security