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:
To dispel any misunderstandings you might have, this section explains the differences between TLS and SSL.
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
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.
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:
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:
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 http://www.ethereal.com) 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 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:
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 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
The TLSv1 protocol is composed primarily of two subprotocols , which are:
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)
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:
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
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.
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:
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.
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:
Table 3-5. TLSv1/SSL Tools
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:
When using the Sun ONE Directory Server software, you also need to be aware of the following configuration entries:
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:
The nsSSLClientAuth attribute has the following values associated with a TLSv1/SSL connection:
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:
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:
The nsKeyfile attribute provides the following:
The nsCertfile attribute provides the following:
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:
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:
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:
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.
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.
These tasks use wizards where possible. You can accomplish the same objectives on the command line by performing the following procedure:
For testing purposes, you can generate a self-signed certificate as described in:
Task 1: Generate a Certificate Request (Console)
Task 2: Obtain the Certificate From a Certificate Authority (CA)
In this task you have a couple of options:
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.
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: http://example.blueprints.com:8100
Once you are in the Certificate Request Approval Page, you can perform the following to view that status of your request:
The following is an example of the information returned to you:
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).
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.
Task 5: Confirm That Your New Certificates Are Installed
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
To Generate a Self-Signed Certificate Request
Use this procedure when you want to test TLSv1/SSL without using a real CA.
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:
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
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:
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
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 127.0.0.1:389 , the correct syntax for the search is:
$ ./ldapsearch -h 127.0.0.1 -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
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 127.0.0.1:636 and the instance name of the server is example ).
$ ./ldapsearch -h 127.0.0.1 -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 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:
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 ( libsldap.so.1 ) 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, example.com 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 libldap.so.5 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:
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 libldap.so.5 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:
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.
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.
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:
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" (ftp://ftp.rfc-editor.org/innotes/rfc2830.txt).
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: