TLSv1SSL Protocol Support

TLSv1/SSL Protocol Support

This section discusses the Transport Layer Security (TLS) and how it provides the encrypted communications between two hosts , such as a directory server and client. The topic is covered in two categories:

  • Server (directory server)

  • Client (Secured LDAP Client)

To dispel any misunderstandings you might have, this section explains the differences between TLS and SSL.

SSL Background

The Secure Sockets Layer (SSL) was originally designed for the World Wide Web (WWW) environment to provide a secure channel between two machines. The SSL protocol has gone through various incarnations, beginning with version 1, and evolving into it's present state with its adoption be the Internet Engineering Task Force (IETF), which is now referred to as the Transport Layer Security (TLS) standard.

All the previous versions of the SSL protocol were developed by engineers who worked for Netscape Communications. Netscape's intention was to develop a security model whereby they could provide a single solution to address all the security issues around not only the Web, but also messaging, and news.

TABLE 3-2 shows the development cycle of SSL/TLS.

Table 3-2. SSL and TLS Development Cycle

SSL / TLS Protocol Version



Developed by Netscape in 1994, but was never released.


Developed by Netscape in 1994, and the first release.


Developed by Netscape in 1995, and provided authentication only.


Adoption by the IETF in 1997. Provided new functionality such as a new MAC algorithm and new key expansion.


The goal of SSLv2 was to provide a secure channel between two hosts on the WWW environment. With this in mind, the SSL protocol needed to fit in well with the HTTP protocol, which is used by the Web. Netscape also wanted to provide a single security solution, which meant that this solution would have to work with other protocols and not just HTTP. Unfortunately, not all protocols use or require the same security properties.


There is no question that SSLv2 was widely adopted resulting in a great deal of popularity, thus ensuring that the design goals and principles of SSLv2 were carried forward into SSLv3. The main goal for SSLv3 was to fix a number of security problems found in SSLv2. This meant designing a more secure model that could negotiate multiple cryptographic algorithms. The end result is that SSLv3 supports many more multiple cryptographic algorithms.

TLS Background

In 1996 the IETF chartered the Transport Layer Security (TLS) working group to attempt to standardize an SSL-like protocol. It became apparent early on that there was very little support for changing the existing SSLv3 protocol, with the exception of a few minor bugs and enhancements. To this end, the new protocol just became a minor cleanup of SSLv3.

Understanding TLSv1 Transport Support

In your directory server (LDAP) deployment, it is highly likely that you have some form of security requirements that must be addressed. Specific security requirements are different from one organization to another. For example, a directory server (LDAP) that is available on the Internet has very specific security needs.

To provide secure communications over a network, your directory server (in particular, the Sun ONE Directory Server), includes and supports the LDAPS communications protocol. LDAPS (LDAP over SSL) is the standard LDAP protocol, which runs on top of the Secure Sockets Layer (SSL).

It is possible to not only use TLSv1 protocol to secure communications between a directory server (LDAP) and directory clients (LDAP), but also between directory servers (LDAP) that are bound by a replication agreement, or between a database link and a remote database. You can use TLSv1 with Simple authentication (bind DN and password), or with certificate-based authentication.

Two kinds of authentication mechanisms can be performed using TLSv1:

  • Server authentication

  • Client authentication

With server authentication, the client decides whether it trusts the certificate presented by the server. With client authentication, the client decides whether it trusts the certificate presented by the server, and the server decides whether it trusts the certificate presented by the client. In the case of server authentication, the client is not authenticated to the server at all. In the case of client authentication, the client may be authenticated to the server if it also performs a bind using the SASL EXTERNAL mechanism.

Using TLSv1 with the Simple authentication mechanism guarantees confidentiality and data integrity. One of the benefits of using a certificate to authenticate to the Directory Server (LDAP) instead of a bind DN and password is improved security.

The use of the certificate-based authentication mechanism is more secure than noncertificate bind operations. This is because certificate-based authentication uses public-key cryptography. As a result, bind credentials cannot be intercepted across the network.

The Sun ONE Directory Server software is capable of simultaneous TLSv1 and non-SSL communications. This means that you do not have to choose between TLSv1 or non-SSL communications for your directory server, because you can use both at the same time.

But one of the downsides to using TLSv1 is reduced efficiency.

The process of data encryption, with generally DES or RC4 does significantly reduce the throughput that can be achieved, and the initial negotiation and key agreement with RSA or DSA is even more expensive. There are potentially three cases for which you must be considered when dealing with the performance impact of TLSv1 in the Sun ONE Directory Server 5.2 software:

  • Clients establish a connection over TLSv1 and maintain that connection for a number of operations (persistent connections). This is the best scenario for TLSv1 because the process of initializing the TLSv1-based connection is the most expensive part. In this case, using TLSv1 will introduce degradation over the performance when not using TLSv1.

  • Clients establish a connection over TLSv1, perform one or two operations (for example, a bind and a search), close the connection, and then repeat. That is, the same system or set of systems are repeatedly used to establish short-lived TLSv1-based connections. This is much less efficient because as indicated above, the process of establishing TLSv1-based connections is rather expensive. However, it is not as bad as it could be because the same TLSv1 session (which is also expensive to set up) can be re-used across multiple TCP connections.

  • Different client systems establish a connection over TLSv1, perform one or two operations (for example, a bind and a search), and then close the connection. That is, different systems are used to establish short-lived SSL-based connections. This is the least efficient of the three scenarios because the TLSv1 sessions cannot be reused across the different TCP connections, which means that the full negotiation process must be performed for each new connection. This case is a very uncommon scenario for real-world directory use.

Why Use TLSv1?

