Configuring SSL and StartTLS for LDAP and JMX

When you have configured Oracle Unified Directory with at least one enabled key manager provider and at least one enabled trust manager provider, you can enable SSL and StartTLS for the connection handlers.

The examples in this section use the dsconfig command to modify the server configuration. The dsconfig command accesses the server configuration over SSL via the administration connector. As such, the relevant connection options must be specified, including how the SSL certificate is trusted. These examples use the -X option to trust all certificates.

Configuring the LDAP and LDAPS Connection Handlers

The LDAP connection handler is responsible for managing all communication with clients using LDAP. By default, the LDAP protocol does not specify any form of security for protecting that communication, but it can be configured to use SSL or also to allow the use of the StartTLS extended operation.

The server configures two connection handlers that can be used for this purpose. While the LDAP connection handler entry is enabled by default and is used to perform unencrypted LDAP communication, it can also be configured to support StartTLS. For information, see To Enable StartTLS Support. The LDAPS connection handler entry is disabled, but the default configuration is set up for To Enable SSL-Based Communication.

The following sections describe how to configure LDAP and LDAPS connection handler parameters with dsconfig.

To Enable a Connection Handler

Set the enabled property of the connection handler to true.

This example enables the LDAP connection handler.

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X \
  set-connection-handler-prop --handler-name "LDAP Connection Handler" \
  --set enabled:true

To Specify a Connection Handler's Listening Port

Set the listen-port property of the connection handler.
The listen-port property specifies the port number to use when communicating with the server through this connection handler. The standard port to use for unencrypted LDAP communication (or LDAP using StartTLS) is 389, and the standard port for SSL-encrypted LDAP is 636. However, it might be desirable or necessary to change this in some environments (for example, if the standard port is already in use, or if you are running on a UNIX system as a user without sufficient privileges to bind to a port below 1024).
This example sets the LDAPS connection handler's listen port to 1636.
```
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X \
  set-connection-handler-prop --handler-name "LDAPS Connection Handler" \
  --set listen-port:1636
```

To Specify a Connection Handler's Authorization Policy

Set the ssl-client-auth-policy property of the connection handler.
The ssl-client-auth-policy property specifies how the connection handler should behave when requesting a client certificate during the SSL or StartTLS negotiation process. If the value is optional, the server requests that the client present its own certificate but still accepts the connection even if the client does not provide a certificate. If the value is required, the server requests that the client present its own certificate and rejects any connection in which the client does not do so. If the value is disabled, the server does not ask the client to present its own certificate.
This example sets the LDAPS connection handler's authorization policy to required.
```
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X \
  set-connection-handler-prop --handler-name "LDAPS Connection Handler" \
  --set ssl-client-auth-policy:required
```

To Specify a Nickname for a Connection Handler's Certificate

Set the ssl-cert-nickname property of the connection handler.
The ssl-cert-nickname property specifies the nickname of the certificate that the server presents to clients during SSL or StartTLS negotiation. This property is primarily useful when multiple certificates are in the keystore and you want to specify which certificate is to be used for that listener instance.
This example sets the nickname of the LDAP connection handler's certificate to server-cert.
```
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X \
  set-connection-handler-prop --handler-name "LDAP Connection Handler" \
  --set ssl-cert-nickname:server-cert
```

To Specify a Connection Handler's Key Manager Provider

Set the key-manager-provider property of the connection handler.
The key-manager-provider property specifies which key manager provider among the available Configuring Key Manager Providers that should be used by the connection handler to obtain the key material for the SSL or StartTLS negotiation.
This example sets the LDAP connection handler's key manager provider to JKS. The specified manager must already be configured for the command to succeed.
```
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X \
  set-connection-handler-prop --handler-name "LDAP Connection Handler" \
  --set key-manager-provider:JKS
```

To Specify a Connection Handler's Trust Manager Provider

Set the trust-manager-provider property of the connection handler.
The trust-manager-provider property specifies which trust manager provider among the available Configuring Trust Manager Providers to be used by the connection handler to decide whether to trust client certificates presented to it.
This example sets the LDAP connection handler's trust manager to JKS. The specified manager must already be configured for the command to succeed.
```
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X \
  set-connection-handler-prop --handler-name "LDAP Connection Handler" \
  --set trust-manager-provider:JKS
```

To Enable StartTLS Support

Specify the appropriate values for the key-manager-provider and trust-manager-provider properties.
Set the allow-start-tls property to true, as follows:
```
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X \
  set-connection-handler-prop --handler-name "LDAP Connection Handler" \
  --set allow-start-tls:true
```
Note - If SSL is enabled, the allow-start-tls property cannot be set.
StartTLS is not supported for connections between the Oracle Unified Directory proxy and the remote LDAP servers. Depending on the setting of the remote LDAP server SSL policy, StartTLS client connections can be passed from the proxy to the remote LDAP servers as SSL connections or as insecure connections. For more information, see To Create a Global Index Catalog Containing Global Indexes.

To Enable SSL-Based Communication

Display the connection handler properties to ensure that the configured key manager provider and trust manager provider values are correct.
The following example displays the properties of the LDAPS connection handler:
```
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X \
  get-connection-handler-prop --handler-name "LDAPS Connection Handler"
```

Set the enabled property to true, as follows:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X \
  set-connection-handler-prop --handler-name "LDAPS Connection Handler" \
  --set enabled:true

Note - If SSL is enabled, non-SSL communication will not be available for that connection handler instance.

Enabling SSL in the JMX Connection Handler

The JMX connection handler can be used to communicate with clients using the JMX (Java Management Extensions) protocol. This protocol does not support the use of StartTLS to allow both encrypted and unencrypted communication over the same port, but it can be configured to accept only unencrypted JMX or only SSL-encrypted JMX communication.

The JMX connection handler provides the server's default configuration for communicating over JMX. To enable SSL for this connection handler, use dsconfig to set the following configuration attributes:

key-manager-provider. Specifies the DN of the configuration entry for the key manager provider that is used to obtain the key material for the SSL negotiation.
ssl-cert-nickname. Specifies the nickname (or alias) of the certificate that is presented to clients.
use-ssl. Indicates whether the connection handler is to use SSL to communicate with clients.

The following example uses dsconfig to configure the JMX connection handler:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X \
  set-connection-handler-prop --handler-name "JMX Connection Handler"

Skip Navigation Links
Exit Print View
	Oracle Fusion Middleware Administration Guide for Oracle Unified Directory 11g Release 1 (11.1.1)