SSL and Custom Sockets

In addition to SASL authentication, most LDAP servers allow their services to be accessed through SSL. SSL is especially useful for LDAP v2 servers because the v2 protocol does not support SASL authentication.
An SSL-enabled server often supports SSL in two ways. In the most basic way, the server supports SSL ports in addition to normal (unprotected) ports. To use this service, the client needs to specify the port number of the SSL port in the Context.PROVIDER_URL property and use SSL sockets when communicating with the server. The other way in which a server supports SSL is via the use of the Start TLS Extension (RFC 2830). This option is available only to LDAP v3 servers and is described in detail in the Start TLS Extension section.
By default, Sun's LDAP service provider uses plain sockets when communicating with the LDAP server. To request that SSL sockets be use, set the Context.SECURITY_PROTOCOL property to "ssl".
In the following example, the LDAP server is offering SSL at port 636. To run this program, you must enable SSL on port 636 on your LDAP server. This procedure is typically carried out by the directory's administrator.
// 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:636/o=JNDITutorial");

// Specify SSL
env.put(Context.SECURITY_PROTOCOL, "ssl");

// Authenticate as S. User and password "mysecret"
env.put(Context.SECURITY_AUTHENTICATION, "simple");
env.put(Context.SECURITY_PRINCIPAL, "cn=S. 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
To run this program, you need to have an SSL implementation that implements the javax.net.SocketFactory abstract class (for details, see http://java.sun.com/j2se/1.4/docs/guide/security/jsse/JSSERefGuide.html). The SSL implementation must be available in your execution environment (such as the HotJava^TM Browser or the Java^TM Web Server) or be added to your classpath. The Java 2 SDK, v1.4 comes with an SSL implementation. If you are using another SDK or version, Sun also provides a standalone SSL implementation, Java Secure Socket Extension. See later in this section for additional information about Java SSL implementations.

Note: If you use SSL to connect to a server on a port that is not using SSL, then your program will hang. Similarly, if you use a plain socket to connect to a server's SSL socket, then your application will hang. This is a characteristic of the SSL protocol.

Using SSL with the External SASL Mechanism
SSL provides authentication and other security services at a lower layer than the LDAP. Since authentication has already been done, the LDAP layer can use that authentication information from SSL by using the External SASL mechanism.
The following example is like the previous SSL example, except that instead of using simple authentication, it uses the External SASL authentication. By using External, you do not need to supply any principal or password information, because they get picked up from the SSL.
// Set up the environment for creating the initial context
Hashtable env = new Hashtable(11);
env.put(Context.INITIAL_CONTEXT_FACTORY, 
    "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.PROVIDER_URL, "ldap://localhost:389/o=JNDITutorial");

// Principal and credentials will be obtained from the connection
env.put(Context.SECURITY_AUTHENTICATION, "EXTERNAL");

// Specify SSL
env.put(Context.SECURITY_PROTOCOL, "ssl");

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

...
Using Custom Sockets
When you set the Context.SECURITY_PROTOCOL property to "ssl", the LDAP provider will use the socket factory javax.net.ssl.SSLSocketFactory to attempt to create an SSL socket to communicate with the server. To use a different SSL implementation, you need to set the "java.naming.ldap.factory.socket" property to the class name of the socket factory that will produce SSL sockets. This class must implement the javax.net.SocketFactory abstract class (see http://java.sun.com/j2se/1.4/docs/guide/security/jsse/JSSERefGuide.html for details).
SSL sockets are but one type of socket. You can probably think of other types of sockets that might be useful, such as those for bypassing firewalls. You can use the "java.naming.ldap.factory.socket" environment property to specify other types of sockets to use. This is useful for setting the socket factory on a per connection basis. To set the socket factory for all sockets used in a program, use java.net.Socket.setSocketImplFactory(). Note that if Context.SECURITY_PROTOCOL is set to "ssl", then the "java.naming.ldap.factory.socket" property should specify a socket factory that produces SSL sockets.
Here is an example that creates an initial context by using a custom socket factory.
// 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:555/o=JNDITutorial");

// Specify the socket factory
env.put("java.naming.ldap.factory.socket", "com.widget.socket.MySocketFactory");

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

// ... do something useful with ctx
Java SSL Implementations
Other Java APIs, such as RMI, use SSL. The RMI documentation includes a list of issues related to RMI-SSL, including the Java SSL implementations available within and outside of the United States. For details, see http://java.sun.com/j2se/1.4/docs/guide/rmi/socketfactory/SSLInfo.html.

Security: End of Lesson
What's next? Now you can:

Continue on to the next lesson in this trail for tips on performing miscellaneous operations, such as reading nonstring attributes.
Go to the Searches lesson for examples of how to perform various types of searches.
Go to the Referrals lesson for tips on handling referrals.
Go to the Schema lesson for tips on accessing the schema.
Go to the Frequently Asked Questions lesson to read about questions that LDAP users have when using the JNDI.

Security