Previous | Next | Trail Map | Tips for LDAP Users | Security

CRAM-MD5 Authentication

CRAM-MD5 authentication was at one point proposed as a required mechanism for LDAP v3 servers. It has since been superseded by Digest-MD5 as the required mechanism. However, some existing servers still support CRAM-MD5. CRAM-MD5 is supported only by LDAP v3 servers.

When using the CRAM-MD5 mechanism, the LDAP server sends some data to the LDAP client. The client responds by encrypting the data with its password by 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(in the API reference documentation).
Set to the string "CRAM-MD5".
Context.SECURITY_PRINCIPAL(in the API reference documentation).
Set to the principal name. This is a server-specific format. Some servers support a login user id format, such as that defined for Unix or Windows login screens. Others accept a distinguished name. Some servers accept multiple formats. Examples of some of these formats are "cuser", "cn=C. User, ou=NewHires, o=JNDITutorial", and "u: cuser" The data type of this property must be java.lang.String.
Context.SECURITY_CREDENTIALS(in the API reference documentation).
Set to 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[], then it is encoded by using UTF-8 for transmission to the server. If the password is a byte[], then it is transmitted as is to the server.

The following example shows how a client performs authentication by using CRAM-MD5 to an LDAP server.

// Set up the environment for creating the initial context
Hashtable env = new Hashtable();
env.put(Context.PROVIDER_URL, "ldap://localhost:389/o=JNDITutorial");

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

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

// ... do something useful with ctx

Note: The Netscape Directory Server v4.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(in the API reference documentation)'s being thrown. See the server's documentation for instructions on how to obtain and install the software.

Previous | Next | Trail Map | Tips for LDAP Users | Security