TLSv1 is used to protect sensitive information. Data that travels over a network is visible to a number of other machines on that network. This is especially of concern for information traveling over the Internet. Normally, the other machines simply ignore the information if it isn't intended for them, but that isn't necessarily the case. Most network interfaces support a feature known as promiscuous mode, in which they sue to pay attention to all traffic and not just information that pertains specifically to that machine. This can be a very helpful diagnostic feature for network administrators or even people that support a product that works in a networked environment. Applications like snoop (included in the Solaris OE) or the Network Monitor that comes with Windows NT, provide a mechanism for capturing and displaying that information. These applications are often called sniffers or protocol analyzers. More advanced protocol analyzers like Ethereal (available for free on a number of platforms, or as source code from can even interpret the information that is captured so that it can be more easily understood by the user . This is helpful with text-based protocols like HTTP because it provides formatting for the request. It is invaluable for binary protocols like LDAP because otherwise the task of decoding the information and figuring out exactly what was going on between the client and the server is much more difficult.

Sniffers can be very helpful tools when trying to track down problems that are occurring in a networked environment. However, they can also be very helpful tools to those with less honorable intentions. They make it easy to see any information that is transferred over the network, so it is possible to capture sensitive information like credit card numbers being used to buy a product on the Web, passwords being used to bind to a directory server, or any other kind of information that would otherwise be protected. Using TLSv1 can thwart these attempts because the encrypted information is completely unintelligible except to the two machines that are having the conversation.

The layer of privacy provided by TLSv1 does not come without a price. Because TLSv1 is used to encapsulate information in another protocol, each machine must deal with the extra overhead of encrypting information before sending it over the network, and decrypting information received before attempting to interpret it. The primary form of overhead is in CPU utilization, but it is also necessary to transfer more information between the client and the server. For that reason, TLSv1 should generally be used only when it is necessary to ensure the privacy of the information that is being sent over the network.

How Does TLSv1 Work?

From a high level, TLSv1 works by encrypting information using data that is only available to the two machines having the encrypted conversation. The foundation of this set of information is the certificate. A certificate is a portion of binary data that can be used to establish proof of identity. There are two important parts of a certificate:

  • The public key

  • The private key

The public key is freely available and is used as the initial proof that the server is the system that the client believes it is. The private key is available only to the server and can be used to decrypt information that is encrypted using the server's public key.

Before information can be encrypted using TLSv1, a preliminary conversation must occur between the client and the server, known as the TLSv1 handshake, which is discussed in some detail later in this section. For now, this is what happens during the TLSv1 handshake:

  1. The client sends some information to the server, including the TLSv1 version number that the client wants to use and some randomly generated data.

  2. The server sends back some information that includes the TLSv1 version number the server will use, some randomly generated data, and the server's public key.

  3. If the client decides to trust the server's certificate as proof of identification, it generates a shared secret. This shared secret is encrypted using the server's public key and sent to the server.

  4. The server decrypts the data from the client using its private key to determine the shared secret.

  5. All communication between the client and the server beyond that point is encrypted with that shared secret.

There is actually more that occurs during this TLSv1 handshake, but the above description is a good starting point.

Types of TLSv1

Two-types of TLSv1 are commonly used:

  • Server authentication

  • Client authentication

Server authentication is the most common form and is the most basic level of authentication that can be performed using TLSv1, and was explained in a brief description in the previous section. Essentially , server authentication is used to obtain enough information to get the shared secret to encrypt the information. It is called server authentication because the process involves a mechanism whereby the server sends proof of its identity to the client and the client is then able to decide whether to trust that information and continue its conversation with the server. In server authentication, the server automatically trusts the client, or trusts the client through some mechanism built into the encapsulated protocol (for example, the password used in an LDAP bind request). No proof of the client's identity is required in the TLSv1 handshake.

Client authentication extends the process of server authentication in that the server requires proof of the client's identity in addition to having to prove its identity to the client. In this case, the TLSv1 handshake is extended to include the server requesting that proof of identity from the client.

In this scenario, the client must have its own certificate, and send the public key to the server so that the server can determine whether to trust the identity of the client. The client does not require a certificate. This is only used when there is client authentication. There is also an additional step involved in the generation of the shared secret when client authentication is used.

FIGURE 3-3 shows that the TLS protocol runs above TCP/IP and below high-level application protocols.

Figure 3-3. TLS Protocol in the Network Layer


TLS Protocol

The TLSv1 protocol is composed primarily of two subprotocols , which are:

  • TLSv1 Record Protocol

  • TLSv1 Handshake Protocol

The TLSv1 is the actual data transfer which is accomplished by the Record Protocol. This is achieved by breaking up the data stream to be transmitted into a series of fragments , with each fragment being independently protected and transmitted. Before any fragment can be transmitted, it must be protected against any potential attack. To provide the integrity protection, a message authentication code (MAC) is computed over the data, and is transmitted along with the fragment. This MAC is appended to the fragment and the concatenated data and MAC are encrypted to form the encrypted payload. A header is then attached to the payload. It is the concatenated header and encrypted payload that is referred as a record , which is then actually transmitted. FIGURE 3-4 shows the record protocol.

Figure 3-4. Composition of TLSv1 Record Protocol


The TLSv1 handshake protocol has various purposes, one of which includes the client and server negotiating on a set of algorithms which are used to protect the data. The client and server establish a set of cryptograhic keys which are used by these algorithms. The process works like this (also see FIGURE 3-5, and FIGURE 3-6 through FIGURE 3-10):

Figure 3-5. SSL Handshake Steps


Figure 3-6. Client Authentication


Figure 3-7. SSL Handshake Flow Chart (1 of 4)


Figure 3-8. SSL Handshake Flow Chart (2 of 4)


Figure 3-9. SSL Handshake Flow Chart (3 of 4)


Figure 3-10. SSL Handshake Flow Chart (4 of 4)


  1. Server and client exchange hello messages

    1. Establish protocol version

    2. Set session ID

    3. Agree to use one of the following cipher suites, choosing the strongest cipher suite that is common between client and server:

      - Key Exchange Algorithm (public-key: RSA, DH)

      - Encryption Cipher

      - MAC Algorithm

    4. Establish compression method

    5. Exchange random values

  2. Establish server authentication

    1. Client confirms server's identity

    2. Server sends certificate (necessary for KEA)

      The TLS protocol supports a variety of different cryptographic algorithms, or ciphers, for use in operations such as authenticating the server and client to each other, transmitting certificates, and establishing session keys. Clients and servers can support different cipher suites, or sets of ciphers, depending on factors such as the version of TLS they support, company policies regarding acceptable encryption strength, and government restrictions on export of TLSenabled software. The TLS handshake protocol determines how the server and client negotiate; which cipher suites they use, to authenticate each other, to transmit certificates, and to establish session keys. TABLE 3-3 describes the cipher suite algorithms.

      Table 3-3. Cipher Suite Algorithms


      Data Encryption Standard, an encryption algorithm used by the U.S. Government


      Digital Signature Algorithm, part of the digital authentication standard used by the U.S. Government


      Key Exchange Algorithm, an algorithm used for key exchange by the U.S. Government


      Message Digest algorithm developed by Rivest

      RC2 and RC4

      Rivest encryption ciphers developed for RSA Data Security


      A public-key algorithm for both encryption and authentication. Developed by Rivest, Shamir, and Adleman

      RSA key exchange

      A key-exchange algorithm for SSL based on the RSA algorithm


      Secure Hash Algorithm, a hash function used by the U.S. Government


      Salted Secure Hash Algorithm, a hash function used by the U.S. Government


      A classified symmetric-key algorithm implemented in Fortezza-compliant hardware used by the U.S. Government


      DES applied three times

      Key-exchange algorithms like KEA and RSA key exchange govern the way in which the server and client determine the symmetric keys they both use during a TLS session. The most commonly used TLS cipher suites use RSA key exchange.

    3. Check certificate DN versus server's DN (used to protect against man-inthemiddle attack).

    4. Premaster secret encrypted with server's public key (successful decryption by server provides additional authentication evidence)

    5. Optionally check the host name used to connect to the server against the value of the CN attribute in the server certificate's subject DN. This is an optional step, whereby the host names are compared to host names and not to the DNs.

  3. Perform key exchange:

    1. Generate Pre-master secret

    2. Client and server share pre-master secret

    3. Secret shared using KEA

    4. RSA KEA example:

      - Client creates pre-master secret

      - Encrypt pre-master secret with server's public key

      - Server decrypts pre-master secret with its own private key

  4. Perform client authentication (optional) For client authentication, it is up to the client whether it wishes to authenticate itself to the server. The client sends its certificate which contains the client's name (and possibly alternate names) and the client's public key and the CA which the server should trust.

    1. Server confirms client's identity

    2. Client sends certificate at server's request with the following:

      - Client's identity

      - Client's public key

    3. Client authenticates identity/public key binding. The ability to encrypt using the private key proves that the client is the owner of the certificate based on the assumption that only that user knows the private key.

    4. Digital signature: random data encrypted with client's private key to validate signature with client's public key

    5. Verify certificate within client's LDAP entry to allow certificate revocation. This is only done after the TLSv1 negotiation is complete, and then only if the client sends a SASL bind request using the EXTERNAL mechanism and the server is configured to verify the certificate presented by the client against the certificate stored in the user's entry. If this is not the case, then the client certificate is not verified against anything in the user's entry, nor is any attempt made to associate the client certificate with any user entry during the TLSv1 negotiation process.

  5. Generate master secret (client and server)

    This is generated during first connection, and shared between connections.

  6. Generate session keys (client and server, new for each connection)

  7. Exchange cipher spec messages and finished messages

    1. Change cipher spec and announce start of encrypted message exchange

    2. Finished messages already encrypted with session key

TLSv1/SSL in the Sun ONE Directory Server 5.2 Software

The Sun ONE Directory server has the ability to support the TLSv1/SSL protocol in multiple areas, and can be enabled in the following situations:

  • Both the administration server and DSML access are listening to HTTPS (HTTP over SSL). In this case HTTP over SSL refers to DSMLv2.

  • Replication over SSL

  • LDAP operations over SSL

  • Chaining over SSL

  • Console connected via SSL

The TLSv1/SSL Layer in the Sun ONE Directory Server 5.2 software is derived from the Network Security Services (NSS), and Netscape Portable Runtime (NSPR). NSS is a set of libraries designed to support cross-platform development of security-enabled server applications, and NSPR which provides low-level cross-platform support for operations such as threading and I/O. It is the Network Security Services that provides support for SSLv2, SSLv3, and TLSv1 and other security standards.

TABLE 3-4 lists the NSS and NSPR versions that are a component of the Sun ONE Directory Server 5.2 software and indicates where you can find more information.

Table 3-4. NSS and NSPR versions



Additional Information

Network Security Services (NSS)


Netscape Portable Runtime (NSPR)


FIGURE 3-11 shows a simplified view of the relationships between the NSS and NSPR shared libraries.

Figure 3-11. NSS/NSPR Architecture


The Network Security Services (NSS) has various security tools available, which may prove useful in the debugging and managing of your TLSv1/SSL implementation.

TLSv1/SSL Tools

Before we take a look at some of the TLSv1/SSL tools (TABLE 3-5), please be aware that these tools are not integrated into the Solaris 9 OE. You can get these tools from the Sun ONE Directory Server Resource Kit (SDRK) which is available from the Sun Download Center: sunone

Tools such as ssltap and many others can be obtained from:

This section describes some of the security certificate databases such as cert7.db, key3.db , and the secmod.db , which can list, generate, modify, or delete certificates within the cert7.db file and create or change the password, generate new public and private key pairs, display the contents of the key database, or delete key pairs within the key3.db file.

Security Databases

Public Key Cryptography Standard (PKCS) #11 specifies an API used to communicate with devices that hold cryptographic information and perform cryptographic operations. PKCS #11 supports a wide range of hardware and software devices intended for such purposes.

A PKCS #11 module (also referred to as a cryptographic module or cryptographic service provider) manages cryptographic services such as encryption and decryption through the PKCS #11 interface. PKCS #11 modules can be thought of as drivers for cryptographic devices that can be implemented in either hardware or software.

A PKCS #11 module always has one or more slots, which can be implemented as physical hardware slots in some form of a physical reader (for example, smart cards) or as conceptual slots in software. Each slot for a PKCS #11 module can contain a token, which is the hardware or software device that actually provides cryptographic services and optionally stores certificates and keys. The following is a brief explanation of the security databases:

  • cert7.db The database where the certificates (and therefore the public keys attached to them) are stored. Each certificate has a series of flags that account for the role that every certificate can take, as well as the uses for which that certificate is to be trusted. You can list, add, and modify the certificates within the database with certutil .

  • key3.db The database where the private keys associated to the public keys of the user certificates in cert7.db are kept. This file is protected by a password or pin.

  • secmod.db The file that keeps track of the available security modules. It lists each module with its slots and tokens, and specifies a default module. This is where an external module must be declared for the server to be able to detect it. By default, secmod.db manages two modules; the internal software module, and the built-in CA certificate module. modutil is the tool used to add, list, and modify modules to secmod.db .

Table 3-5. TLSv1/SSL Tools



certutil 2.0

Manages certificate and key databases ( cert7.db and key3.db ).

dbck 1.0

Analyzes and repairs certificate databases.

modutil 1.1

Manages the database of PKCS#11 modules ( secmod.db ). The PKCS#11 modules refer to hardware encryption tokens like SSL accelerator cards or secure key storage mechanisms. Adds modules and modifies the properties of existing modules (such as whether a module is the default provider of some crypto service).

pk12util 1.0

Imports and exports keys and certificates between the cert/key databases and files in PKCS#12 format.

ssltap 3.2

Performs proxy requests for an SSL server and for contents of the messages exchanged between the client and server. The ssltap tool does not decrypt data, but it shows things like the type of SSL message ( clientHello , serverHello , and so forth) and connection data (protocol version, cipher suite, and so forth). This tool is very useful for debugging.


The Sun Crypto Accelerator 1000 card is the only PKCS#11 module that is officially supported in the Sun ONE Directory Server 5.2 software.

TLSv1/SSL Configuration Overview

Before implementing the TLSv1/SSL functionality, you need to be aware of the attributes and attribute values that are or may be required by the Sun ONE Directory Server 5.2 software for the following attributes:

  • Certificate name

  • Supported cipher suites

  • Cryptographic token

  • Optionally, secure port number

When using the Sun ONE Directory Server software, you also need to be aware of the following configuration entries:

  • dn: cn=config

  • dn: cn=encryption, cn=config

In the cn=config entry, pay particular attention to the nsslapd-security and nsslapd-secureport attributes. The nsslapd-security attribute enables the use of the security features (TLSv1/SSL and attribute encryption) in the Sun ONE Directory Server 5.2 software. If you require secure connections, or the use of the attribute encryption feature, this attribute must be set to on . With the nsslapd-secureport , you must select the TCP/IP port number that will be used for TLSv1/SSL communications. The default TCP/IP port number is 636, and is only used if the server has been configured with a private key and a certificate; otherwise the server does not listen on this port.

In the cn=encryption, cn=config entry, there are a number of attributes and attribute values to deal with such as specifying the support for a particular SSL version. The nsSSL2 attribute supports SSLv2, while the nsSSL3 attribute supports SSLv3. Both of these attributes can be set to on or off .

The nsSSLSessionTimeout specifies the session lifetime in the session cache (in seconds). The Default is (zero), which results in the following:

  • SSLv2 =100 sec

  • SSLv3 =24 h

The nsSSLClientAuth attribute has the following values associated with a TLSv1/SSL connection:

  • Off no client authentication

  • Allowed request certificate, no error if no client certificate received

  • Required request certificate, error if no client certificate received

  • Default allowed

Next is the nsSSLServerAuth attribute, which stipulates the action that the TLSv1/SSL client should take on the server certificate sent by the TLSv1/SSL server in a TLSv1/SSL connection. The points of interest are:

  • Weak accept a server's certificate without checking the issuers CA

  • Cert accept server's certificate if the issuer CA is trusted

  • cncheck accept the server's certificate if:

    • The issuer CA is trusted

    • The certificate's cn matches the server's DNS host name

  • Default cert

The following is an example of the cn=encryption,cn=config entry.

 # Example of using ldapsearch to show the cn=encryption,cn=config # entry.  $./ldapsearch -h   directoryserver_hostname   -p   ldap_port   -b "cn=   encryption,cn=config" "(objectclass=*)"  # # Should return # cn=encryption,cn=config objectClass=top objectClass=nsEncryptionConfig cn=encryption nsSSLSessionTimeout=0 nsSSLClientAuth=allowed nsSSLServerAuth=cert nsSSL2=off nsSSL3=off 

The nsSSL3Ciphers is a multi-valued attribute that specifies a set of encryption ciphers that the Sun ONE Directory Server 5.2 software will use during TLSv1/SSL communications. The following values are to be noted as interest:

  • enable / disable to enable and disable cipher suites

  • +all enable all cipher suites but rsa_null_md5

  • -all disable all cipher suites

  • cipher_suite enable or disable a cipher suite. Use the following syntax:

  • Default all but rsa_null_md5 enabled

The nsKeyfile attribute provides the following:

  • Key database path relative to the SERVER_ROOT

  • Key database usually in the alias directory ( alias/slapdi- nstancename key3.db )

The nsCertfile attribute provides the following:

  • Certificate database path relative to the directory server installation directory ( /var/Sun/mps by default)

  • Certificate database usually in the alias directory ( alias/slapd- instancename cert7.db )

The nsSSLToken specifies where the certificate will be stored. In the vast majority of installations, this will be internal (software), which means that the certificate will be contained in the *cert7.db and *key3.db database files. However, it can be different if the certificate is stored elsewhere (it will be something like username@realm if you are using the Sun Crypto Accelerator 1000). The nsSSLToken attribute can have the following values:

  • Token for the cryptograhic operations: internal / external

  • Default: internal (software)

The nsSSLPersonalityssl attribute specifies the nickname of the certificate that is used as the TLSv1/SSL certificate for the directory server. It is generally something like server-cert . The nsSSLPersonalityssl attribute has the following values:

  • Certificate name

  • If external, token certname:tokenname - Even with external tokens, the format is still just the nickname of the certificate. This is true at least with the SCA 1000 card, which is the only external token supported in the 5.2 directory server. However, the nsSSLToken may be different for external tokens.

The nsSSLActivation attribute indicates whether the associated cipher family should be considered enabled for use. Given that there will generally only be a single cipher family (RSA), then it should be on if you want to use TLSv1/SSL in the directory server. Finally, the nsSSLActivation has the following values:

  • on (the default)

  • off

Now that we have covered the essential attributes and their values, we can now take a look at how we can now enable TLSv1/SSL in the Sun ONE Directory Server 5.2 software

Enabling TLSv1/SSL in the Sun ONE Directory Server 5.2 Software

This section describes the process of creating a certificate database, obtaining and installing a certificate for use with your Sun ONE Directory Server 5.2 software, and configuring the Sun ONE Directory Server 5.2 software to trust the certification authority's (CA) certificate. There are two methods you can use to perform these tasks . One method uses the Console, the other is through the command line. Both methods are covered in this chapter.

The following process is necessary before you can turn on TLSv1/SSL in the Sun ONE Directory Server software.

  1. Obtain and install a certificate for your directory server, and configure the directory server to trust the certification authority's certificate. See "Obtaining and Installing Server Certificates" on page 113.

  2. Turn on TLSv1/SSL in the Sun ONE Directory Server 5.2 software. See "Activating TLSv1/SSL in the Sun ONE Directory Server 5.2 Software" on page 126.

  3. (Optional) Ensure that each user of the directory server obtains and installs a personal certificate for all clients that will authenticate using TLSv1/SSL. This procedure is not covered in this book.


LDAPS implicitly requires you to have a secure port to listen to. With the Start TLS operation, this is no longer a requirement.

Obtaining and Installing Server Certificates

You must perform the following tasks to obtain and install server certificates.

  • "Task 1: Generate a Certificate Request (Console)" on page 113

  • "Task 2: Obtain the Certificate From a Certificate Authority (CA)" on page 118

  • "Task 3: Install the Certificate" on page 121

  • "Task 4: Trust the Certificate Authority" on page 123

  • "Task 5: Confirm That Your New Certificates Are Installed" on page 124

These tasks use wizards where possible. You can accomplish the same objectives on the command line by performing the following procedure:

  • "To Obtain and Install Server Certificates Using the Command-Line Interface" on page 124

For testing purposes, you can generate a self-signed certificate as described in:

  • "To Generate a Self-Signed Certificate Request" on page 125

Task 1: Generate a Certificate Request (Console)
  1. On the Sun ONE Directory Server Console, select the Tasks tab and click Manage Certificates .

    If this is the first time that you've opened this window, you are asked to assign a password to protect the key db as shown in FIGURE 3-12. This password is required to start the directory server when TLSv1/SSL is enabled.

    Figure 3-12. Console Security Device Password Window


    The Manage Certificates window is displayed (FIGURE 3-13).

    Figure 3-13. Manage Certificates Window


  2. Select the Server Certs tab, and click the Request button .

    The Certificate Request Wizard is displayed (FIGURE 3-14).

    Figure 3-14. Certificate Request Wizard Requestor Information Dialog Box


  3. Click Next .

  4. Enter the Requestor Information in the text fields ( FIGURE 3-14 ), then click Next .

    The following information is required:

    • Server Name Enter the fully qualified host name of the directory server as it is used in DNS lookups, for example, blueprints . .

    • Organization Enter your organization name.

    • Organizational Unit Enter your organizational unit information.

    • City/locality Enter your city name.

    • State/ province Enter the full name of your state or province (no abbreviations).

    • Country/region Select the two-character abbreviation for your country's name (ISO format). The country code for the United States is US, Great Britain is GB, Holland is NL, Singapore is SG, and so on.

  5. In the Token Password dialog box ( FIGURE 3-15 ), enter the password that will be used to protect the private key, and click Next .

    Figure 3-15. Certificate Request Wizard Token Password Dialog Box



    The Next button is greyed out until you supply a password. When you click Next, the Request Submission dialog box is displayed.

  6. In the Request Submission dialog box ( FIGURE 3-16 ), select Copy to Clipboard to copy the certificate request information that you will send to the Certificate Authority .

    Figure 3-16. Certificate Request Wizard Request Submission Dialog Box


    Example of the PKCS #10 Request:


    You use this generated request to request a certificate from a certificate authority (the next task).

Task 2: Obtain the Certificate From a Certificate Authority (CA)

In this task you have a couple of options:

  • Send the previously generated certificate request to a certificate authority in email, or

  • Go to a Certificate Authority web site and paste your request.

The outcome should be the same with either choice. That is, the CA will send you a certificate through e-mail. It is worth noting that the way to request a certificate from a CA varies depending on the CA.

The Sun ONE Certificate Manager software can be used to manage and sign digital certificates. This procedure uses the Sun ONE Certificate Manager as the CA. For small organizations, self-signed certificates are acceptable. However, for enterprise configurations, using an established CA is recommended.


Sun ONE Certificate Manager version 4.7 is used in this procedure.

  1. Using a browser, go to the Sun ONE Certificate Manager secure URL .

    This example uses

  2. Select SSL Application Server under the Enrollment tab .

  3. Copy the certificate request from the directory server, and paste it into the certificate manager system (in the TLSv1/SSL Server PKCS#10 request area, as shown in FIGURE 3-17 ):

    Figure 3-17. Sun ONE Certificate Manager Test Registration Authority



    It is advisable to have multiple Registration Authorities (RA) that you can select from, for example, BluePrints Inc. CA for production systems, and BluePrints Inc. TEST CA for development and test systems.


    Be sure to Include the "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" tags in the information pasted into the certificate install wizard.

  4. Fill out all the other information required by the Certificate Authority (CA) as described in TABLE 3-6.

    Table 3-6. Information Required by the CA


    Enter your name here


    Enter your email address.

    Additional Comments

    Enter your request details here. As an example, your request may be for enabling TLSv1/SSL on your own Enterprise Directory Service Infrastructure.

    Revocation Password

    Enter the database PIN for this system

    The revocation password is needed if a certificate holder wants the certificate revoked , but does not have access to the private key in order to sign the revocation request.

  5. Click Submit at the bottom of the page .

    The Certificate Request Result screen appears (FIGURE 3-18), confirming that the request has been submitted. Note the request ID provided in the response message in the example below (You can use it later to retrieve the certificate, once the certificate has been issued).

    Figure 3-18. Sun ONE Certificate Manager Test Registration Authority


Next, your request gets added to the agent queue of the Certificate Manager for approval by that Certificate Manager's agent. If you have permissions to access that Certificate Manager's Agent interface, you can issue the certificate. Otherwise, you should wait for the other agent to approve the request you submitted and issue the certificate.

The Sun ONE Certificate Manager administrator must approve the request by going to the services URL. Example:

Once you are in the Certificate Request Approval Page, you can perform the following to view that status of your request:

  1. On the Certificate Management Retrieval Services menu, click Check Request Status.

  2. Enter the request ID that was given to you when you submitted the initial request.

The following is an example of the information returned to you:

Request: 2114

Submitted on: 4/8/2003 12:38:59

Status: pending

Task 3: Install the Certificate

This task is dependent on receiving an email from your CA with instructions on how to pick up your certificate (usually the CA provides you with a URL).

  1. Using a browser, go to the URL that was provided by the CA .

  2. In the Sun ONE Directory Server Console, select the Tasks tab and click Manage Certificates .

    The Manage Certificates window is displayed.

  3. Select the Server Certs tab, and click Install .

    The Certificate Install Wizard is displayed.

  4. Select In the following encoded text block .

  5. Copy and Paste the base-64 formatted certificate .

    See FIGURE 3-19 for an example of entering the certificate into the Certificate Wizard.

    Figure 3-19. Certificate Install Wizard


  6. Check that the certificate information you have pasted is displayed correctly, and click Next .

    The new TLSv1/SSL server certificate appears in the list of Server Certs in the Certificate Manager Window (FIGURE 3-20).

    Figure 3-20. List of Server Certificates


Task 4: Trust the Certificate Authority

Configuring the Sun ONE Directory Server 5.2 software to trust the certificate authority consists of obtaining your CA's certificate and installing it into your server's certificate database. Once you have the CA certificate, you can use the Certificate Install Wizard to configure the Sun ONE Directory Server software to trust the Certificate Authority.

  1. On the Sun ONE Directory Server 5.2 Console, select the Tasks tab and click Manage Certificates .

    The Manage Certificates window is displayed.

  2. For each of the CA certs, go to the CA Certs tab, and click Install .

    The Certificate Install Wizard is displayed.

  3. Locate the CA certificate (or CA certificate chain in its base-64 encoded format), and select Retrieval and then Import CA Certificate Chain .

  4. Select Display Certificates in the CA Certificate Chain for Importing Individually into a Server and then click Submit .

  5. Copy the text of the base 64 cert .

    Copy the section between "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" and paste it into the window.


    Repeat this install for each of the Certificates (sections between "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----") present on the page.

  6. Check that the certificate information that is displayed is correct, and click Next .

  7. Select both of the following as the purpose of trusting this Certificate Authority:

    Accepting connections from clients (Client Authentication) . The server checks that the client's certificate has been issued by a trusted Certificate Authority.

    Accepting connections to other servers (Server Authentication) . The server checks that the directory to which it is making a connection (for example, for replication updates) has a certificate that has been issued by a trusted Certificate Authority.

  8. Click Done to dismiss the wizard .

    Once you have installed your certificate and trusted the CA's certificate, you are ready to activate TLSv1/SSL. However, before proceeding, you should first make sure that the certificates have been installed correctly.

Task 5: Confirm That Your New Certificates Are Installed
  1. On the Sun ONE Directory Server Console, select the Tasks tab and click Manage Certificates .

    The Manage Certificates window is displayed.

  2. Select the Server Certs tab .

    A list of all the installed certificates for the server are displayed.

  3. Scroll through the list. You should find the certificates that you have installed .

    The Sun ONE Directory Server software is now ready for TLSv1/SSL activation.

Using the Command Line to Obtain and Install Server Certificates

The following steps are performed on the command line instead of through a GUI. The five steps listed here have the same results as all the tasks that use the GUI.

To Obtain and Install Server Certificates Using the Command-Line Interface
  1. If you do not have certutil in you current PATH, you must either change directory to server-root /shared/bin or set the LD_LIBRARY_PATH shell variable to server-root /lib .

  2. Run the certutil command to generate a Certificate Signing Request (CSR) as shown:

    The certutil binary is located in server-root /shared/bin .

     $cd  server-root  /shared/bin $  ./certutil -R -s   subject   -a -d   cert-dir   -P "slapd-   instancename-   "  
  3. Take this output and provide it to a third-party CA to be signed (just like you would with the request generated through the Sun ONE Directory Server Console) .

  4. To install the certificate once it has been signed use the certutil command as shown:

     $cd  server-root  /shared/bin $  ./certutil -A -n server-cert -t Pu,Pu,Pu -a -i   certfile   -D   cert-dir   -P   "slapd-   instancename   -"  
  5. Import the CA certificate withe the certutil command:

     $cd  server-root  /shared/bin $  ./certutil -A -n ca-cert -t CT,CT,CT -a -i   ca_certfile   -D   cert-dir   -P   "slapd-   instancename   -"  
To Generate a Self-Signed Certificate Request

Use this procedure when you want to test TLSv1/SSL without using a real CA.

  1. If you do not have certutil in you current PATH, you must either change directory to server-root /shared/bin or set the LD_LIBRARY_PATH shell variable to server-root /lib .

  2. Issue the certutil command as shown:

     $cd  server-root  /shared/bin $  ./certutil -N -d <serveroot>/alias -P "slapd-example -"  

    Running the above command will request that a password is given to protect the key db.


    The password must be at least eight characters long, and must contain at least one non-alphabetic character.

    You are prompted for a password to protect the private key store, which you should provide, and then it will create a new certificate database in the server-root /alias directory.

  3. Issue the following command:

     $cd  server-root  /shared/bin $  ./certutil -S -n "server-cert" -s   subject   -t CTPu,CTPu,CTPu -x -v   12 -d <serveroot>/alias -P "slapd-example -" -5  

    The -t option specifies the trust attributes to modify in an existing certificate or to apply to a certificate when creating it or adding it to a database. In this example, we used CTPu , where C is the trusted CA to issue server certificates (SSL only), where T is the trusted CA to issue the client certificates to, where P is the trusted peer, and u is the certificate that can be used for authentication or signing. For more information on certutil , refer to:

  4. Respond as prompted.

    You are asked to randomly enter a text until the progress meter is full, then asked for the password for the private key store (the one you just used above). You receive a list of options for certificate extensions. Enter a 1 to indicate that it is an SSL server, followed by a 9 to indicate that there are no more extensions. Say y to indicate that it is a critical extension.

After completing the above successfully, you can use the certificate in this database for your directory server. It is self-signed, and nothing will trust it by default, so you must use that newly-created database as the trust store as well.

The following databases are also created:

  • slapd-example-cert7.db

  • slapd-example-key3.db

Activating TLSv1/SSL in the Sun ONE Directory Server 5.2 Software

Before you can activate TLSv1/SSL, you must create a certificate database, obtain and install a server certificate, and trust the CA's certificate as described in "Obtaining and Installing Server Certificates" on page 113.

Once those tasks are complete, you can then enable the TLSv1/SSL capabilities of the Sun ONE Directory Server software. This process is simple, but involves a few tasks. The first task is to configure the directory server to use TLSv1/SSL.

To Configure the Directory Server to Use TLSv1/SSL
  1. Select the Configuration tab from the Sun ONE Directory Server Console (FIGURE 3-21 ) .

    Figure 3-21. Encryption Tab in the Configuration Window in the Sun ONE Directory Console


  2. Select the Encryption tab from the right pane, and choose:

    • Security Device (token)

    • Certificate

  3. Choose Cipher family preferences by clicking the corresponding check box and clicking on the Settings button next to "Cipher:" .

    FIGURE 3-22 is an example of the Cipher Preferences for the Sun ONE Directory Server 5.2 software.

    Figure 3-22. Cipher Preference Panel


  4. Set the client authentication policy .

  5. Check Enable SSL for this server .

  6. Select the server certificate by name .

  7. (Optional) Choose to connect the Sun ONE Server Console to Directory Server over TLSv1/SSL .

    It is strongly recommended that you do not select Use SSL in Sun ONE Server Console while initially enabling SSL in the server. If you do this and there is a problem with the way that TLSv1/SSL has been configured, it will not be possible to administer the server through the console without manually editing information under o=NetscapeRoot . If you want to administer the directory server through the admin console using TLSv1/SSL, then you should enable that after you have confirmed that TLSv1/SSL has been properly configured.

  8. (Optional) Configure and set the Secure Port for the Sun ONE Directory Server software .

    1. Go to the Configuration graphics/rarr.gif Network Tab as shown in FIGURE 3-23.

      Figure 3-23. Network Tab in the Sun ONE Directory Console


    2. Specify in the bottom of this pane whether you wish to disable, allow, or require client authentication .

      In most cases, the default of Allow client authentication is acceptable.


      It is possible to require client authentication for TLSv1/SSL-based connections and still be able to use the admin console, as long as the admin console is not communicating with the directory server over TLSv1/SSL. Therefore, if you want to require client authentication, one possibility is to set nsslapd-listenhost to so that it only listens for non-secure connections on the loopback interface, and run the admin console from the directory server machine itself, connecting over LDAP rather than LDAPS.

  9. Click Save .

    After clicking Save, the Console shows a dialog box telling you changes do not take affect until the server is restarted. You must use the command line for this, because the command line provides a means of entering a password.

  10. Stop and restart the directory server .


     #  directoryserver_install_dir  /slapd-  instancename   /stop-slapd  #  directoryserver_install_dir  /slapd-  instancename   /start-slapd  Enter PIN for Internal (Software) Token: # 


    If you configure the directory server to verify the client certificate against a certificate stored in the user's entry, then you can use either a binary or an ASCII representation of the certificate to add the data to the user's entry. Usually it's easier to use the ASCII version because it is easier to include in an LDIF file.

Additional Information about TLSv1/SSL in the Sun ONE Directory Server Software

By default, the Sun ONE Directory Server software uses port 636 for encrypted communication because this is the standard LDAPS port. If this port is already in use, or if you would like to use a different port, you can also specify that in the administration server. Under the Configuration tab, click on the Settings tab in the right pane instead of the Encryption tab. The port to use for LDAPS communications is specified in the text field labeled Encrypted port in the Network Settings section. Enter the correct value, and click the Save button to update the configuration.

Alternatively, you can specify the port to use for TLSv1/SSL communication with the secure-port directive ( nsslapd-secureport ) in the dse.ldif configuration file.

Although you can use the nsslapd-listenhost parameter in the dse.ldif configuration file to specify the IP address on which the directory server will listen, this applies only to unencrypted LDAP traffic. If you wish to restrict LDAPS communication to a single IP address, you can do so with the nsslapd-securelistenhost directive.

When all of the TLSv1/SSL- related configuration of the Sun ONE Directory Server software is complete, you must restart the server in order for the changes to take effect and cause the directory server to actually listen for LDAPS requests. This introduces a problem, however, because the directory server must be able to access the private key on startup, but this is stored in the certificate database key store, which is password-protected. You will be prompted for this password when the directory server starts, either on the command line (on UNIX systems) or in a dialog box (on Windows NT). On UNIX systems, the fact that the password will be requested from the command line means that you will not be able to use the administration console to restart the directory server. It also means that the directory server will not automatically start when the machine boots on either UNIX or Windows NT systems. To remedy this, you can create a file that contains the password so that you will not be prompted for the password when the server is restarted. This file should be stored in the alias directory under the directory server install root and should be called slapd- instancename -pin.txt , where instancename is the name of the directory server instance for which you have installed the certificate. You will also see files named slapd- instancename -cert7.db and slapd- instancename -key3.db in that directory, which are the certificate trust and key stores, respectively. The text that should be placed in your file is Internal (Software) Token : password , where password is the password for the certificate key store (there should not be any spaces on either side of the colon ). Permissions on that file should be configured so that they are identical to the permissions of the certificate trust and key store, respectively.

At this point, you can restart the directory server and you should not be asked for a password. Use the command netstat -an to look at the network sockets that are in use on the machine. You should be able to see that the directory server is listening on both ports 389 and 636 (or whatever LDAP and LDAPS ports you have chosen ). If you do not, then there is likely a problem with the TLSv1/SSL configuration, and you should check the directory server's error log for more information.

Using TLSv1/SSL in the Sun ONE Server Console

The Sun ONE Administration Server Console is actually a web server that uses the HTTP protocol to communicate with the administration console and LDAP to communicate with the configuration directory with the use of CGI. However, it doesn't have to be that way. The administration server can use HTTPS to communicate with the administration console and LDAPS to communicate with the configuration directory. In order to do the former, it needs a server certificate, and the latter requires that the certificate used by the configuration directory is trusted by the administration server. This section describes how to do each of these.

The process of requesting and installing certificates in the administration server is almost exactly the same as requesting and installing certificates in the directory server. The only difference is that you do it in the administration server configuration of the Administration Server console instead of in one of the directory server instances. Upon opening the Sun ONE Server Console for the Administration Server, click on the Configuration tab and then the Encryption tab (FIGURE 3-24). You will see what is essentially the same interface as the Encryption tab in the directory server console.

Figure 3-24. Sun ONE Server Console



In the Sun ONE Server Console (5.2) there are now options to either Disable Client Authentication, or Require Client Authentication.

To request and install a server certificate, and to install CA certificates and trusted certificate chains, use the certificate setup wizard exactly as you would use it to perform those functions if the certificates were for the directory server.

Similarly, the process of enabling TLSv1/SSL in the Sun ONE Administration Server Console is virtually identical to enabling TLSv1/SSL in the Sun ONE Directory Server software. Simply check the Enable SSL for this Server checkbox. At that point, it is necessary to restart the administration server. This should be done on the command line in UNIX systems because you will be prompted for the key store password. You cannot use a PIN file to automate this process as you can with the directory server, however a simple workaround exists. Because the start-admin program is simply a shell script that sets up the appropriate environment to invoke the ns-httpd executable to start the administration server, and because the TLSv1/SSL password is read from STDIN, you can pipe the password to the process when it is started.

Enabling TLSv1/SSL in the Sun ONE Administration Server Console

Unlike the directory server, which has the ability to listen for both LDAP and LDAPS requests at the same time, the administration server can only listen for HTTP or HTTPS traffic, but not both. Therefore, once TLSv1/SSL is enabled in the administration server, the console must use TLSv1/SSL to communicate with it. The change required to do this is simple, but is often overlooked, and might be a source of confusion when you can no longer log in to the administration console once the administration server is using TLSv1/SSL.

The change that needs to be made is in the Administration URL, which is typically http:// servername :port . Once TLSv1/SSL is enabled for the administration server, the URL must change from http to https , as shown in FIGURE 3-25:

Figure 3-25. Using TLSv1/SSL in the Sun ONE Administration Server Console With an https URL


Understanding and Using TLSv1/SSL LDAP Client Architecture

This section describes the LDAP operations using both the ldapsearch and ldapmodify commands over TLSv1/SSL and the Secured LDAP Client implementation in the Solaris OE. Before processing, the following requirements must be meet. The following is only given as an outline with the details discussed later:

  • Certificate database:

    • Install the server cert's issuer CA cert trust for server authentication (trust flag: C )

  • If cert-based client authentication is required:

    • Key database

    • Request and install user certificate in cert db

    • Install user cert's issuer CA cert in server's cert db - trust for client authentication (trust flag: T )

Once a certificate has been installed in the directory server and TLSv1/SSL has been enabled, you should test this functionality to ensure that everything is working properly. The easiest and most convenient way to do this is by using the ldapsearch command-line utility. This utility is located in the shared/bin directory under the directory server root and has the ability to communicate with the directory server using TLSv1/SSL using either server or client authentication.


This is not the Solaris 9 OE integrated version of the ldapsearch command-line tool.

First, it is necessary to understand the syntax for the ldapsearch utility without TLSv1/SSL enabled. The basic syntax for the ldapsearch command is as follows :

 $  ./ldapsearch   options query attributes-to-return  

The options described in TABLE 3-7 are the most commonly used:.

Table 3-7. Common ldapsearch Options

Command-line Options



The DNS host name or IP address of the directory server. If this parameter is not specified, the default localhost ( ) is used.


The port on which the directory server is listening. If this parameter is not specified, the default 389 is used.


The DN to use to bind to the directory server. If this parameter is not specified, the search will be performed anonymously.


The password to use for the bind DN. If a bind DN is specified, the password is required.


The DN of the entry to use as the search base. This parameter is required.


The search scope. It must be one of the following:

  • base

  • one

  • onelevel

  • sub

  • subtree

If this parameter is not specified, then a default of subtree is used.

The easiest way to test connectivity to the directory server using ldapsearch is to retrieve the root DSE. This entry is available anonymously (so no bind credentials are required), and it is known to exist in the directory server no matter how the administrator has configured the server. The root DSE has a null DN, which you can specify in ldapsearch as "", and you must perform a base-level search to get any results. Assuming that the directory server is listening on , the correct syntax for the search is:

 $  ./ldapsearch -h -p 389 -b "" -s base "(objectclass=*)"  

You will see the root DSE in LDIF format returned. This is returned using the unencrypted LDAP protocol, but confirms that the directory server is up and responding properly.

Look at the ldapsearch operational arguments for the ldapsearch command over TLSv1/SSL as shown in TABLE 3-8.

Table 3-8. Common Command-line Options to ldapsearch with TLSv1/SSL

Command-line Options


Simple Authentication:



Secure port


TLSv1/SSL encrypted connection



Certificate-based client authentication:









cn check in server authentication


Earlier versions of the directory server did not require the -K argument to ldapsearch if you were only using TLSv1/SSL server authentication. However, starting with version 5.1, and still applicable to version 5.2, it is necessary to provide the path to the private-key store even if client authentication is not going to be used. This is because of a change in the underlying LDAP SDK for C used to build tools like ldapsearch and ldapmodify .

To test the TLSv1/SSL capabilities of the Sun ONE Directory Server software, you must add a couple more parameters to the search request. The -Z parameter, as mentioned above, indicates that you are using TLSv1/SSL to make an LDAPS connection, and the -P path-to-trust-db parameter specifies the location of the certificate trust database. The easiest certificate trust database to use is the directory server's own certificate database, which is the slapd- instancename -cert7.db file in the server-root /alias directory, because we know that the directory server's own certificate is included in that trust database and is trusted by default.

Additionally, you must change the port from the insecure LDAP port to the TLSv1/SSL-enabled LDAPS port of the directory server. With the above changes, the following command should be able to retrieve the root DSE of the directory server using LDAPS, (assuming that the directory is listening for LDAPS requests on and the instance name of the server is example ).

 $  ./ldapsearch -h -p 636 -b "" -s base -Z   -P ../../alias/slapd-example-cert7.db "(objectclass=*)"  


The above command should all be on one line.

In the above example, you can see exactly the same results as in the previous search, but the search is done using LDAPS instead of LDAP. If so, then the directory server is responding properly to TLSv1/SSL requests using server authentication.

The ldapsearch utility can also be configured to make LDAPS requests using client authentication. This process is significantly more complex than server authentication and carries a few additional requirements. Those requirements include:

  • The public and private keys of the client certificate must exist in the certificate database that is used.

  • The client certificate must exist in the directory server in the usercertificate;binary attribute of the entry with which you are binding. This is only true if the certmap.conf file has been configured to verify the certificate ( verifycert set to on ).

  • The certificate mapping mechanism must be used to uniquely map the certificate subject DN to an entry in the database. There are a number of ways of establishing this mapping if the DN of the user does not match the subject DN of the certificate (and it is not very common for a user certificate's subject DN to match the DN of the user's entry in the directory). But unless the subject of the client certificate exactly matches the DN of the directory entry containing the certificate, you must provide the -D parameter that contains the DN of the user entry as whom you wish to bind. The certmap.conf allows some flexibility here.

The mechanism for fulfilling these requirements is discussed in the next section of configuring an LDAP Client to use TLSv1/SSL. It must be noted, however, that if you want to use client authentication, it is recommended that you use a Netscape Communicator (any browser can be used that supports certificate and key databases) certificate database (this is shown in our example) rather than the directory server's certificate database. Once you have met those requirements, then you must specify the additional parameters, as shown in TABLE 3-8, for the ldapsearch command.

All of the examples in this section used the ldapsearch command-line utility to interact with the Sun ONE Directory Server software using LDAPS. The same functionality exists in the ldapmodify utility, which can be used to add, delete, or modify entries in the directory server. The use of the ldapmodify command is not discussed here, but all of theTLSv1/SSL related options are exactly the same for ldapmodify as for ldapsearch . Therefore, if you can use ldapsearch to search the directory using an TLSv1/SSL-encrypted connection, then you can use those same options with ldapmodify to modify the directory server data.

To Generate a TLSv1/SSL Client Certificate

In this procedure showing an example of using client authentication, all of the users on a client that wish to use TLSv1/SSL when connecting to a Sun ONE directory server using LDAP client applications, must generate a TLSv1/SSL client certificate. To create a certificate we need to follow these steps listed below:

  1. Request a signed certificate from the CA using the Netscape browser . This example in FIGURE 3-26 uses the Sun ONE Certificate Server URL to request a client certificate ( ):

    Figure 3-26. Sun ONE Certificate Manager


  2. Fill in all the necessary information .

  3. Select the Submit button at the bottom of the request page .

    The browser generates a keypair and sends the public part of this keypair to the Sun ONE Certificate Server in our example. The Sun ONE Certificate Server software then signs the key together with the additional information that you previously provided.

  4. Click OK ( FIGURE 3-27 ) .

    Figure 3-27. Key Generation Dialog Box


  5. Enter a password to protect your private key ( FIGURE 3-28 ) .

    Figure 3-28. Password Request Dialog Box


    After you enter your password, the private key is generated. If you are using Netscape Communicator or the Mozilla browser, you should see cert7.db, key3.db and secmod.db under your browser's directory (for example, the .netscape or .mozilla directories). The Netscape browser uses the security database files in the ~/.netscape directory. Therefore, it is already set up to query the Sun ONE directory server using TLSv1/SSL. The secmod.db is the file where Network Security Services (NSS) lists the different PCKS#11 modules available to you. Each module can have several slots, each slot being usually based on a token or security device.

    For instance, the NSS library delivers an internal module by default, which consists of a couple of slots (you can see this by using modutil on the secmod.db/secmodule.db ):

    • Slot NSS Internal Cryptographic Services -> Token "NSS Generic Crypto Services"

    • Slot NSS User Private Key and Certificate Services -> Token "NSS Certificate DB"

    This file is also where you plug in your external modules, such as accelerator cards.

    If you experience a message like the following:

     Please enter the password of pin for the Communicator Certificate DB 

    Then it assumes you have already provided a password the first time you accessed your browser's certificate/key databases. If you don't remember the password, there is nothing you can do, and you will have to generate a new cert/key database pair.

    The Sun ONE Certificate software presents a request ID to you. Before you can import the certificate, the Certificate Server Administrator must approve your request. You can receive the request notification by email or verbally.

    Example of a Certificate Request being sent by email:

     <html> <body> <h2>An automatically generated notification from <i>ca</i></h2> Your certificate request has been processed successfully. <p> SubjectDN= <b>,CN=Lucy Ruble,UID= lucyr,OU=Publishing,O=Example,C=US</b><br> IssuerDN= <b>CN=Certificate Manager,O=Example,Inc,C=us</b><br> notAfter= <b>09-Jan-04 9:28:59 PM</b><br> notBefore= <b>10-Jan-03 9:28:59 PM</b><br> Serial Number= <b>153</b><p> <p> To get your certificate, please follow this <A HREF=" displayBySerial&serialNumber=153">URL</A> Please contact your admin if there is any problem. </body> </html> 

    Example of a Request that has been successfully submitted is shown in FIGURE 3-29.

    Figure 3-29. Example of a Successfully Submitted Request


    The following examples show actual signed certificate components .

    This is the certificate section:

     # Example certificate Certificate 0x099  Certificate contents     Certificate:         Data:             Version:  v3             Serial Number: 0x99           Signature Algorithm: MD5withRSA - 1.2.840.113549.1.1.4             Issuer: CN=Certificate Manager,O=blueprints, C=us             Validity:                 Not Before: Thursday, April 10, 2003 9:28:59 PM                 Not After: Friday, April 9, 2004 9:28:59 PM                 Subject:,CN=Lucy Ruble,UID=     lucyr,OU=Publishing,O=Example, Inc,C=US                 Subject Public Key Info:                     Algorithm: RSA - 1.2.840.113549.1.1.1                     Public Key:                     30:81:89:02:81:81:00:AE:1D:D5:23:20:AC:F7:BD:B8:                     44:42:77:BE:23:AA:FD:32:46:41:CA:D1:F0:F2:24:94:                     43:71:ED:63:22:84:DB:EC:68:2B:FF:32:D1:FC:F6:B4:                     98:39:7C:B4:ED:B7:A7:12:89:EE:C2:DF:8D:71:D3:35:                     07:56:0E:33:F0:F5:A6:EE:6B:DD:43:92:FD:90:31:8B:                     0B:B9:DD:5A:8E:05:79:15:F4:21:87:FC:DC:81:73:49:                     03:32:78:D2:AA:13:0F:32:D5:E4:C1:88:92:B7:B3:B5:                     B6:CF:2B:AF:68:C8:A4:8C:D6:1B:02:74:81:45:93:D1:                         8F:E8:A5:C9:59:ED:85:02:03:01:00:01                 Extensions:                 Identifier: Certificate Type - 2.16.840.1.113730.1.1                        Critical: no                        Certificate Usage:                            SSL Client                            Secure Email                     Identifier: Key Type -                         Critical: yes                         Key Usage:                             Digital Signature                             Non Repudiation                             Key Encipherment                     Identifier: Authority Key Identifier -                         Critical: no                         Key Identifier:     DB:6B:27:D7:93:90:3B:68:BB:41:10:12:AB:36:D8:95:                         02:60:F0:6C                Signature:                    Algorithm: MD5withRSA - 1.2.840.113549.1.1.4                    Signature:                        94:5B:04:2D:0B:82:A6:FD:C9:C0:49:95:B1:C1:8D:09:                        67:7C:AA:E0:A1:ED:4D:CF:4A:2F:FF:66:87:B1:88:D0:                        FA:B0:AA:EB:68:15:7F:92:87:52:FD:7E:A1:2B:0C:AA:                        D6:FE:BE:05:B4:09:97:E9:6D:CC:27:7A:88:4D:87:09 

    The following is the certificate fingerprint section:

     # Example certificate fingerprint Certificate fingerprints     MD2: 4F:22:38:50:E2:C4:A4:09:95:06:E0:E4:A0:1F:9B:3F     MD5: 9E:8F:5F:ED:9F:FB:D2:14:2D:AF:74:E0:62:90:60:CE     SHA1: 2D:8E:33:90:19:CE:18:7E:B3:9B:5C:4D:DC:AE:B5:05:3A:FD:F8:87 

    These are the details on how to install the certificate:

     # Example of how to install the certificate The following format can be used to install this certificate into a Netscape server. -----BEGIN CERTIFICATE----- MIICVjCCAgCgAwIBAgICAJkwDQYJKoZIhvcNAQEEBQAwOTELMAkGA1UEBhMCdXMx DDAKBgNVBAoTA3N1bjEcMBoGA1UEAxMTQ2VydGlmaWNhdGUgTWFuYWdlcjAeFw0w MzA0MTAxNjU4NTlaFw0wNDA0MDkxNjU4NTlaMIGgMQswCQYDVQQGEwJVSzEeMBwG A1UEChMVU3VuIE1pY3Jvc3lzdGVtcywgSW5jMRgwFgYDVQQLEw9TdW4gRW5naW5l ZXJpbmcxFzAVBgoJkiaJk/IsZAEBEwdtaDEzNzQ5MRcwFQYDVQQDEw5NaWNoYWVs IEhhaW5lczElMCMGCSqGSIb3DQEJARYWbWljaGFlbC5oYWluZXNAc3VuLmNvbTCB nzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEArh3VIyCs9724REJ3viOq/TJGQcrR 8PIklENx7WMihNvsaCv/MtH89rSYOXy07benEonuwt+NcdM1B1YOM/D1pu5r3UOS /ZAxiwu53VqOBXkV9CGH/NyBc0kDMnjSqhMPMtXkwYiSt7O1ts8rr2jIpIzWGwJ0 gUWT0Y/opclZ7YUCAwEAAaNGMEQwEQYJYIZIAYb4QgEBBAQDAgWgMA4GA1UdDwEB /wQEAwIF4DAfBgNVHSMEGDAWgBTbayfXk5A7aLtBEBKrNtiVAmDwbDANBgkqhkiG 9w0BAQQFAANBAJRbBC0Lgqb9ycBJlbHBjQlnfKrgoe1Nz0ov/2aHsYjQ+rCq62gV f5KHUv1+oSsMqtb+vgW0CZfpbcwneohNhwk= -----END CERTIFICATE----- 
  6. Once you receive a signed certificate, import the signed certificate .

    With the signed certificate, it is now possible to import the signed client certificate. To perform this, scroll down to the end of the page, and look for:

     Importing this certificate 

    To import the certificate into your client, select the Import Your Certificate button.

  7. Enter the password for the Communicator Certificate Database ( FIGURE 3-30 ) .

    Figure 3-30. Password Dialog Box for the Communicator Certificate Database


    Once you have successfully typed in the correct password, you will have a new private key stored in ~/.netscape/key3.db , and a new certificate stored in ~/.netscape/cert7.db .

    You must make sure that the certificate of the CA that signed our TLSv1/SSL-client certificate is trusted.

  8. Verify and set up the appropriate trust relations .

    1. From the Netscape browsers menu select Communicator graphics/rarr.gif Tools graphics/rarr.gif Security Info .

    2. Under the Certificates, select Your certificate .

      You should see the certificate you just imported from the Certificate Server.

    3. Select the certificate and click the Verify button .

      The browser shows you a dialog box (FIGURE 3-31) showing that the certificate is not trusted.

      Figure 3-31. Netscape Verify a Certificate Dialog Box Showing Failed Verification


    4. Go to the Security Info window, select Signers in the navigation frame and select the certificate signer from the list in the right frame .

      This changes the certificate so that it is trusted.

      The CA that signed the certificate must have the appropriate trust relations. To accomplish this task from the Netscape Browser.

    5. Click the Edit button .

      The Edit Certification Authority dialog box appears (FIGURE 3-32).

      Figure 3-32. Edit a Certification Authority Dialog Box


    6. Modify the trust relation by checking each Accept option ( FIGURE 3-32 ) .

    7. Verify the client certificate again, as you did previously .

      The browser shows that the certificate is now trusted (FIGURE 3-33).

      Figure 3-33. Verify a Certificate Dialog Box


Initializing the Secured LDAP Client

When you initially created your client certificate, you chose to use the manual option from the certificate management system (CMS). Remember, however, that by selecting this option, you end up having your client certificate in your browser's certificate/key database pair, so these are the databases that you have to use with the Secured LDAP client application.

To use the TLSv1/SSL security databases ( cert7.db and key3.db ), these databases must be placed in the directory defined by the clients certificatePath attribute. This is required because the Secured LDAP Client library ( ) uses the ldapssl_client_init API from libldap to initialize itself to connect to a secure LDAP server over TLsv1/SSL. This call requires the path to the database containing certificates and the database must be a cert7.db certificate database.

You can use the NS_LDAP_HOST_CERTPATH parameter in the Secured LDAP Client profile to specify the path. If you don't, the path by default is the /var/ldap directory. So copy the database files and give read access as shown in the following example:

 #  /usr/bin/cp /.netscape/cert7.db /var/ldap  #  /usr/bin/cp /.netscape/key3.db /var/ldap  #  /usr/bin/chmod 400 /var/ldap/cert7.db /var/ldap/key3.db  


The Netscape browser uses the security database files in the ~/.netscape directory. Therefore, it is already set up to query the Sun ONE Directory Server software using TLSv1/SSL.

The Solaris OE version of the libldap library and TLSv1/SSL require mutual authentication. Therefore, the servers IP address that the client uses must resolve to the same name that is contained in the servers certificate. Because the servers certificate uses its fully qualified domain name, for example, if you are using the Secured LDAP client, the address must resolve to the name in the certificate.


The LDAP name service cannot be used to resolve the address to the LDAP server. DNS can be used for host resolution. If you add the host to the /etc/hosts file, be sure to add it so that the host name resolves to the same name that is in the certificate.

First add the full host name and address of the server to the /etc/hosts file. Edit the /etc/nsswitch.ldap file to use files and then LDAP for hosts resolution. The modified nsswitch.ldap file should have an entry as follows:

 hosts: files ldap 

You must modify the /etc/nsswitch.ldap file because when you run the ldapclient init command, it is copied to the /etc/nsswitch.conf file.

The TLSv1/SSL support in the Secured LDAP Client is implemented as a library, and it is that actually implements the client side of it. This works in the following way.

In the Secured LDAP client profile, the authenticationMethods that you can specify are:

  • NONE








Those that start with TLS: indicate that a TLSv1/SSL session is required. When the libsldap library sets up the connection to the Sun ONE Directory (LDAP) Server (or any directory server for that matter), it first calls a private interface in to initialize the client application for TLSv1/SSL ( open the certificate database), then calls the private interface again to initialize an LDAP session with the secure directory server. After this, everything is performed in the same way as a non-TLS session.

In the Secured LDAP Client, there is a list of encryption types with encryption strengths of TLSv1/SSl certificates that can be used by the Solaris OE Secured LDAP Client.

The Secured LDAP client informs the directory server which cipher suites it supports (in preferential order see below). The directory server replies with the subset of mechanisms it supports (in preferential order). The policy is to allow all of these cipher suites, except those that are not enabled. The following cipher suites are present by default:

  • SSL 3.0:


  • SSL_RSA_WITH_RC4_128_MD5








These may work (see Note):





The three Fortezza cases listed above require other things installed, such as cards, boards , and tokens. Sun does not currently support them at this time.

For SSL2:

  • SSL_CK_RC4_128_WITH_MD5







To Verify That TLSv1/SSL Is Working

This procedure verifies that TLSv1/SSL is working on the directory server and that the client profile is set up.

  1. Use the ldapsearch command as shown in the following examples .

     $  ./ldapsearch -h   directoryserver_hostname   -p   ldap_port   -D "cn=Directory Manager" -w   password   -b "cn=encryption,cn=config" cn=*  objectClass=top objectClass=nsEncryptionConfig cn=encryption nsSSLSessionTimeout=0 nsSSLClientAuth=allowed nsSSLServerAuth=cert nsSSL2=off nsSSL3=on 
     $  ./ldapsearch -h   directoryserver_hostname   -p   ldap_port   -b "ou=profile,dc=example,dc=com" "cn=default"  cn=default,ou=profile,dc=example,dc=com objectClass=top objectClass=DUAConfigProfile defaultSearchBase=dc=example,dc=com authenticationMethod=tls:simple followReferrals=FALSE defaultSearchScope=one searchTimeLimit=30 profileTTL=43200 cn=default credentialLevel=proxy bindTimeLimit=10 
  2. Initialize the Secured LDAP client with the ldapclient init command using the name of the server instead of the address .


     $  ./ldapclient init -a proxydn=cn=proxyagent, ou=profile,dc=   example,dc=com -a proxypassword=proxy -a  # $  ldapclient list  NS_LDAP_FILE_VERSION= 2.0 NS_LDAP_BINDDN= cn=proxyagent,ou=profile,dc=example,dc=com NS_LDAP_BINDPASSWD= {NS1}ecc423aad0 NS_LDAP_SERVERS= NS_LDAP_SEARCH_BASEDN= dc=example,dc=com NS_LDAP_AUTH= tls:simple NS_LDAP_SEARCH_REF= FALSE NS_LDAP_SEARCH_SCOPE= one NS_LDAP_SEARCH_TIME= 30 NS_LDAP_PROFILE= default NS_LDAP_CREDENTIAL_LEVEL= proxy NS_LDAP_BIND_TIME= 10 
  3. (Optional) Verify the encrypted traffic .

    It is good practice to verify the encrypted traffic. Out of the standard Solaris OE command-line tools, only the ldaplist and ldapaddent commands access the Sun ONE Directory (LDAP) server using TLSv1/SSL. The command-line tools ( ldapsearch , ldapmodify and ldapdelete ) that are provided with the Sun ONE Directory software distribution are enhanced to use TLSv1/SSL. These are located in the path / directory-server-instance /shared/bin directory.

    Here is an example of verifying the encrypted traffic with TLSv1/ SSL using the ldapsearch command:

     $  ./ldapsearch -h   directoryserver_hostname   -p   ldap_port   636 -Z   -P /var/ldap/cert7.db -b "dc=example,dc=com" "cn=*"  

    To actually verify that the traffic is encrypted, use something like the Solaris 9 OE /usr/sbin/snoop command (see Appendix C, "Using snoop with LDAP). The more advanced protocol analyzers like Ethereal (available for free for a number of platforms, and as source code from can even interpret the information that is captured so that it can be more easily understood. This is helpful with text-based protocols like HTTP because it provides formatting for the request. It is invaluable for binary protocols like LDAP because the task of decoding the information and figuring out exactly what is going on between the client and the server is much more difficult.


    Ethereal is available on the Solaris 8 and 9 OE Companion Software CDs. However, support for this utility is not provided by Sun.

Start TLS Overview

The TLS Protocol Version 1.0 is defined in RFC 2246. Before deciding to use the Start TLS functionality, it is worth taking the time to understand what TLS actually offers. The primary use of the TLS protocol with LDAP is to ensure connection confidentiality and integrity, and to optionally provide for authentication. Be aware that using the Start TLS operation on its own does not provide any additional security because the security element is accomplished through the use of TLS itself.

The level of security provided though the use of TLS is dependent directly on both the quality of the TLS implementation used and the style of usage of that implementation.


The Start TLS extended operation in the Sun ONE Directory Server 5.2 software is available on all platforms. This was not the case with version 5.1, where NT is not supported.

The Start TLS operation is an extended operation defined by the LDAPv3 protocol that is initiated by a client starting the TLS protocol over an already established LDAP connection. What actually happens is that the client transmits an LDAP PDU (protocol data unit) containing the LDAPv3 ExtendedRequest , and specifying the OID for the Start TLS operation. The OID is: 

This extended operation enables the ability of securing a connection that was not secure, based on a client's demand.

This extended operation is forwarded to the directory server in terms of an LDAP extended request that contains a specific OID as referenced above, identifying the Start TLS operation. It is up to the directory server to decide whether or not the request should be accepted or rejected. The server sends an extended LDAP PDU containing a Start TLS extended response back to the client with either a successful or a non-successful answer as to whether the directory server is willing and able to negotiate TLS. If the ExtendedResponse contains a result code indicating success, then the directory server is willing and able to negotiate TLS. If, on the other hand, the ExtendedResponse contains a result code other than success, this indicates that the directory server is unwilling or unable to negotiate TLS. If the Start TLS extended request is not successful, the result code will be one of:

  • operationsError TLS already established.

  • protocolError TLS is not supported or incorrect PDU structure.

  • referral The directory server does not support TLS.

  • unavailable There is a serious problem with TLS, or the directory server is down.

In the case that a successful response is returned, the directory server initializes TLSv1/SSL (initializes both the certificate and key databases, and sets the cipher policy), imports the current socket into a TLSv1/SSL-socket, and configures it in order to behave as a TLSv1/SSL server.

In the Sun ONE Directory Server 5.2 software, the Start TLS extended operation is implemented as an internal extended operation plug-in. The implementation itself is based on the IETF RFC 2830 "Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security" (

When the Sun ONE directory server receives a Start TLS extended operation request, it performs a series of checks as specified in the above document (such as checking whether there are other operations still pending on the connection, whether security is enabled on the directory server, and so on). If successful, it performs the TLSv1/SSL handshake and uses a secure connection.

As to the configuration of the Sun ONE directory server, no specific configuration has to be taken into account except for the Windows platforms, where you must add the ds-start- tls-enabled : on attribute to the cn=config entry. This is necessary because on Windows, the server handles connections differently depending on whether they are secured or non-secured; secured connections need to be handled using NSPR (as NSS is built upon NSPR), whereas non-secured ones benefit from the Windows I/O completion ports architecture, which turns out to be more efficient. So, if you want to convert a non-secured connection into a secured one (perform Start TLS operation), you must know beforehand so that the server can also handle non-secured connections using NSPR right from the start-up.

For Start TLS to work, the security must be enabled in the server, with all the necessary configuration (certificate and key databases, server certificate available, cipher preferences set, client authentication policy specified, and so forth).


You don't need to have a dedicated secure port open. That is, in fact, one of the strong points of Start TLSit allows you to have secure connections on the non-secure LDAP port.

In summary, the complexity of setting up TLSv1/ SSL is mainly on the Sun ONE directory server-side, and is categorized in the following main points:

  1. Find a CA. You can use an existing one, or you will have to set up something like the Sun ONE/iPlanet Certificate Server.

  2. The Sun ONE Directory (LDAP) server has to get a server certificate from the CA, and has to activate TLSv1/SSL afterwards.

  3. The Secured LDAP Client has to get a CA certificate from the same CA.

  4. You must copy $HOME/cert7.db and $HOME/key3.db to /var/ldap . The path /var/ldap can be overwritten by setting up certificatepath with ldapclient -a certificatepath path


    Currently the Secured LDAP does not use Start TLS.

  5. If you want to test an LDAP client authentication, the server has to get a CA certificate and the client has to get a client certificate from the same CA. But it's not required by the Secured LDAP Client.

LDAP in the Solaris Operating Environment[c] Deploying Secure Directory Services
LDAP in the Solaris Operating Environment[c] Deploying Secure Directory Services
ISBN: 131456938
Year: 2005
Pages: 87 © 2008-2017.
If you may any questions please contact us: