| 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`.
>   Set to the string `"CRAM-MD5"`.
> `Context.SECURITY_PRINCIPAL`.
>   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`.
>   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.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 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`'s being thrown. See the server's documentation for instructions on how to obtain and install the software.

| Security