| Security

## 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 HotJavaTM Browser or the JavaTM 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/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