11.1. Introduction to SSL in the Directory Server

11.1. Introduction to SSL in the Directory Server

The Directory Server supports TLS/SSL to secure communications between LDAP clients and the Directory Server, between Directory Servers that are bound by a replication agreement, or between a database link and a remote database. Directory Server can use TLS/SSL with simple authentication (bind DN and password) or with certificate-based authentication.

Directory Server's cryptographic services are provided by Mozilla Network Security Services (NSS), a library of TLS/SSL and base cryptographic functions. NSS includes a software-based cryptographic token which is FIPS 140-2 certified.

Using TLS/SSL with simple authentication ensures confidentiality and data integrity. There are two major benefits to using a certificate — smart card, token, or software-based — to authenticate to the Directory Server instead of a bind DN and password:

The Directory Server is capable of simultaneous TLS/SSL and non-SSL communications. This means that you do not have to choose between TLS/SSL or non-SSL communications for the Directory Server; both can be used at the same time. Directory Server can also utilize the Start TLS extended operation to allow TLS/SSL secure communication over a regular (insecure) LDAP port.

11.1.1. Enabling SSL: Summary of Steps

To configure the Directory Server to use LDAPS, follow these steps:

  1. Obtain and install a certificate for the Directory Server, and configure the Directory Server to trust the certification authority's (CA's) certificate.

    For information, see Section 11.2, “Obtaining and Installing Server Certificates”.

  2. Turn on SSL in the directory.

    For information, refer to Section 11.4, “Starting the Server with SSL Enabled”.

  3. Configure the Administration Server connect to an SSL-enabled Directory Server.

  4. Optionally, ensure that each user of the Directory Server obtains and installs a personal certificate for all clients that will authenticate with TLS/SSL.

    For information, refer to Section 11.7, “Configuring LDAP Clients to Use SSL”.

11.1.2. Command-Line Functions for Start TLS

LDAP operations such as ldapmodify, ldapsearch, and ldapdelete can use TLS/SSL when communicating with an SSL-enabled server or to use certificate authentication. Command-line options also specify or enforce Start TLS, which which allows a secure connection to be enabled on a clear text port after a session has been initiated.


These options to use Start TLS applies only for the Mozilla LDAP tools provided with Red Hat Directory Server.

In the following example, a network administrator enforces Start TLS for a search for Mike Connor's identification number:

ldapsearch -p 389 -ZZZ -P certificateDB -s base 
    -b "uid=mconnors,ou=people,dc=example,dc=com" "(attribute=govIdNumber)"

-ZZZ enforces Start TLS, and certificateDB gives the filename and path to the certificate database.


The -ZZZ option enforces the use of Start TLS, and the server must respond that a Start TLS command was successful. If the -ZZZ command is used and the server does not support Start TLS, the operation is aborted immediately.

For information on the command-line options available, see the Directory Server Configuration, Command, and File Reference. Troubleshooting Start TLS

With the -ZZ option, the following errors could occur:

With the -ZZZ option, the following errors could occur, causing the Start TLS operation to fail:

For SDK libraries used in client programs, if a session is already in TLS mode and Start TLS is requested, then the connection continues to be in secure mode but prints the error "DSA is unwilling to perform".

Note: This documentation is provided {and copyrighted} by Red Hat®, Inc. and is released via the Open Publication License. The copyright holder has added the further requirement that Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder. The CentOS project redistributes these original works (in their unmodified form) as a reference for CentOS-5 because CentOS-5 is built from publicly available, open source SRPMS. The documentation is unmodified to be compliant with upstream distribution policy. Neither CentOS-5 nor the CentOS Project are in any way affiliated with or sponsored by Red Hat®, Inc.