Attachment 306859 Details for Bug 441889 – 7.1 SSL chapter

7.1 SSL chapter

ssl.htm (text/html), 92.82 KB, created by Deon Ballard on 2008-05-28 00:14:43 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Deon Ballard

Created: 2008-05-28 00:14:43 UTC

Size: 92.82 KB

patch

obsolete

><html>
>
>
><head>
><meta name="keywords" content="e-commerce, ecommerce, Red Hat, directory server, Directory Server, directory service, enterprise software, database, software, directory, Linux, Fedora, Red Hat software, linux, LDAP, open source" />
><meta name="description" content="Red Hat, Inc., produces the world renowned Directory Server, as well as cutting-edge open source software." />
><meta http-equiv="content-type" content="text/html; charset=ISO-8859-1" />
><meta name="templatebase" content="Authored in FrameMaker. Converted to HTML in WebWorks Publisher. manual wdt 1.6" />
><meta name="LASTUPDATED" content="05/27/08 19:01:12" />
><title>Red Hat Directory Server Administrator's Guide: Chapter&#32;11 Managing SSL and SASL</title>
>
>
><script type="text/JavaScript" src="sniffer.js">
>
>
>
></script>
>
>
>
></head>
>
>
>
>
><body text="#000000" link="#990000" vlink="#990000" alink="#333366" bgcolor="#FFFFFF">
>
>
>
>
>
>
>
><table border="0" cellspacing="0" cellpadding="0" width="100%">
><tr>
><td><table border="0" cellspacing="0" cellpadding="0">
><tr>
><td valign="bottom" width="67">
><img src="logo64.png" height="64" width="64" border="0" alt="shadow man" />
></td>
><td valign="middle">
>Administrator's Guide 
>Red Hat Directory Server 
></td>
></tr>
></table>
></td>
></tr>
>
><tr>
><td>
><hr size="1" noshade="noshade" />
>
><a style="text-decoration: none; color:#990000" href="index1.htm">
>Previous
></a>
>
>
>&nbsp;&nbsp;&nbsp;&nbsp;
>
>
>
><a style="text-decoration: none; color:#990000" href="contents.htm">
>Contents
></a>
>
>&nbsp;&nbsp;&nbsp;&nbsp;
>
>
>
><a style="text-decoration: none; color:#990000" href="ix.htm">
>Index
></a>
>
>&nbsp;&nbsp;&nbsp;&nbsp;
>
>
>
><a style="text-decoration: none; color:#990000" href="../index.htm">
>DocHome
></a>
>
>&nbsp;&nbsp;&nbsp;&nbsp;
>
>
>
><a style="text-decoration: none; color:#990000" href="dsstats.htm">
>Next
></a>
>
>&nbsp;&nbsp;&nbsp;&nbsp;
>
>
></td>
></tr>
></table>
>
>
>
>
>
>
><blockquote>
> 
>
><a name="1085020"> </a>
><a name=""> </a>
>
>Chapter&#32;11 
>&nbsp;
>
>
><a name="996824"> </a>
><a name="Managing SSL and SASL"> </a>
>Managing SSL and SASL
>
> 
><a name="1038480"> </a>
>To provide secure communications over the network, Red Hat Directory Server (Directory Server) includes the LDAPS communications protocol. LDAPS is the standard LDAP protocol, but it runs on top of Secure Sockets Layer (<a href="glossary.htm#1044686" >SSL</a>). Directory Server also allows "spontaneous" secure connections over otherwise-insecure LDAP ports, using Start TLS (Transport Layer Security).
>
>
><a name="1083212"> </a>
>Additionally, Directory Server supports SASL authentication using the GSS-API mechanism, allowing Kerberos, rather than certificates, to authenticate sessions and encrypt data.
>
>
><a name="1079245"> </a>
>This chapter describes how to use SSL and SASL with your Directory Server in the following sections:
>
><ul>
>
><li>
><a href="ssl.htm#1041472" >Introduction to SSL in the Directory Server</a> (<a href="ssl.htm#1041472" >page 418</a>)
><a name="1038882"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
><a href="ssl.htm#1085091" >Obtaining and Installing Server Certificates</a> (<a href="ssl.htm#1085091" >page 420</a>)
><a name="1079229"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
><a href="ssl.htm#1089131" >Command-Line Functions for Start TLS</a> (<a href="ssl.htm#1089131" >page 419</a>)
><a name="1089118"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
><a href="ssl.htm#1089063" >Using certutil</a> (<a href="ssl.htm#1089063" >page 425</a>)
><a name="1087249"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
><a href="ssl.htm#1087250" >Starting the Server with SSL Enabled</a> (<a href="ssl.htm#1087250" >page 428</a>)
><a name="1038937"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
><a href="ssl.htm#1038525" >Setting Security Preferences</a> (<a href="ssl.htm#1038525" >page 433</a>)
><a name="1038886"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
><a href="ssl.htm#1053102" >Using Certificate-Based Authentication</a> (<a href="ssl.htm#1053102" >page 435</a>)
><a name="1038894"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
><a href="ssl.htm#1048777" >Configuring LDAP Clients to Use SSL</a> (<a href="ssl.htm#1048777" >page 437</a>)
><a name="1053589"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
><a href="ssl.htm#1083165" >Introduction to SASL</a> (<a href="ssl.htm#1083165" >page 439</a>)
><a name="1083158"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
></ul>
>
><a name="1041472"> </a>
><a name="Introduction to SSL in the Directory Server"> </a>
>Introduction to SSL in the Directory Server
><hr size="1" noshade="noshade" />
>
>
>
><a name="1079183"> </a>
>The Directory Server supports SSL/TLS to secure communications between LDAP clients and the Directory Server, between Directory Servers that are bound by a replication agreement, or between a database link and a remote database. You can use SSL/TLS with simple authentication (bind DN and password) or with certificate-based authentication. 
>
>
><a name="1079645"> </a>
>Using SSL with simple authentication ensures confidentiality and data integrity. The benefits of using a certificate to authenticate to the Directory Server instead of a bind DN and password include:
>
><ul>
>
><li>
>Improved efficiency &#151; When you are using applications that prompt you once for your certificate database password and then use that certificate for all subsequent bind or authentication operations, it is more efficient than continuously providing a bind DN and password.
><a name="1079679"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
>Improved security &#151; The use of certificate-based authentication is more secure than non-certificate bind operations. This is because certificate-based authentication uses public-key cryptography. As a result, bind credentials cannot be intercepted across the network.
><a name="1079681"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
></ul>
>
><a name="1080430"> </a>
>The Directory Server is capable of simultaneous SSL and non-SSL communications. This means that you do not have to choose between SSL or non-SSL communications for your Directory Server; you can use both at the same time. You can also utilize the Start TLS extended operation to allow SSL/TLS secure communication over a regular (insecure) LDAP port.
>
>
><a name="1087172"> </a>
>Directory Server also supports SASL client authentication; see <a href="ssl.htm#1083165" >"Introduction to SASL"</a>, for more information.
>
>
><a name="1082682"> </a>
><a name="Enabling SSL: Summary of Steps"> </a>
>Enabling SSL: Summary of Steps
>
>
>
>
><a name="1079643"> </a>
>To configure your Directory Server to use LDAPS, follow these steps:
>
><ol type="1">
>
><li value="1">
>Obtain and install a certificate for your Directory Server, and configure the Directory Server to trust the certification authority's (CA's) certificate.
><a name="1079187"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1079234"> </a>
>For information, see <a href="ssl.htm#1085091" >"Obtaining and Installing Server Certificates"</a>.
> &nbsp;</dt> </dl>
>
><li value="2">
>Turn on SSL in your directory.
><a name="1079196"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1079235"> </a>
>For information, see <a href="ssl.htm#1087250" >"Starting the Server with SSL Enabled"</a>.
> &nbsp;</dt> </dl>
>
><li value="3">
>Configure the Administration Server to connect to an SSL-enabled Directory Server.
><a name="1079200"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1079236"> </a>
>For information, see <a href="../pdf/console60.pdf">Managing Servers with Red Hat Console</a>.
> &nbsp;</dt> </dl>
>
><li value="4">
>Optionally, ensure that each user of the Directory Server obtains and installs a personal certificate for all clients that will authenticate with SSL.
><a name="1079706"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1079707"> </a>
>For information, see <a href="ssl.htm#1048777" >"Configuring LDAP Clients to Use SSL"</a>.
> &nbsp;</dt> </dl>
></ol>
>
><a name="1079208"> </a>
>For a complete description of SSL, Internet security, and certificates, check the appendixes included in <a href="../pdf/console60.pdf">Managing Servers with Red Hat Console</a>.
>
>
><a name="1089131"> </a>
><a name="Command-Line Functions for Start TLS"> </a>
>Command-Line Functions for Start TLS
><hr size="1" noshade="noshade" />
>
>
>
><a name="1089132"> </a>
>You can specify that LDAP operations such as <code>ldapmodify</code>, <code>ldapsearch</code>, and <code>ldapdelete</code> use SSL/TLS when communicating with an SSL-enabled server or to use certificate authentication. Using the command-line options, you can also specify or enforce Start TLS, which which allows a secure connection to be enabled on a cleartext port after a session has been initiated.
>
>
><a name="1089134"> </a>
>In the following example, a network administrator enforces Start TLS for a search for Mike Connor's identification number:
>
>
><a name="1089135"> </a>
><code>ldapsearch -p 389 -ZZZ -P </code>certificateDB&nbsp;<code> -N </code>certificate_name&nbsp;<code> -s base -b "uid=mconnors" "(attribute=govIdNumber)"</code>
>
>
><a name="1089136"> </a>
>where <code>-ZZZ</code> enforces Start TLS, certificateDB gives the filename and path to the certificate database, and certificate_name is the certificate.
>
><table border="0" cellpadding="0" width="90%">
><tr><td colspan="2">
><hr size="1" />
></td></tr>
><tr>
><td valign="top">
><a name="1089139"> </a>
>Note&nbsp;&nbsp;
>
>
></td>
><td valign="top">
><a name="1089141"> </a>
>The <code>-ZZZ</code> command enforces the use of Start TLS, and the server must respond that a Start TLS command was successful. If you use the <code>-ZZZ</code> command and the server does not support Start TLS, the operation is aborted immediately.
>
></td>
> </tr>
>
><tr><td colspan="2">
><hr size="1" />
></td></tr>
></table>
>
> 
> 
>
>
><a name="1089146"> </a>
>For information on the command-line options available, see the <a href="../cli/utilities.htm">Red Hat Directory Server Configuration, Command, and File Reference</a>.
>
>
><a name="1089149"> </a>
><a name="Troubleshooting Start TLS"> </a>
>Troubleshooting Start TLS
>
>
>
>
><a name="1089150"> </a>
>With the <code>-ZZ</code> option, the following errors could occur:
>
><ul>
>
><li>
>If there is no certificate database, the operation fails. See <a href="ssl.htm#1085091" >"Obtaining and Installing Server Certificates"</a>, for information on using certificates.
><a name="1089154"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
>If the server does not support Start TLS, the connection proceeds in cleartext. To enforce the use of Start TLS, use the <code>-ZZZ</code> command option.
><a name="1089161"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
>If the certificate database does not have the Certifying Authority (CA) certificate, the connection proceeds in cleartext. See <a href="ssl.htm#1085091" >"Obtaining and Installing Server Certificates"</a>, for information on using certificates.
><a name="1089162"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
></ul>
>
><a name="1089166"> </a>
>With the <code>-ZZZ</code> option, the following errors could occur, causing the Start TLS operation to fail:
>
><ul>
>
><li>
>If there is no certificate database. See <a href="ssl.htm#1085091" >"Obtaining and Installing Server Certificates"</a>, for information on using certificates.
><a name="1089169"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
>If the certificate database does not have the Certifying Authority (CA) certificate. See <a href="ssl.htm#1085091" >"Obtaining and Installing Server Certificates"</a>, for information on using certificates.
><a name="1089171"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
>The server does not support Start TLS as an extended operation.
><a name="1089175"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
></ul>
>
><a name="1089176"> </a>
>For SDK libraries used in client programs, if a session is already in TLS mode and Start TLS is requested, then the connection continues to be in secure mode but prints the error <code>"DSA is unwilling to perform"</code>.
>
>
><a name="1085091"> </a>
><a name="Obtaining and Installing Server Certificates"> </a>
>Obtaining and Installing Server Certificates
><hr size="1" noshade="noshade" />
>
>
>
><a name="1042334"> </a>
>This section describes the process of creating a certificate database, obtaining and installing a certificate for use with your Directory Server, and configuring Directory Server to trust the certification authority's (CA) certificate.
>
>
><a name="1079253"> </a>
>This process is a necessary first step before you can turn on SSL in your directory. If you have already completed these tasks, see <a href="ssl.htm#1087250" >"Starting the Server with SSL Enabled"</a>. 
>
>
><a name="1079254"> </a>
>Obtaining and installing certificates consists of the following steps:
>
><ul>
>
><li>
><a href="ssl.htm#1041474" >Step 1: Generate a Certificate Request</a>
><a name="1044650"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
><a href="ssl.htm#1079314" >Step 2: Send the Certificate Request</a> to the Certificate Authority
><a name="1044654"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
><a href="ssl.htm#1041552" >Step 3: Install the Certificate</a>
><a name="1044658"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
><a href="ssl.htm#1043718" >Step 4: Trust the Certificate Authority</a>
><a name="1044662"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
><a href="ssl.htm#1046393" >Step 5: Confirm That Your New Certificates Are Installed</a>
><a name="1044666"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
></ul>
>
><a name="1041473"> </a>
>You will use the Certificate Request Wizard to generate a certificate request (Step 1) and send it to a Certificate Authority (Step 2). You then use the Certificate Install Wizard to install the certificate (Step 3) and to trust the Certificate Authority's certificate (Step 4).
>
>
><a name="1080491"> </a>
>These wizards automate the process of creating a certificate database and of installing the key-pair.
>
>
><a name="1041474"> </a>
><a name="Step 1: Generate a Certificate Request"> </a>
>Step 1: Generate a Certificate Request
>
>
>
>
><a name="1041476"> </a>
>To generate a certificate request and send it to a CA:
>
><ol type="1">
>
><li value="1">
>In the Directory Server Console, select the Tasks tab, and click Manage Certificates.
><a name="1041482"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1079261"> </a>
>The Manage Certificates window is displayed.
> &nbsp;</dt> </dl>
>
><li value="2">
>Select the Server Certs tab, and click the Request button.
><a name="1079262"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1079263"> </a>
>The Certificate Request Wizard is displayed. 
> &nbsp;</dt> </dl>
>
><li value="3">
>Click Next.
><a name="1079273"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="4">
>Enter the following Requestor Information in the blank text fields, then click Next:
><a name="1079284"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <ul>
>
><li>
>Server Name &#151; Enter the fully qualified hostname of the Directory Server as it is used in DNS lookups; for example, <code>dir.example.com</code>.
><a name="1041519"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
><li>
>Organization &#151; Enter the legal name of your company or institution. Most CAs require you to verify this information with legal documents such as a copy of a business license.
><a name="1041523"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
><li>
>Organizational Unit &#151; Optional. Enter a descriptive name for your organization within your company. 
><a name="1041525"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
><li>
>Locality &#151; Optional. Enter your company's city name.
><a name="1041527"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
><li>
>State or Province &#151; Enter the full name of your company's state or province (no abbreviations).
><a name="1041529"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
><li>
>Country &#151; Select the two-character abbreviation for your country's name (ISO format). The country code for the United States is US. 
><a name="1041531"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li> </ul>
>
><li value="5">
>Enter the password that will be used to protect the private key, and click Next.
><a name="1041533"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1079290"> </a>
>The Next field is grayed out until you supply a password. When you click Next, the Request Submission dialog box is displayed.
> &nbsp;</dt> </dl>
>
><li value="6">
>Select Copy to Clipboard or Save to File to save the certificate request information that you must send to the Certificate Authority.
><a name="1079289"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="7">
>Click Done to dismiss the Certificate Request Wizard.
><a name="1079308"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
></ol>
>
><a name="1041534"> </a>
>Once you have generated the request, you are ready to send it to the CA.
>
>
><a name="1079314"> </a>
><a name="Step 2: Send the Certificate Request"> </a>
>Step 2: Send the Certificate Request
>
>
>
>
><a name="1079316"> </a>
>Follow these steps to send the certificate information to the CA:
>
><ol type="1">
>
><li value="1">
>Use your email program to create a new email message.
><a name="1079317"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="2">
>Copy the certificate request information from the clipboard or the saved file into the body of the message.
><a name="1041542"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1054006"> </a>
>The content will look similar to the following example:
> &nbsp;</dt> <dt> <a name="1079336"> </a>
><code>-----BEGIN NEW CERTIFICATE REQUEST----- MIIBrjCCARcCAQAwbjELMAkGA1UEBhMCVXMxEzARBgNVBAgTCkNBTElGT1J OSUExLDAqBgVBAoTI25ldHNjYXBlIGNvbW11bmljYXRpb25zIGNvcnBvcmF 0aW9uMRwwGgYDVQQDExNtZWxsb24ubmV0c2NhcGUuY29tMIGfMA0GCSqGSI b3DQEBAQUAA4GNADCBiQKBgQCwAbskGh6SKYOgHy+UCSLnm3ok3X3u83Us7 ug0EfgSLR0f+K41eNqqRftGR83emqPLDOf0ZLTLjVGJaH4Jn4l1gG+JDf/n /zMyahxtV7+mT8GOFFigFfuxaxMjr2j7IvELlxQ4IfZgWwqCm4qQecv3G+N 9YdbjveMVXW0v4XwIDAQABoAAwDQYK -----END NEW CERTIFICATE REQUEST-----</code>
> &nbsp;</dt> </dl>
>
><li value="3">
>Send the email message to the CA.
><a name="1041549"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
></ol>
>
><a name="1041550"> </a>
>Once you have emailed your request, you must wait for the CA to respond with your certificate. Response time for requests varies. For example, if your CA is internal to your company, it may only take a day or two to respond to your request. If your selected CA is external to your company, it could take several weeks to respond to your request.
>
>
><a name="1047992"> </a>
>When the CA sends a response, be sure to save the information in a text file. You will need the data when you install the certificate.
>
>
><a name="1047990"> </a>
>You should also back up the certificate data in a safe location. If your system ever loses the certificate data, you can reinstall the certificate using your backup file.
>
>
><a name="1047984"> </a>
>Once you receive your certificate, you are ready to install it in your server's certificate database. 
>
>
><a name="1041552"> </a>
><a name="Step 3: Install the Certificate"> </a>
>Step 3: Install the Certificate
>
>
>
>
><a name="1041553"> </a>
>To install a server certificate:
>
><ol type="1">
>
><li value="1">
>In the Directory Server Console, select the Tasks tab, and click Manage Certificates.
><a name="1079353"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1079354"> </a>
>The Manage Certificates window is displayed.
> &nbsp;</dt> </dl>
>
><li value="2">
>Select the Server Certs tab, and click Install.
><a name="1079355"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1079356"> </a>
>The Certificate Install Wizard is displayed. 
> &nbsp;</dt> </dl>
>
><li value="3">
>Choose one of the following options for the certificate location, then click Next.
><a name="1046318"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <ul>
>
><li>
>In this file &#151; Enter the absolute path to the certificate in this field.
><a name="1050391"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
><li>
>In the following encoded text block &#151; Copy the text from the CA's email or from the text file you created, and paste it in this field. For example:
><a name="1043576"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li> </ul>
> <dl>
> <dt> <a name="1043535"> </a>
><code>-----BEGIN CERTIFICATE----- MIICMjCCAZugAwIBAgICCEEwDQYJKoZIhvcNAQEFBQAwfDELMAkGA1UEBhMCVVMx IzAhBgNVBAoTGlBhbG9va2FWaWxsZSBXaWRnZXRzLCBJbmMuMR0wGwYDVQQLExRX aWRnZXQgTWFrZXJzICdSJyBVczEpMCcGA1UEAxMgVGVzdCBUZXN0IFRlc3QgVGVz dCBUZXN0IFRlc3QgQ0EwHhcNOTgwMzEyMDIzMzU3WhcNOTgwMzI2MDIzMzU3WjBP MQswCQYDVQQGEwJVUzEoMCYGA1UEChMfTmV0c2NhcGUgRGlyZWN0b3J5IFB1Ymxp Y2F0aW9uczEWMBQGA1UEAxMNZHVgh49dq2itLmNvbTBaMA0GCSqGSIb3 -----END CERTIFICATE-----</code>
> &nbsp;</dt> </dl>
>
><li value="4">
>Check that the certificate information displayed is correct, and click Next.
><a name="1044365"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="5">
>Specify a name for the certificate, and click Next.
><a name="1079538"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="6">
>Verify the certificate by providing the password that protects the private key.
><a name="1083263"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1083264"> </a>
>This password is the same as the one you provided in "<a href="ssl.htm#1041474" >Step 1: Generate a Certificate Request</a>," on <a href="ssl.htm#1079353" >page 423</a>.
> &nbsp;</dt> </dl>
></ol>
>
><a name="1083268"> </a>
>Now that you have installed your certificate, you need to configure your server to trust the Certificate Authority from which you obtained the server's certificate.
>
>
><a name="1043718"> </a>
><a name="Step 4: Trust the Certificate Authority"> </a>
>Step 4: Trust the Certificate Authority
>
>
>
>
><a name="1042273"> </a>
>Configuring your Directory Server to trust the certificate authority consists of obtaining your CA's certificate and installing it into your server's certificate database. This process differs depending on the certificate authority you use. Some commercial CAs provide a web site that allows you to automatically download the certificate. Others will email it to you upon request.
>
>
><a name="1054205"> </a>
>Once you have the CA certificate, you can use the Certificate Install Wizard to configure the Directory Server to trust the Certificate Authority.
>
><ol type="1">
>
><li value="1">
>In the Directory Server Console, select the Tasks tab, and click Manage Certificates.
><a name="1079564"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1079565"> </a>
>The Manage Certificates window is displayed.
> &nbsp;</dt> </dl>
>
><li value="2">
>Go to the CA Certs tab, and click Install.
><a name="1079568"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1079572"> </a>
>The Certificate Install Wizard is displayed.
> &nbsp;</dt> </dl>
>
><li value="3">
>If you saved the CA's certificate to a file, enter the path in the field provided. If you received the CA's certificate via email, copy and paste the certificate, including the headers, into the text field provided. Click Next.
><a name="1044549"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="4">
>Check that the certificate information that is displayed is correct, and click Next.
><a name="1079595"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="5">
>Specify a name for the certificate, and click Next.
><a name="1079596"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="6">
>Select the purpose of trusting this Certificate Authority (you can select both):
><a name="1079606"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <ul>
>
><li>
>Accepting connections from clients (Client Authentication) &#151; The server checks that the client's certificate has been issued by a trusted Certificate Authority.
><a name="1079609"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
><li>
>Accepting connections to other servers (Server Authentication) &#151; This server checks that the directory to which it is making a connection (for replication updates, for example) has a certificate that has been issued by a trusted Certificate Authority.
><a name="1079610"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li> </ul>
>
><li value="7">
>Click Done to dismiss the wizard.
><a name="1050583"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
></ol>
>
><a name="1053860"> </a>
>Once you have installed your certificate and trusted the CA's certificate, you are ready to activate SSL. However, you should first make sure that the certificates have been installed correctly.
>
>
><a name="1046393"> </a>
><a name="Step 5: Confirm That Your New Certificates Are Installed"> </a>
>Step 5: Confirm That Your New Certificates Are Installed
>
>
>
><ol type="1">
>
><li value="1">
>In the Directory Server Console, select the Tasks tab, and click Manage Certificates.
><a name="1079369"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1079370"> </a>
>The Manage Certificates window is displayed.
> &nbsp;</dt> </dl>
>
><li value="2">
>Select the Server Certs tab.
><a name="1079373"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1054019"> </a>
>A list of all the installed certificates for the server is displayed.
> &nbsp;</dt> </dl>
>
><li value="3">
>Scroll through the list. You should find the certificates you installed.
><a name="1042292"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1079376"> </a>
>Your server is now ready for SSL activation.
> &nbsp;</dt><table border="0" cellpadding="0" width="90%">
><tr><td colspan="2">
><hr size="1" />
></td></tr>
><tr>
><td valign="top">
><a name="1085779"> </a>
>Note&nbsp;&nbsp;
>
>
></td>
><td valign="top">
><a name="1085781"> </a>
>When you renew a certificate using the Certificate Wizard, the text on the introduction screen (step 1) doesn't clearly indicate that the process is renewal and not requesting a new certificate. Also, the requestor information (step 2) doesn't get filled automatically.
>
></td>
> </tr>
>
><tr><td colspan="2">
><hr size="1" />
></td></tr>
></table>
>
> 
> 
>
> </dl>
></ol>
>
><a name="1089063"> </a>
><a name="Using certutil"> </a>
>Using certutil
><hr size="1" noshade="noshade" />
>
>
>
><a name="1087251"> </a>
>The Directory Server has a command-line tool, <code>certutil</code>, which locally creates self-signed CA and client certificates, certificate databases, and keys. The default location for the Directory Server <code>certutil</code> tool is serverRoot/shared/bin/.
>
>
><a name="1089269"> </a>
><code>certutil</code> can also be downloaded from <a href="ftp://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/"><code>ftp://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/</code></a>.
>
>
><a name="1088112"> </a>
>The following steps outline how to make the databases, key, CA certificate, and server/client certificate and convert the certificates into <code>pkcs12</code> format.
>
><ol type="1">
>
><li value="1">
>Open the directory where the Directory Server certificate databases are stored.
><a name="1089299"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1089301"> </a>
><code>cd </code>serverRoot/alias
> &nbsp;</dt> </dl>
>
><li value="2">
>Make a backup copy of all of the filed in the directory as a precaution. If something goes awry with while managing certificates, the databases can then be restored. For example:
><a name="1089305"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1089307"> </a>
><code>tar -cf /tmp/db-backup.tar *</code>
> &nbsp;</dt> </dl>
>
><li value="3">
>Create a password file for the security token password.
><a name="1089311"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1089313"> </a>
><code>vi /tmp/pwdfile</code>
> &nbsp;</dt> <dt> <a name="1089315"> </a>
><code>secretpw</code>
> &nbsp;</dt> <dt> <a name="1089317"> </a>
>This password locks the server's private key in the key database and is used when the keys and certificates are first created. The password in this file is also the default password to encrypt PK12 files used by <code>pk12util</code>. Because this password is stored in plaintext, the password file should be owned by the user as which Directory Server runs, by default <code>nobody</code>, and it must be set as read-only for the Directory Server user and allow no access to anyone else (mode <code>0400</code>). It's a good idea to have a secure backup of this file.
> &nbsp;</dt> </dl>
>
><li value="4">
>Set the environment variable for the shell to include the <code>certutil</code> directory path. For example:
><a name="1089320"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1089322"> </a>
><code>export PATH=</code>serverRoot/shared/bin/:$PATH
> &nbsp;</dt> <dt> <a name="1089324"> </a>
>The command varies depending on the shell.
> &nbsp;</dt> </dl>
>
><li value="5">
>Create the key and certificate databases databases.
><a name="1089327"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1089329"> </a>
><code>certutil -N -d . -f /tmp/pwdfile -P slapd-</code>instance_name-
> &nbsp;</dt> </dl>
>
><li value="6">
>Generate the self-signed CA certificate. <code>certutil</code> creates the required key pairs and the certificate. This certificate is used to generate the other server certificates and can be exported for use with other servers and clients.
><a name="1089333"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1089335"> </a>
><code>certutil -S -n "CA certificate" -s "cn=My Org CA cert, dc=example,dc=com" -x -t "CT,," -m 1000 -v 120 -d . -k rsa -g 1024 -f /tmp/pwdfile -P slapd-</code>instance_name-
> &nbsp;</dt> </dl>
>
><li value="7">
>Generate the Directory Server client certificate.
><a name="1089340"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1089342"> </a>
><code>certutil -S -n "Server-Cert" -s "cn=</code>FQDN,cn=Directory Server" -c "CA certificate" -t "u,u,u" -m 1001 -v 120 -d . -k rsa -g 1024 -f /tmp/pwdfile -P slapd-instance_name-
> &nbsp;</dt> <dt> <a name="1089345"> </a>
>The value of the <code>-s</code> argument is very important. The leftmost RDN must be <code>cn=</code>FQDN (where FQDN is the fully-qualified host and domain name of the Directory Server). For example, to issue a certificate for a server with the name <code>ldap.example.com</code>, specifiy at least <code>-s "cn=ldap.example.com"</code>; it is beneficial to have a more descriptive name to help with server identification, such as <code>"cn=ldap.example.com, ou=DS1"</code>. The FQDN must be available for DNS and reverse DNS lookups to Directory Server clients because certificate validation may fail if the clients cannot properly resolve the FQDN, and some clients refuse to connect if a server certificate does not have its FQDN in the subject. Additionally, using the format <code>cn=</code>hostname.domain is essential for Directory Server clients to protect themselves from man in the middle attacks.
> &nbsp;</dt> <dt> <a name="1089347"> </a>
>To provide a subjectAltName, as well as the nickname, use the <code>-8</code> argument in addition to the <code>-s</code> argument.
> &nbsp;</dt> <dt> <a name="1089349"> </a>
>To use the Directory Server behind a DNS round robin or any other scheme which aliases a single server certificate to multiple hostnames, see the TLS/SSL information about server name wildcards or subjectAltName.
> &nbsp;</dt> <dt> <a name="1089351"> </a>
>Server certificates for other servers are created using a similar command as for the Directory Server certificate. Make sure that every <code>-n</code> option (nickname) and <code>-m</code> option (serial number) is unique for every certificate, and make sure that the <code>-s</code> option gives the correct FQDN for the server.
> &nbsp;</dt> <dt> <a name="1089470"> </a>
><table border="0" cellpadding="0" width="90%">
><tr><td colspan="2">
><hr size="1" />
></td></tr>
><tr>
><td valign="top">
><a name="1089467"> </a>
>Note&nbsp;&nbsp;
>
>
></td>
><td valign="top">
><a name="1089469"> </a>
>Keep careful track on the numbers set with the -m option. The -m option sets the unique identifier for the server certificate, and a CA cannot issue two certificates with the same ID. Keep a log of issued serial numbers so that no number is ever duplicated.
>
></td>
> </tr>
>
><tr><td colspan="2">
><hr size="1" />
></td></tr>
></table>
>
> &nbsp;</dt> </dl>
>
><li value="8">
>Export the CA certificate for use with other servers and clients. A client usually requires the CA certificate to validate the server certificate in an TLS/SSL connection. Use certutil to export the CA certificate in ASCII/PEM format:
><a name="1089357"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1089359"> </a>
><code>certutil -d . -L -n "CA certificate" -a &gt; cacert.asc -P slapd-</code>instance_name-
> &nbsp;</dt> <dt> <a name="1089361"> </a>
>The way that the CA certificate is imported is different for every client. For example, certutil can import a CA certificate into another Directory Server certificiate database:
> &nbsp;</dt> <dt> <a name="1089363"> </a>
><code>cd </code>other-serverRoot/alias
> &nbsp;</dt> <dt> <a name="1089364"> </a>
><code>certutil -A -d . -n "CA certificate" -t "CT,," -a -i cacert.asc -P slapd-</code>instance_name-
> &nbsp;</dt> </dl>
>
><li value="9">
>Use pk12util to export other server certificates and keys created with certutil so that they can be used on a remote server.
><a name="1089368"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1089370"> </a>
><code>pk12util -d . -o ldap1.p12 -n Server-Cert1 -w /tmp/pwdfile -k /tmp/pwdfile -P slapd-</code>instance_name-
> &nbsp;</dt> <dt> <a name="1089372"> </a>
>The <code>-w</code> argument is the password used to encrypt the <code>.p12</code> file for transport. The <code>-k</code> argument specifies the password for the key database containing the server certificate being exported to <code>.p12</code>.
> &nbsp;</dt> </dl>
>
><li value="10">
>If the Directory Server will run with TLS/SSL enabled, then create a password file (<code>pin.txt</code>) for the server to use so it will not prompt you for a password every time it restarts. Creating the password file is described in <a href="ssl.htm#1087372" >"Creating a Password File"</a>.
><a name="1089295"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
></ol>
>
><a name="1087756"> </a>
>The certificates created by <code>certutil</code> are automatically available in the Encryption tab of the Console; there is not need to import them.
>
>
><a name="1087250"> </a>
><a name="Starting the Server with SSL Enabled"> </a>
>Starting the Server with SSL Enabled
><hr size="1" noshade="noshade" />
>
>
>
><a name="1080534"> </a>
>Most of the time, you want your server to run with SSL enabled. If you temporarily disable SSL, make sure you re-enable it before processing transactions that require confidentiality, authentication, or data integrity.
>
>
><a name="1088984"> </a>
>There are two ways to use SSL:
>
><ul>
>
><li>
>Enabling SSL communications to the Directory Server only
><a name="1088985"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
>Requiring SSL among the Directory Server, Admin Server, Console, and other client applications
><a name="1088988"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
></ul>
>
><a name="1088998"> </a>
>For routine use, you only need to enable SSL to the Directory Server.
>
>
><a name="1080536"> </a>
>Before you can activate SSL, you must create a certificate database, obtain and install a server certificate, and trust the CA's certificate, as described in <a href="ssl.htm#1085091" >"Obtaining and Installing Server Certificates"</a>.
>
><table border="0" cellpadding="0" width="90%">
><tr><td colspan="2">
><hr size="1" />
></td></tr>
><tr>
><td valign="top">
><a name="1082196"> </a>
>Note&nbsp;&nbsp;
>
>
></td>
><td valign="top">
><a name="1082198"> </a>
>On SSL-enabled servers, be sure to check the file permissions on certificate-database files, key-databases files, and PIN files to protect the sensitive information they contain. Because the server does not enforce read-only permissions on these files, check the file modes to protect the sensitive information contained in these files.
>
></td>
> </tr>
>
><tr><td colspan="2">
><hr size="1" />
></td></tr>
></table>
>
> 
> 
>
>
><a name="1087338"> </a>
><a name="Enabling SSL Only in the Directory Server:"> </a>
>Enabling SSL Only in the Directory Server:
>
>
>
><ol type="1">
>
><li value="1">
>Obtain and install CA and server certificates.
><a name="1087398"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="2">
>Set the secure port you want the server to use for SSL communications. 
><a name="1087399"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1087658"> </a>
>The encrypted port number that you specify must not be the same port number you use for normal LDAP communications. By default, the standard port number is <code>389</code>, and the secure port is <code>636</code>. if you did not install the server as <code>root</code>, change to a port number above <code>1024</code>:
> &nbsp;</dt> </dl>
> <ol type="a">
>
><li>
>Change the secure port number in the Configuration&gt;Settings tab of the Directory Server Console. Save.
><a name="1087694"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
><li>
>Restart the Directory Server. It will restart still with the regular port.
><a name="1087687"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li> </ol>
>
><li value="3">
>In the Directory Server Console, select the Configuration tab, and then select the topmost entry in the navigation tree in the left pane. Select the Encryption tab in the right pane.
><a name="1087691"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="4">
>Select the "Enable SSL for this Server" checkbox.
><a name="1087406"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="5">
>Check the "Use this Cipher Family" checkbox.
><a name="1087407"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="6">
>Select the certificate that you want to use from the drop-down menu.
><a name="1087408"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="7">
>Click Cipher Settings.
><a name="1087409"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1087410"> </a>
>The Cipher Preference dialog box is displayed. By default, all ciphers are selected.
> &nbsp;</dt> </dl>
>
><li value="8">
>Set your preferences for client authentication. 
><a name="1087456"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <ul>
>
><li>
>Do not allow client authentication &#151; With this option, the server will ignore the client's certificate. This does not mean that the bind will fail.
><a name="1087457"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
><li>
>Allow client authentication &#151; This is the default setting. With this option, authentication is performed on the client's request. For more information about certificate-based authentication, see <a href="ssl.htm#1053102" >"Using Certificate-Based Authentication"</a>.
><a name="1087458"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
><li>
>Require client authentication &#151; With this option, the server requests authentication from the client.
><a name="1087462"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li> </ul>
> <dl>
> <dt> <a name="1087628"> </a>
>If you are only enabling SSL in the Directory Server, do not select "Require client authentication" checkbox.
> &nbsp;</dt><table border="0" cellpadding="0" width="90%">
><tr><td colspan="2">
><hr size="1" />
></td></tr>
><tr>
><td valign="top">
><a name="1087465"> </a>
>Note&nbsp;&nbsp;
>
>
></td>
><td valign="top">
><a name="1087467"> </a>
>If you are using certificate-based authentication with replication, then you must configure the consumer server either to allow or to require client authentication.
>
></td>
> </tr>
>
><tr><td colspan="2">
><hr size="1" />
></td></tr>
></table>
>
> 
> 
>
> </dl>
>
><li value="9">
>You can further configure the server to verify the authenticity of requests by selecting the "Check hostname against name in certificate for outbound SSL connections" option. The server does this verification by matching the hostname against the value assigned to the common name (<code>cn</code>) attribute of the subject name in the <a href="glossary.htm#1044149" >certificate</a> being presented for authentication.
><a name="1087482"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1087486"> </a>
>By default, this feature is disabled. If it's enabled and if the hostname does not match the <code>cn</code> attribute of the certificate, appropriate error and audit messages are logged. For example, in a replicated environment, messages similar to these are logged in the supplier server's log files if it finds that the peer server's hostname doesn't match the name specified in its certificate:
> &nbsp;</dt> <dt> <a name="1087491"> </a>
><code>[DATE] - SSL alert: ldap_sasl_bind("",LDAP_SASL_EXTERNAL) 81 (Netscape runtime error -12276 - Unable to communicate securely with peer: requested domain name does not match the server's certificate.)</code>
> &nbsp;</dt> <dt> <a name="1087492"> </a>
><code>[DATE] NSMMReplicationPlugin - agmt="cn=to ultra60 client auth" (ultra60:1924): Replication bind with SSL client authentication failed: LDAP error 81 (Can't contact LDAP server)</code>
> &nbsp;</dt> <dt> <a name="1087496"> </a>
>It is recommended that you enable this option to protect Directory Server's outbound SSL connections against a Man in the Middle (MITM) attack.
> &nbsp;</dt> </dl>
>
><li value="10">
>Click Save.
><a name="1087497"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="11">
>Restart the Directory Server. You must restart from the command-line.
><a name="1087501"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
></ol>
>
><a name="1087514"> </a>
><a name="Enabling SSL in the Directory Server, Admin Server, and Console"> </a>
>Enabling SSL in the Directory Server, Admin Server, and Console
>
>
>
><ol type="1">
>
><li value="1">
>Obtain server certificates and CA certs, and install them on the Directory Server. 
><a name="1087451"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="2">
>Obtain and install server and CA certificates on the Administration Server.
><a name="1087270"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1087271"> </a>
>It is important that the Administration Server and Directory Server have their CA certificates in common so that they trust the other's certificates.
> &nbsp;</dt> </dl>
>
><li value="3">
>If you have not installed the servers as <code>root</code>, it is necessary to change the secure port setting from the default <code>636</code> to a number above <code>1024</code>. 
><a name="1087272"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <ol type="a">
>
><li>
>Change the secure port number in the Configuration&gt;Settings tab of the Directory Server Console. Save.
><a name="1087273"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
><li>
>Restart the Directory Server. It will restart still with the regular port.
><a name="1087274"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li> </ol>
>
><li value="4">
>In the Configuration tab of the Directory Server Console, highlight the server name at the top of the table, and select the Encryption tab.
><a name="1087275"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="5">
>Select the "Enable SSL" checkbox.
><a name="1087549"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="6">
>Check the "Use this Cipher Family" checkbox.
><a name="1087702"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="7">
>Select the certificate that you want to use from the drop-down menu.
><a name="1087703"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="8">
>Click Cipher Settings.
><a name="1087704"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1087705"> </a>
>The Cipher Preference dialog box is displayed. By default, all ciphers are selected.
> &nbsp;</dt> </dl>
>
><li value="9">
>Set your preferences for client authentication.
><a name="1087578"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <ul>
>
><li>
>Do not allow client authentication &#151; With this option, the server will ignore the client's certificate. This does not mean that the bind will fail.
><a name="1087579"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
><li>
>Allow client authentication &#151; This is the default setting. With this option, authentication is performed on the client's request. For more information about certificate-based authentication, see <a href="ssl.htm#1053102" >"Using Certificate-Based Authentication"</a>.
><a name="1087580"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
><li>
>Require client authentication &#151; With this option, the server requests authentication from the client.
><a name="1087584"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li><table border="0" cellpadding="0" width="90%">
><tr><td colspan="2">
><hr size="1" />
></td></tr>
><tr>
><td valign="top">
><a name="1087587"> </a>
>Note&nbsp;&nbsp;
>
>
></td>
><td valign="top">
><a name="1087589"> </a>
>If you are using certificate-based authentication with replication, then you must configure the consumer server either to allow or to require client authentication.
>
></td>
> </tr>
>
><tr><td colspan="2">
><hr size="1" />
></td></tr>
></table>
>
> 
> 
>
> </ul>
>
><li value="10">
>You can further configure the server to verify the authenticity of requests by selecting the "Check hostname against name in certificate for outbound SSL connections" option. The server does this verification by matching the hostname against the value assigned to the common name (<code>cn</code>) attribute of the subject name in the <a href="glossary.htm#1044149" >certificate</a> being presented for authentication.
><a name="1087640"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1087644"> </a>
>By default, this feature is disabled. If it's enabled and if the hostname does not match the <code>cn</code> attribute of the certificate, appropriate error and audit messages are logged. For example, in a replicated environment, messages similar to these are logged in the supplier server's log files if it finds that the peer server's hostname doesn't match the name specified in its certificate:
> &nbsp;</dt> <dt> <a name="1087645"> </a>
><code>[DATE] - SSL alert: ldap_sasl_bind("",LDAP_SASL_EXTERNAL) 81 (Netscape runtime error -12276 - Unable to communicate securely with peer: requested domain name does not match the server's certificate.)</code>
> &nbsp;</dt> <dt> <a name="1087646"> </a>
><code>[DATE] NSMMReplicationPlugin - agmt="cn=to ultra60 client auth" (ultra60:1924): Replication bind with SSL client authentication failed: LDAP error 81 (Can't contact LDAP server)</code>
> &nbsp;</dt> <dt> <a name="1087650"> </a>
>It is recommended that you enable this option to protect Directory Server's outbound SSL connections against a Man in the Middle (MITM) attack.
> &nbsp;</dt> </dl>
>
><li value="11">
>Check the "Use SSL in the Console" box. Hit "Save."
><a name="1087638"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="12">
>In the Administration Server Console, select the Configuration tab. Select the Encryption tab, check the "Enable SSL" checkbox, and fill in the appropriate certificate information.
><a name="1087281"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="13">
>In the Configuration DS tab, change the port number to the new Directory Server secure port information. See <a href="intro.htm#1070843" >"Changing Directory Server Port Numbers"</a>, for more information. Do this even if you are using the default port of <code>636</code>. 
><a name="1087282"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1089020"> </a>
>Check the "Secure Connection" checkbox. 
> &nbsp;</dt> </dl>
>
><li value="14">
>In the User DS tab, select the "Set User Directory" radio button, and fill in the new Directory Server secure port information, the LDAP URL, and the user database information. 
><a name="1087286"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1089021"> </a>
>Check the "Secure Connection" checkbox.
> &nbsp;</dt> </dl>
>
><li value="15">
>Save the new SSL settings, Configuration DS, and User DS information in the Administration Server.
><a name="1087287"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="16">
>Restart the Admin Server. You must start the server from the command-line.
><a name="1087291"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="17">
>Restart the Directory Server. You must start the server from the command-line.
><a name="1087292"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
></ol>
>
><a name="1087293"> </a>
>When you restart the Console, be certain that the address reads <code>https</code>; otherwise, the operation will time out, unable to find the Admin Server since it is running on a secure connection. When you successfully connect, a dialog box will appear, asking you to accept the certificate. Click OK to accept the certificate (you may choose whether to accept it only for that session or for always).
>
>
><a name="1087372"> </a>
><a name="Creating a Password File"> </a>
>Creating a Password File
>
>
>
>
><a name="1087374"> </a>
>You can create a password file to store your certificate password. By placing your certificate database password in a file, you can start your server from the Console and also allow your server to restart automatically when running unattended.
>
><table border="0" cellpadding="0" width="90%">
><tr><td colspan="2">
><hr size="1" />
></td></tr>
><tr>
><td valign="top">
><a name="1087377"> </a>
>Caution&nbsp;&nbsp;
>
></td>
><td valign="top">
><a name="1087379"> </a>
>This password is stored in cleartext within the password file, so its usage represents a significant security risk. Do not use a password file if your server is running in an unsecured environment.
>
></td>
> </tr>
>
><tr><td colspan="2">
><hr size="1" />
></td></tr>
></table>
>
> 
> 
>
>
><a name="1087381"> </a>
>The password file must be placed in the following location:
>
>
><a name="1087382"> </a>
>serverRoot&nbsp;<code>/alias/slapd-</code>serverID&nbsp;<code>-pin.txt</code>
>
>
><a name="1089038"> </a>
>where serverID is the identifier you specified for the server when you installed it.
>
>
><a name="1089039"> </a>
>You need to include the token password in the file: 
>
><dl>
><a name="1089040"></a>
>mypassword
>
></dl>
><a name="1087386"> </a>
>When the server restarts, it will use this value as the token PIN.
>
>
><a name="1038525"> </a>
><a name="Setting Security Preferences"> </a>
>Setting Security Preferences
><hr size="1" noshade="noshade" />
>
>
>
><a name="1038529"> </a>
>You can choose the type of ciphers you want to use for SSL communications. A cipher is the algorithm used in encryption. Some ciphers are more secure, or stronger, than others. Generally speaking, the more bits a cipher uses during encryption, the more difficult it is to decrypt the key. For a more complete discussion of algorithms and their strength, see <a href="../pdf/console60.pdf">Managing Servers with Red Hat Console</a>.
>
>
><a name="1038533"> </a>
>When a client initiates an SSL connection with a server, the client tells the server what ciphers it prefers to use to encrypt information. In any two-way encryption process, both parties must use the same ciphers. There are a number of ciphers available. Your server needs to be able to use the ciphers that will be used by client applications connecting to the server.
>
>
><a name="1038536"> </a>
>Directory Server provides the following SSL 3.0 ciphers:
>
><ul>
>
><li>
>RC4 cipher with 40-bit encryption and MD5 message authentication.
><a name="1038540"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
>RC2 cipher with 40-bit encryption and MD5 message authentication.
><a name="1038542"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
>No encryption, only MD5 message authentication.
><a name="1079481"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
>DES with 56-bit encryption and SHA message authentication.
><a name="1040055"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
>RC4 cipher with 128-bit encryption and MD5 message authentication.
><a name="1079466"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
>Triple DES with 168-bit encryption and SHA message authentication.
><a name="1038546"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
>FIPS DES with 56-bit encryption and SHA message authentication. This cipher meets the FIPS 140-1 U.S. government standard for implementations of cryptographic modules.
><a name="1079475"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
>FIPS Triple DES with 168-bit encryption and SHA message authentication. This cipher meets the FIPS 140-1 US government standard for implementations of cryptographic modules.
><a name="1040124"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
></ul>
>
><a name="1052945"> </a>
>To select the ciphers you want the server to use:
>
><ol type="1">
>
><li value="1">
>Make sure SSL is enabled for your server.
><a name="1083310"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1083314"> </a>
>For information, see <a href="ssl.htm#1087250" >"Starting the Server with SSL Enabled"</a>.
> &nbsp;</dt> </dl>
>
><li value="2">
>In the Directory Server Console, select the Configuration tab, and then select the topmost entry in the navigation tree in the left pane.
><a name="1083318"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="3">
>Select the Encryption tab in the right pane.
><a name="1038569"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1079491"> </a>
>This displays the current server encryption settings.
> &nbsp;</dt> </dl>
>
><li value="4">
>Click Cipher Settings.
><a name="1079493"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1079494"> </a>
>The Cipher Preference dialog box is displayed.
> &nbsp;</dt> </dl>
>
><li value="5">
>In the Cipher Preference dialog box, specify which ciphers you want your server to use by selecting them from the list, and click OK.
><a name="1038571"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1079497"> </a>
>Unless you have a security reason not to use a specific cipher, you should select all of the ciphers, except for <code>none,MD5</code>. 
> &nbsp;</dt> </dl>
>
><li value="6">
>In the Encryption tab, click Save.
><a name="1077547"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
><table border="0" cellpadding="0" width="90%">
><tr><td colspan="2">
><hr size="1" />
></td></tr>
><tr>
><td valign="top">
><a name="1077555"> </a>
>Caution&nbsp;&nbsp;
>
></td>
><td valign="top">
><a name="1077562"> </a>
>Avoid selecting the <code>none,MD5</code> cipher because the server will use this option if no other ciphers are available on the client. It is not secure because encryption doesn't occur.
>
></td>
> </tr>
>
><tr><td colspan="2">
><hr size="1" />
></td></tr>
></table>
>
> 
> 
>
></ol>
>
><a name="1053148"> </a>
>In order to continue using the Red Hat Console with SSL, you must select at least one of the following ciphers:
>
><ul>
>
><li>
>RC4 cipher with 40-bit encryption and MD5 message authentication.
><a name="1053073"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
>No encryption, only MD5 message authentication.
><a name="1053091"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
>DES with 56-bit encryption and SHA message authentication.
><a name="1053130"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
>RC4 cipher with 128-bit encryption and MD5 message authentication.
><a name="1053135"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
>Triple DES with 168-bit encryption and SHA message authentication.
><a name="1053141"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
></ul>
>
><a name="1053102"> </a>
><a name="Using Certificate-Based Authentication"> </a>
>Using Certificate-Based Authentication
><hr size="1" noshade="noshade" />
>
>
>
><a name="1047830"> </a>
>Directory Server allows you to use certificate-based authentication for the command-line tools (which are LDAP clients) and for replication communications. Certificate-based authentication can occur between:
>
><ul>
>
><li>
>An LDAP client connecting to the Directory Server.
><a name="1079732"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
>A Directory Server connecting to another Directory Server (<a href="glossary.htm#1044601" >replication</a> or <a href="glossary.htm#1044157" >chaining</a>).
><a name="1079733"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
><table border="0" cellpadding="0" width="90%">
><tr><td colspan="2">
><hr size="1" />
></td></tr>
><tr>
><td valign="top">
><a name="1082141"> </a>
>Note&nbsp;&nbsp;
>
>
></td>
><td valign="top">
><a name="1082143"> </a>
>When specifying the key and certificate database filenames, you may use absolute or relative paths. If using relative paths, ensure that they are relative to the server root (for example, <code>alias/slapd-phonebook-cert8.db</code> and <code>alias/slapd-phonebook-key3.db</code>). 
>
>
><a name="1082211"> </a>
>The name of the certificate database has been changed from <code>cert7.db</code> to <code>cert8.db</code>. Directory Server automatically converts the <code>cert7.db</code> to <code>cert8.db</code> and uses the new file. However, the <code>dse.ldif</code> file may not show the new database name. For example, you may still see this entry: 
>
>
><a name="1082249"> </a>
><code>nsCertfile: alias/slapd-testDir-cert7.db</code>
>
>
><a name="1082213"> </a>
>If you want the database filename change reflected in the <code>dse.ldif</code> file, manually edit the filename in the <code>dse.ldif</code> file.
>
></td>
> </tr>
>
><tr><td colspan="2">
><hr size="1" />
></td></tr>
></table>
>
> 
> 
>
></ul>
>
><a name="1080310"> </a>
><a name="Setting up Certificate-Based Authentication"> </a>
>Setting up Certificate-Based Authentication
>
>
>
>
><a name="1080345"> </a>
>To set up certificate-based authentication, you must:
>
><ol type="1">
>
><li value="1">
>Create a certificate database for the client and the server or for both servers involved in replication.
><a name="1038642"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1079758"> </a>
>In the Directory Server, the certificate database creation automatically takes place when you install a certificate. For information on creating a certificate database for a client, see <a href="ssl.htm#1048777" >"Configuring LDAP Clients to Use SSL"</a>.
> &nbsp;</dt> </dl>
>
><li value="2">
>Obtain and install a certificate on both the client and the server or on both servers involved in replication.
><a name="1054091"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="3">
>Enable SSL on the server or on both servers involved in replication.
><a name="1038646"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1079627"> </a>
>For information on enabling SSL, refer to <a href="ssl.htm#1087250" >"Starting the Server with SSL Enabled"</a>.
> &nbsp;</dt><table border="0" cellpadding="0" width="90%">
><tr><td colspan="2">
><hr size="1" />
></td></tr>
><tr>
><td valign="top">
><a name="1080319"> </a>
>Note&nbsp;&nbsp;
>
>
></td>
><td valign="top">
><a name="1080321"> </a>
>If Red Hat Console connects to Directory Server over SSL, selecting "Require client authentication" disables communication. This is because, although Red Hat Console supports SSL, it does not have a certificate to use for client authentication.
>
></td>
> </tr>
>
><tr><td colspan="2">
><hr size="1" />
></td></tr>
></table>
>
> 
> 
>
> </dl>
>
><li value="4">
>Map the certificate's distinguished name to a distinguished name known by your directory.
><a name="1079626"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1054122"> </a>
>This allows you to set access control for the client when it binds using this certificate. This mapping process is described in <a href="../pdf/console60.pdf">Managing Servers with Red Hat Console</a>.
> &nbsp;</dt> </dl>
></ol>
>
><a name="1080341"> </a>
><a name="Allowing/Requiring Client Authentication"> </a>
>Allowing/Requiring Client Authentication
>
>
>
>
><a name="1080346"> </a>
>If you have configured Red Hat Console to connect to your Directory Server using SSL and your Directory Server requires client authentication, you can no longer use Red Hat Console to manage server applications. You will have to use the appropriate command-line utilities instead.
>
>
><a name="1080356"> </a>
>However, if at a later date you wish to change your directory configuration to no longer require but allow client authentication, so that you can use Red Hat Console, you must follow these steps:
>
><ol type="1">
>
><li value="1">
>Stop Directory Server.
><a name="1080342"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1080387"> </a>
>For information on stopping and starting the server from the command-line, see <a href="intro.htm#1072054" >"Starting and Stopping the Server from the Command-Line"</a>.
> &nbsp;</dt> </dl>
>
><li value="2">
>Modify the <code>cn=encryption,cn=config</code> entry by changing the value of the <code>nsSSLClientAuth</code> attribute from <code>required</code> to <code>allowed</code>.
><a name="1080372"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1080375"> </a>
>For information on modifying entries from the command-line, see <a href="modify.htm#996824" >chapter 2, "Creating Directory Entries</a>."
> &nbsp;</dt> </dl>
>
><li value="3">
>Start Directory Server.
><a name="1080376"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1080391"> </a>
>You can now start Red Hat Console.
> &nbsp;</dt> </dl>
></ol>
>
><a name="1048777"> </a>
><a name="Configuring LDAP Clients to Use SSL"> </a>
>Configuring LDAP Clients to Use SSL
><hr size="1" noshade="noshade" />
>
>
>
><a name="1079713"> </a>
>If you want all the users of your Directory Server to use SSL or certificate-based authentication when they connect using LDAP client applications, you must make sure they perform the following tasks:
>
><ul>
>
><li>
>Create a certificate database.
><a name="1079714"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li>
>Trust the Certificate Authority (CA) that issues the server certificate.
><a name="1048780"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
></ul>
>
><a name="1048781"> </a>
>These operations are sufficient if you want to ensure that LDAP clients recognize the server's certificate. However, if you also want LDAP clients to use their own certificate to authenticate to the directory, make sure that all your directory users obtain and install a personal certificate.
>
><table border="0" cellpadding="0" width="90%">
><tr><td colspan="2">
><hr size="1" />
></td></tr>
><tr>
><td valign="top">
><a name="1080077"> </a>
>Note&nbsp;&nbsp;
>
>
></td>
><td valign="top">
><a name="1080079"> </a>
>Some client applications do not verify that the server has a trusted certificate.
>
></td>
> </tr>
>
><tr><td colspan="2">
><hr size="1" />
></td></tr>
></table>
>
> 
> 
>
><ol type="1">
>
><li value="1">
>On the client system, obtain a client certificate from the CA.
><a name="1048792"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="2">
>On your client system, install your client certificate.
><a name="1079934"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1048793"> </a>
>Regardless of how you receive your certificate (either in email or on a web page), there should be a link that you click to install the certificate.
> &nbsp;</dt> <dt> <a name="1080095"> </a>
>Make sure you record the certificate information that is sent to you in a file. In particular, you must know the subject DN of the certificate because you must configure the server to map it to an entry in the directory. Your client certificate will be similar to:
> &nbsp;</dt> <dt> <a name="1080114"> </a>
><code>-----BEGIN CERTIFICATE----- MIICMjCCAZugAwIBAgICCEEwDQYJKoZIhvcNAQEFBQAwfDELMAkGA1UEBh MCVVMxIzAhBgNVBAoTGlBhbG9va2FWaWxsZSBXaWRnZXRzLCBJbmMuMR0w GwYDVQQLExRXaWRnZXQgTWFrZXJzICdSJyBVczEpMCcGA1UEAxMgVGVzdC BUZXN0IFRlc3QgVGVzdCBUZXN0IFRlc3QgQ0EwHhcNOTgwMzEyMDIzMzU3 WhcNOTgwMzI2MDIzMzU3WjBPMQswCQYDVQQGEwJVUzEoMCYGA1UEChMfTm V0c2NhcGUgRGlyZWN0b3 -----END CERTIFICATE-----</code>
> &nbsp;</dt> </dl>
>
><li value="3">
>You must convert the client certificate into its binary format using the <code>certutil</code> utility. To do this:
><a name="1080096"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1080194"> </a>
><code>certutil -L -d </code>certdbPath&nbsp;<code> -n </code>userCertName&nbsp;<code> -r &gt; </code>userCert.bin
> &nbsp;</dt> <dt> <a name="1080183"> </a>
>where certdbPath is the location of your certificate database, userCertName is the name you gave to your certificate when you installed it, and userCert.bin is the name you must specify for the output file that will contain the certificate in the binary format.
> &nbsp;</dt> </dl>
>
><li value="4">
>On the server, map the subject DN of the certificate that you obtained to the appropriate directory entry by editing the <code>certmap.conf</code> file.
><a name="1080182"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1079975"> </a>
>This procedure is described in <a href="../pdf/console60.pdf">Managing Servers with Red Hat Console</a>. 
> &nbsp;</dt><table border="0" cellpadding="0" width="90%">
><tr><td colspan="2">
><hr size="1" />
></td></tr>
><tr>
><td valign="top">
><a name="1080643"> </a>
>Note&nbsp;&nbsp;
>
>
></td>
><td valign="top">
><a name="1081629"> </a>
>Do not map your certificate-based-authentication certificate to a distinguished name under <code>cn=monitor</code>. If you map your certificate to a DN under <code>cn=monitor</code>, your bind will fail. Map your certificate to a target located elsewhere in the directory information tree.
>
>
><a name="1080652"> </a>
>Make sure that the <code>verifyCert</code> parameter is set to <code>on</code> in the <code>certmap.conf</code> file. If this parameter is not set to <code>on</code>, Directory Server simply searches for an entry in the directory that matches the information in the <code>certmap.conf</code> file. If the search is successful, it grants access without actually checking the value of the <code>userCertificate</code> and <code>userCertificate;binary</code> attributes.
>
></td>
> </tr>
>
><tr><td colspan="2">
><hr size="1" />
></td></tr>
></table>
>
> 
> 
>
> </dl>
>
><li value="5">
>In the Directory Server, modify the directory entry for the user who owns the client certificate to add the <code>userCertificate</code> attribute.
><a name="1079987"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <ol type="a">
>
><li>
>Select the Directory tab, and navigate to the user entry.
><a name="1080177"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
><li>
>Double click the user entry, and use the Property Editor to add the <code>userCertificate</code> attribute, with the <code>binary</code> subtype.
><a name="1080221"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li> <dl>
> <dt> <a name="1080226"> </a>
>When you add this attribute, instead of an editable field, the server provides a Set Value button.
> &nbsp;</dt> </dl>
>
><li>
>Click Set Value.
><a name="1080181"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li> <dl>
> <dt> <a name="1080234"> </a>
>A file selector is displayed. Use it to select the binary file you created in <a href="ssl.htm#1080096" >Step 3</a>.
> &nbsp;</dt> </dl>
> </ol>
> <dl>
> <dt> <a name="1080035"> </a>
>For information on using the Directory Server Console to edit entries, refer to "<a href="modify.htm#1128965" >Modifying Directory Entries</a>," on <a href="modify.htm#1128965" >page 49</a>.
> &nbsp;</dt> </dl>
></ol>
>
><a name="1079986"> </a>
>You can now use SSL with your LDAP clients. For information on how to use SSL with <code>ldapmodify</code>, <code>ldapdelete</code>, and <code>ldapsearch</code>, refer to <a href="../cli/utilities.htm">Red Hat Directory Server Configuration, Command, and File Reference</a>.
>
>
><a name="1083165"> </a>
><a name="Introduction to SASL"> </a>
>Introduction to SASL
><hr size="1" noshade="noshade" />
>
>
>
><a name="1083166"> </a>
>Directory Server supports LDAP client authentication through the Simple Authentication and Security Layer (<a href="glossary.htm#1044886" >SASL</a>), an alternative to SSL/TLS and a native way for some applications to share information securely. 
>
>
><a name="1086536"> </a>
>SASL is a framework, meaning it sets up a system that allows different mechanisms to authenticate a user to the server, depending on what mechanism is enabled in both client and server applications. SASL can also set up a security layer for an encrypted session. Directory Server utilizes the GSS-API mechanism to encrypt data during sessions.
>
><table border="0" cellpadding="0" width="90%">
><tr><td colspan="2">
><hr size="1" />
></td></tr>
><tr>
><td valign="top">
><a name="1083920"> </a>
>Note&nbsp;&nbsp;
>
>
></td>
><td valign="top">
><a name="1083922"> </a>
>SASL data encryption is not supported for client connections that use SSL/TLS.
>
></td>
> </tr>
>
><tr><td colspan="2">
><hr size="1" />
></td></tr>
></table>
>
> 
> 
>
>
><a name="1083896"> </a>
><a name="Authentication Mechanisms"> </a>
>Authentication Mechanisms
>
>
>
>
><a name="1083947"> </a>
>Directory Server support the following SASL encryption mechanisms:
>
><ul>
>
><li>
>EXTERNAL
><a name="1086152"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1086167"> </a>
>The EXTERNAL authentication mechanism is utilized by services such as SSL/TLS. It can be used with public keys for strong authentication.
> &nbsp;</dt> </dl>
>
><li>
>DIGEST-MD5
><a name="1086157"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1086180"> </a>
>DIGEST-MD5 is a mandatory authentication method for LDAPv3 servers. While it is not as strong as public key systems or Kerberos authentication methods, it is preferred over plaintext passwords and does protect against plaintext attacks.
> &nbsp;</dt> </dl>
>
><li>
>Generic Security Services (GSS-API)
><a name="1086158"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
> <dl>
> <dt> <a name="1086192"> </a>
>Generic Security Services (GSS) is a security API that is the native way for UNIX-based operating systems to access and authenticate Kerberos services. <a href="glossary.htm#1044906" >GSS-API</a> also supports session encryption via function calls that can be used to wrap and unwrap payload data. This allows LDAP clients to authenticate with the server using Kerberos version 5 credentials. 
> &nbsp;</dt><table border="0" cellpadding="0" width="90%">
><tr><td colspan="2">
><hr size="1" />
></td></tr>
><tr>
><td valign="top">
><a name="1085243"> </a>
>Note&nbsp;&nbsp;
>
>
></td>
><td valign="top">
><a name="1085245"> </a>
>GSS-API and, thus, Kerberos are only supported on platforms that have GSS-API support.
>
></td>
> </tr>
>
><tr><td colspan="2">
><hr size="1" />
></td></tr>
></table>
>
> 
> 
>
> </dl>
></ul>
>
><a name="1086217"> </a>
>DIGEST-MD5 and GSS-API are shared secret mechanisms. This means that the server challenge the client attempting to bind with a "secret," such as a password, that depends on the mechanism. The user sends back the response required by the mechanism. 
>
>
><a name="1085255"> </a>
><a name="SASL Identity Mapping"> </a>
>SASL Identity Mapping
>
>
>
>
><a name="1085259"> </a>
>When processing a SASL bind request, the server matches, or maps, the SASL user ID used to authenticate to the Directory Server with an LDAP entry stored within the server.
>
>
><a name="1086489"> </a>
>If the user ID clearly corresponds to the LDAP entry for a person, it is possible to configure the Directory Server to map the authentication DN automatically to the entry DN. Every branch in the directory tree has a default map, and customized maps can be created. During a bind attempt, a randomly selected custom map is applied. If only one user identity is returned, the bind is successful; if none or more than one are returned, then the next custom map is tried, and so on, until the default is tried. If no map works, then the bind fails.
>
><table border="0" cellpadding="0" width="90%">
><tr><td colspan="2">
><hr size="1" />
></td></tr>
><tr>
><td valign="top">
><a name="1087031"> </a>
>Note&nbsp;&nbsp;
>
>
></td>
><td valign="top">
><a name="1087033"> </a>
>SASL proxy authorization is not supported in Directory Server; therefore, the server will ignore any SASL <code>authzid</code> supplied by the client.
>
></td>
> </tr>
>
><tr><td colspan="2">
><hr size="1" />
></td></tr>
></table>
>
> 
> 
>
>
><a name="1086294"> </a>
>SASL is configured by entries under a container entry:
>
><dl>
><a name="1086282"></a>
>dn: cn=sasl,cn=config 
>objectClass: top 
>objectClass: nsContainer 
>cn: sasl
>
></dl>
><a name="1086283"> </a>
>SASL identity mapping entries are children of second container entry:
>
><dl>
><a name="1086284"></a>
>dn: cn=mapping,cn=sasl,cn=config 
>objectClass: top 
>objectClass: nsContainer 
>cn: mapping
>
></dl>
><a name="1086285"> </a>
>Mapping entries contain three attributes, <code>nsSaslMapRegexString</code>, <code>nsSaslMapBaseDNTemplate</code>, and <code>nsSaslMapFilterTemplate</code>. The <code>nsSaslMapping</code> object class sets these identity mapping parameters. The <code>nsSaslMapRegexString</code> attribute sets variables of the form <code>\1</code>, <code>\2</code>, <code>\3</code>, etc., for bind IDs which are filled into the template attributes during a search. For example, assume the <code>nsSaslMapping</code> is set up as follows:
>
><dl>
><a name="1085479"></a>
>dn: cn=mymap,cn=mapping,cn=sasl,cn=config 
>objectclass:top 
>objectclass:nsSaslMapping 
>cn: mymap 
>nsSaslMapRegexString: (.*)@(.*)\.(.*) 
>nsSaslFilterTemplate: (objectclass=inetOrgPerson) 
>nsSaslBaseDNTemplate: uid=\1,ou=people,dc=\2,dc=\3
>
></dl>
><a name="1086342"> </a>
>A bind attempt with <code>mconnors@example.com</code> as the regular expression would "fill in" the base DN template with <code>uid=mconnors,ou=people,dc=example,dc=com</code> as the authentication ID, and authentication would proceed from there.
>
>
><a name="1086891"> </a>
>You could also write a broader mapping scheme, such as the following:
>
><dl>
><a name="1086845"></a>
>objectclass: top 
>objectclass: nsSaslMapping 
>cn: mymap2 
>nsSaslMapRegexString: .* 
>nsSaslMapBaseDNTemplate: ou=People,dc=example,dc=com 
>nsSaslMapFilterTemplate: (cn=&amp;) 
>
></dl>
><a name="1086852"> </a>
>This will match any user ID and map to the result of the the subtree search with base <code>ou=People,dc=example,dc=com</code> and filter <code>cn=</code>userId.
>
>
><a name="1086549"> </a>
><a name="Legacy Identity Mapping"> </a>
>Legacy Identity Mapping
>
>
><a name="1086553"> </a>
>Older versions of Directory Server did support limited SASL mechanisms, EXTERNAL and DIGEST-MD5. These mechanisms have simple username-based identies, so the server implements a simple identity mapping scheme using the <code>uid</code> to find the corresponding directory entries. A user binds with an authentication DN such as <code>uid=bjensen,ou=people,dc=example,dc=com</code>, and the server searches across the entire directory contents, looking for an entry with a corresponding <code>uid</code>. This identity mapping is hard-coded and cannot be changed. 
>
>
><a name="1086660"> </a>
>Because Kerberos has more complicated identities (see <a href="ssl.htm#1086092" >"Realms"</a>), Directory Server supports regular expression-based mapping schemes. In processing a bind request, the server first tries to apply any regular expression mapping, if configured. If no match is found, then the server tries to apply legacy mapping.
>
>
><a name="1085437"> </a>
><a name="Configuring SASL Identity Mapping from the Console"> </a>
>Configuring SASL Identity Mapping from the Console
>
>
>
><ol type="1">
>
><li value="1">
>In the Console, open the Directory Server.
><a name="1085267"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="2">
>Open the "Configuration" tab.
><a name="1085268"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="3">
>Select the "SASL Mapping" tab.
><a name="1085274"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
>
><li value="4">
>Select the "Add" button, and fill in the required values.
><a name="1085278"> </a>
><img src="pixel.gif" align="top" height="22" alt="" />
></li>
></ol>
>
><a name="1085284"> </a>
>Before you can modify a SASL identity, you must have saved that identity. Then you can click on the "Modify" button, and a text box appears with the current values. Change the values you want, and then close, and hit "Save." To delete a SASL identity, highlight it, and hit the "Delete" button.
>
>
><a name="1087006"> </a>
><a name="Configuring SASL Identity Mapping from the Command-Line"> </a>
>Configuring SASL Identity Mapping from the Command-Line
>
>
>
>
><a name="1087016"> </a>
>To configure SASL identity mapping from the command-line, use the <code>ldapmodify</code> utility to configure an identity mapping scheme, such as the following:
>
><dl>
><a name="1087017"></a>
>ldapmodify -a -p 389 -h localhost -D <code>"</code>cn=directory manager<code>"</code> -w 
>password33
>
>
><a name="1089215"></a>
>dn: cn=mymap2,cn=mapping,cn=sasl,cn=config 
>objectclass: top 
>objectclass: nsSaslMapping 
>cn: mymap2 
>nsSaslMapRegexString: .* 
>nsSaslMapBaseDNTemplate: ou=People,dc=example,dc=com 
>nsSaslMapFilterTemplate: (cn=&amp;) 
>
></dl>
><a name="1087018"> </a>
>This will match any user ID and map to the result of the the subtree search with base <code>ou=People,dc=example,dc=com</code> and filter <code>cn=</code>userId.
>
>
><a name="1085885"> </a>
><a name="Configuring Kerberos"> </a>
>Configuring Kerberos
>
>
>
>
><a name="1084930"> </a>
>Kerberos v5 must be deployed on your system to utilize the GSS-API mechanism for SASL authentication. <a href="ssl.htm#1083776" >Table&nbsp;11-1</a> summarizes the Kerberos applications supported by various platforms. GSS-API must be enabled as a SASL mechanism in the Directory Server to take advantage of Kerberos services.
>
> 
>
><a name="1083776"> </a>
><a name="Supported Kerberos Systems"> </a>
>Table 11-1	&nbsp;&nbsp; Supported Kerberos Systems
>
> 
><table width="90%" border="1" cellspacing="0" cellpadding="4">
><tr>
><td valign="top">
>
><a name="1083780"> </a>
>Linux
></td>
><td valign="top">
>
><a name="1083782"> </a>
>MIT Kerberos version 5
></td>
> 
></tr>
><tr>
><td valign="top">
>
><a name="1083784"> </a>
>HP-UX 11i
></td>
><td valign="top">
>
><a name="1083786"> </a>
>HP Kerberos version 2.1
></td>
> 
></tr>
><tr>
><td valign="top">
>
><a name="1083788"> </a>
>Sun Solaris
></td>
><td valign="top">
>
><a name="1083790"> </a>
>SEAM 1.0.1
></td>
> 
></tr>
>
></table>
>
>
> 
> 
>
>
><a name="1086092"> </a>
><a name="Realms"> </a>
>Realms
>
>
><a name="1086072"> </a>
>A realm is a set of users and the authentication methods for those users to access the realm. A realm resembles a fully-qualified domain name and can be distributed across either a single server or a single domain across multiple machines. A single server instance can also support multiple realms.
>
>
><a name="1086505"> </a>
>Realms are used by the server to associate the DN of the client in the following form, which looks like an LDAP URL:
>
>
><a name="1086506"> </a>
><code>uid=</code>user_name&nbsp;<code>/[</code>server_instance&nbsp;<code>],cn=</code>realm&nbsp;<code>,cn=</code>mechanism&nbsp;<code>,cn=auth</code>
>
><table border="0" cellpadding="0" width="90%">
><tr><td colspan="2">
><hr size="1" />
></td></tr>
><tr>
><td valign="top">
><a name="1086075"> </a>
>Note&nbsp;&nbsp;
>
>
></td>
><td valign="top">
><a name="1086077"> </a>
>Kerberos systems treat the Kerberos realm as the default realm; other systems default to the server.
>
></td>
> </tr>
>
><tr><td colspan="2">
><hr size="1" />
></td></tr>
></table>
>
> 
> 
>
>
><a name="1086079"> </a>
>Mike Connors in the <code>engineering</code> realm of the European division of <code>example.com</code> would have the following association if he tried to access a different server, such as <code>cyclops</code>:
>
><dl>
><a name="1086080"></a>
>uid=mconnors/cn=Europe.example.com, 
>cn=engineering,cn=gssapi,cn=auth
>
></dl>
><a name="1086081"> </a>
>Babs Jensen in the <code>accounting</code> realm of <code>US.example.com</code> would not have to specify server_instance:
>
><dl>
><a name="1086082"></a>
>uid=bjensen,cn=accounting,cn=gssapi,cn=auth
>
></dl>
><a name="1086083"> </a>
>If realms are supported by the mechanism and the default realm was not used, realm must be specified; otherwise, it is omitted. Currently, only GSS-API supports the concept of realms.
>
>
><a name="1083840"> </a>
><a name="Configuring the KDC Server"> </a>
>Configuring the KDC Server
>
>
><a name="1084994"> </a>
>To use GSS-API, the user first obtains a ticket granting ticket (TGT). The ticket and the ticket's lifetime are parameters in the <code>kdc</code> server configuration in the <code>/etc/krb5/krb5.conf</code> file. See <a href="ssl.htm#1084197" ></a><a href="ssl.htm#1084197" >"Example"</a>.
>
><table border="0" cellpadding="0" width="90%">
><tr><td colspan="2">
><hr size="1" />
></td></tr>
><tr>
><td valign="top">
><a name="1086464"> </a>
>Note&nbsp;&nbsp;
>
>
></td>
><td valign="top">
><a name="1086473"> </a>
>The HP server and client are separate packages with their own configuration. The server stores config files in <code>/opt/krb5</code>. The client is classic MIT and uses <code>/etc/krb5.conf</code>. You need to configure both to have a working Kerberos system.
>
></td>
> </tr>
>
><tr><td colspan="2">
><hr size="1" />
></td></tr>
></table>
>
> 
> 
>
>
><a name="1086896"> </a>
>In order to respond to Kerberos operations, the Directory Server requires access to its own cryptographic key which is read by the Kerberos libraries that the server calls via GSSAPI. The details of how it is found are implementation-dependent. However, in current releases of the supported Kerberos implementations, the mechanism is the same: the key is read from a file called a keytab file. This file is created by the Kerberos administrator by exporting the key from the KDC. Either the system default keytab file (typically <code>/etc/krb5.keytab</code>) is used, or a service-specific keytab file determined by the value of the <code>KRB5_KTNAME</code> environment variable. 
>
>
><a name="1089263"> </a>
>The Directory Server uses the service name <code>ldap</code>. Its Kerberos principal is <code>ldap/</code>host-fqdn&nbsp;<code>@</code>realm. A key with this identity must be stored in the server's keytab in order for Kerberos to work. For information on setting up the service key, see your Kerberos documentation.
>
>
><a name="1084197"> </a>
><a name="Example"> </a>
>Example
>
>
><a name="1084208"> </a>
><a href="ssl.htm#1083638" >Code Example&nbsp;11-1</a> is an example code for a KDC server configured with the <code>company.example.com</code> realm.
>
> 
><table width="90%" border="0" cellpadding="0" cellspacing="0">
><tr><td>
>
><a name="1083638"> </a>
><a name="Configuring an Example KDC Server"> </a>
>Code Example 11-1	&nbsp;&nbsp; Configuring an Example KDC Server
>
></td></tr>
><tr><td><hr noshade size="1" /></td></tr>
>
><tr>
><td valign="top">
><code>
><a name="1083648"> </a>
>[libdefaults]
>
></code>
> <code>
><a name="1083649"> </a>
> ticket_lifetime = 24000
>
></code>
> <code>
><a name="1083650"> </a>
> default_realm = COMPANY.EXAMPLE.COM
>
></code>
> <code>
><a name="1083651"> </a>
> dns_lookup_realm = false
>
></code>
> <code>
><a name="1083652"> </a>
> dns_lookup_kdc = false
>
></code>
> <code>
><a name="1083653"> </a>
> ccache_type = 1
>
></code>
> <code>
><a name="1083654"> </a>
> forwardable = true
>
></code>
> <code>
><a name="1083655"> </a>
> proxiable = true
>
></code>
> <code>
><a name="1083656"> </a>
> default_tgs_enctypes = des3-hmac-sha1 des-cbc-crc
>
></code>
> <code>
><a name="1083657"> </a>
> default_tkt_enctypes = des3-hmac-sha1 des-cbc-crc
>
></code>
> <code>
><a name="1083658"> </a>
> permitted_enctypes = des3-hmac-sha1 des-cbc-crc
>
></code>
> <code>
><a name="1083659"> </a>
>[realms]
>
></code>
> <code>
><a name="1083660"> </a>
> COMPANY.EXAMPLE.COM = {
>
></code>
> <code>
><a name="1083661"> </a>
> kdc = kdcserver.company.example.com:88
>
></code>
> <code>
><a name="1083662"> </a>
> admin_server = adminserver.company.example.com:749
>
></code>
> <code>
><a name="1083663"> </a>
> default_domain = company.example.com
>
></code>
> <code>
><a name="1083642"> </a>
> }
>
></code>
> </td>
> </tr>
><tr>
><td valign="top">
><code>
><a name="1083668"> </a>
>[appdefaults]
>
></code>
> <code>
><a name="1083669"> </a>
> pam = {
>
></code>
> <code>
><a name="1083670"> </a>
> debug = true
>
></code>
> <code>
><a name="1083671"> </a>
> ticket_lifetime = 36000
>
></code>
> <code>
><a name="1083672"> </a>
> renew_lifetime = 36000
>
></code>
> <code>
><a name="1083673"> </a>
> forwardable = true
>
></code>
> <code>
><a name="1083674"> </a>
> krb4_convert = false
>
></code>
> <code>
><a name="1083644"> </a>
> }
>
></code>
> </td>
> </tr>
>
>
><tr><td><hr noshade size="1" /></td></tr>
></table>
> 
> 
>
>
><a name="1089264"> </a>
>
>
>
></blockquote>
>
>
>
>
>
> 
> 
>
><a style="text-decoration: none; color:#990000" href="index1.htm">
>Previous
></a>
>
>
>&nbsp;&nbsp;&nbsp;&nbsp;
>
>
>
><a style="text-decoration: none; color:#990000" href="contents.htm">
>Contents
></a>
>
>&nbsp;&nbsp;&nbsp;&nbsp;
>
>
>
><a style="text-decoration: none; color:#990000" href="ix.htm">
>Index
></a>
>
>&nbsp;&nbsp;&nbsp;&nbsp;
>
>
>
><a style="text-decoration: none; color:#990000" href="../index.htm">
>DocHome
></a>
>
>&nbsp;&nbsp;&nbsp;&nbsp;
>
>
>
><a style="text-decoration: none; color:#990000" href="dsstats.htm">
>Next
></a>
>
>&nbsp;&nbsp;&nbsp;&nbsp;
>
> 
><hr noshade="noshade" size="1" />
>&copy; 2001 Sun Microsystems, Inc. Portions copyright 1999, 2002-2004 Netscape Communications Corporation, 2005 Red Hat, Inc. All rights reserved. 
><a href="../copyright/copyright.html">Read the Full Copyright and Third-Party Acknowledgments</a>. 
> 
>Last Updated May 27, 2008
> 
>
>
>
></body>
></html>

<html>


<head>
<meta name="keywords" content="e-commerce, ecommerce, Red Hat, directory server, Directory Server, directory service, enterprise software, database, software, directory, Linux, Fedora, Red Hat software, linux, LDAP, open source" />
<meta name="description" content="Red Hat, Inc., produces the world renowned Directory Server, as well as cutting-edge open source software." />
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1" />
<meta name="templatebase" content="Authored in FrameMaker. Converted to HTML  in WebWorks Publisher. manual wdt 1.6" />
<meta name="LASTUPDATED" content="05/27/08 19:01:12" />
<title>Red Hat Directory Server        Administrator's Guide: Chapter&#32;11 Managing SSL and SASL</title>


<script type="text/JavaScript" src="sniffer.js">



</script>



</head>




<body text="#000000" link="#990000" vlink="#990000" alink="#333366" bgcolor="#FFFFFF">

<!--maincontent defines everything between the body tags -->
<!--start maincontent-->

<!--navigationcontent defines the top row of links and the banner -->
<!--start navigationcontent-->

<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>
<td><table border="0" cellspacing="0" cellpadding="0">
<tr>
<td valign="bottom" width="67">
<img src="logo64.png" height="64" width="64" border="0" alt="shadow man" />
</td>
<td valign="middle">
<span class="booktitle">Administrator's Guide</span><br />
<span class="product"><i>Red Hat Directory Server       </i></span>
</td>
</tr>
</table>
</td>
</tr>

<tr>
<td>
<hr size="1" noshade="noshade" />
<span class="navigation">
<a style="text-decoration: none; color:#990000" href="index1.htm">
Previous
</a>
</span>

&nbsp;&nbsp;&nbsp;&nbsp;


<span class="navigation">
<a style="text-decoration: none; color:#990000" href="contents.htm">
Contents
</a>
</span>
&nbsp;&nbsp;&nbsp;&nbsp;


<span class="navigation">
<a style="text-decoration: none; color:#990000" href="ix.htm">
Index
</a>
</span>
&nbsp;&nbsp;&nbsp;&nbsp;


<span class="navigation">
<a style="text-decoration: none; color:#990000" href="../index.htm">
DocHome
</a>
</span>
&nbsp;&nbsp;&nbsp;&nbsp;


<span class="navigation">
<a style="text-decoration: none; color:#990000" href="dsstats.htm">
Next
</a>
</span>
&nbsp;&nbsp;&nbsp;&nbsp;


</td>
</tr>
</table>

<!--end navigationcontent-->

<!--bookcontent defines the actual content of the file, sans headers and footers -->
<!--start bookcontent-->

<blockquote>
<br />
<p class="title">
<a name="1085020"> </a>
<a name=""> </a>
<font color="#666666">
Chapter&#32;11 
&nbsp;
</font>

<a name="996824"> </a>
<a name="Managing SSL and SASL"> </a>
Managing SSL and SASL
</p>
<br /><p class="text">
<a name="1038480"> </a>
To provide secure communications over the network, Red Hat Directory Server (Directory Server) includes the LDAPS communications protocol. LDAPS is the standard LDAP protocol, but it runs on top of Secure Sockets Layer (<a href="glossary.htm#1044686"  >SSL</a>). Directory Server also allows "spontaneous" secure connections over otherwise-insecure LDAP ports, using Start TLS (Transport Layer Security).
</p>
<p class="text">
<a name="1083212"> </a>
Additionally, Directory Server supports SASL authentication using the GSS-API mechanism, allowing Kerberos, rather than certificates, to authenticate sessions and encrypt data.
</p>
<p class="text">
<a name="1079245"> </a>
This chapter describes how to use SSL and SASL with your Directory Server in the following sections:
</p>
<ul>

<li>
<a href="ssl.htm#1041472"  >Introduction to SSL in the Directory Server</a> (<a href="ssl.htm#1041472"  >page 418</a>)
<a name="1038882"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
<a href="ssl.htm#1085091"  >Obtaining and Installing Server Certificates</a> (<a href="ssl.htm#1085091"  >page 420</a>)
<a name="1079229"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
<a href="ssl.htm#1089131"  >Command-Line Functions for Start TLS</a> (<a href="ssl.htm#1089131"  >page 419</a>)
<a name="1089118"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
<a href="ssl.htm#1089063"  >Using certutil</a> (<a href="ssl.htm#1089063"  >page 425</a>)
<a name="1087249"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
<a href="ssl.htm#1087250"  >Starting the Server with SSL Enabled</a> (<a href="ssl.htm#1087250"  >page 428</a>)
<a name="1038937"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
<a href="ssl.htm#1038525"  >Setting Security Preferences</a> (<a href="ssl.htm#1038525"  >page 433</a>)
<a name="1038886"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
<a href="ssl.htm#1053102"  >Using Certificate-Based Authentication</a> (<a href="ssl.htm#1053102"  >page 435</a>)
<a name="1038894"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
<a href="ssl.htm#1048777"  >Configuring LDAP Clients to Use SSL</a> (<a href="ssl.htm#1048777"  >page 437</a>)
<a name="1053589"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
<a href="ssl.htm#1083165"  >Introduction to SASL</a> (<a href="ssl.htm#1083165"  >page 439</a>)
<a name="1083158"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
</ul>
<p class="h1">
<a name="1041472"> </a>
<a name="Introduction to SSL in the Directory Server"> </a>
Introduction to SSL in the Directory Server
<hr size="1" noshade="noshade" />
</p>

<p class="text">
<a name="1079183"> </a>
The Directory Server supports SSL/TLS to secure communications between LDAP clients and the Directory Server, between Directory Servers that are bound by a replication agreement, or between a database link and a remote database. You can use SSL/TLS with simple authentication (bind DN and password) or with certificate-based authentication. 
</p>
<p class="text">
<a name="1079645"> </a>
Using SSL with simple authentication ensures confidentiality and data integrity. The benefits of using a certificate to authenticate to the Directory Server instead of a bind DN and password include:
</p>
<ul>

<li>
Improved efficiency &#151; When you are using applications that prompt you once for your certificate database password and then use that certificate for all subsequent bind or authentication operations, it is more efficient than continuously providing a bind DN and password.
<a name="1079679"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
Improved security &#151; The use of certificate-based authentication is more secure than non-certificate bind operations. This is because certificate-based authentication uses public-key cryptography. As a result, bind credentials cannot be intercepted across the network.
<a name="1079681"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
</ul>
<p class="text">
<a name="1080430"> </a>
The Directory Server is capable of simultaneous SSL and non-SSL communications. This means that you do not have to choose between SSL or non-SSL communications for your Directory Server; you can use both at the same time. You can also utilize the Start TLS extended operation to allow SSL/TLS secure communication over a regular (insecure) LDAP port.
</p>
<p class="text">
<a name="1087172"> </a>
Directory Server also supports SASL client authentication; see <a href="ssl.htm#1083165"  >"Introduction to SASL"</a>, for more information.
</p>
<p class="h2">
<a name="1082682"> </a>
<a name="Enabling SSL: Summary of Steps"> </a>
Enabling SSL: Summary of Steps
</p>


<p class="text">
<a name="1079643"> </a>
To configure your Directory Server to use LDAPS, follow these steps:
</p>
<ol type="1">

<li value="1">
Obtain and install a certificate for your Directory Server, and configure the Directory Server to trust the certification authority's (CA's) certificate.
<a name="1079187"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1079234"> </a>
For information, see <a href="ssl.htm#1085091"  >"Obtaining and Installing Server Certificates"</a>.
<br />&nbsp;</dt>  </dl>

<li value="2">
Turn on SSL in your directory.
<a name="1079196"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1079235"> </a>
For information, see <a href="ssl.htm#1087250"  >"Starting the Server with SSL Enabled"</a>.
<br />&nbsp;</dt>  </dl>

<li value="3">
Configure the Administration Server to connect to an SSL-enabled Directory Server.
<a name="1079200"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1079236"> </a>
For information, see <a href="../pdf/console60.pdf"><em>Managing Servers with Red Hat Console</em></a>.
<br />&nbsp;</dt>  </dl>

<li value="4">
Optionally, ensure that each user of the Directory Server obtains and installs a personal certificate for all clients that will authenticate with SSL.
<a name="1079706"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1079707"> </a>
For information, see <a href="ssl.htm#1048777"  >"Configuring LDAP Clients to Use SSL"</a>.
<br />&nbsp;</dt>  </dl>
</ol>
<p class="text">
<a name="1079208"> </a>
For a complete description of SSL, Internet security, and certificates, check the appendixes included in <a href="../pdf/console60.pdf"><em>Managing Servers with Red Hat Console</em></a>.
</p>
<p class="h1">
<a name="1089131"> </a>
<a name="Command-Line Functions for Start TLS"> </a>
Command-Line Functions for Start TLS
<hr size="1" noshade="noshade" />
</p>

<p class="text">
<a name="1089132"> </a>
You can specify that LDAP operations such as <code>ldapmodify</code>, <code>ldapsearch</code>, and <code>ldapdelete</code> use SSL/TLS when communicating with an SSL-enabled server or to use certificate authentication. Using the command-line options, you can also specify or enforce Start TLS, which which allows a secure connection to be enabled on a cleartext port after a session has been initiated.
</p>
<p class="text">
<a name="1089134"> </a>
In the following example, a network administrator enforces Start TLS for a search for Mike Connor's identification number:
</p>
<p class="text">
<a name="1089135"> </a>
<code>ldapsearch -p 389 -ZZZ -P </code><em>certificateDB</em>&nbsp;<code> -N </code><em>certificate_name</em>&nbsp;<code> -s base -b "uid=mconnors" "(attribute=govIdNumber)"</code>
</p>
<p class="text">
<a name="1089136"> </a>
where <code>-ZZZ</code> enforces Start TLS, <em>certificateDB</em> gives the filename and path to the certificate database, and <em>certificate_name</em> is the certificate.
</p>
<table border="0" cellpadding="0" width="90%">
<tr><td  colspan="2">
<hr size="1" />
</td></tr>
<tr>
<td valign="top"><p class="note">
<a name="1089139"> </a>
Note&nbsp;&nbsp;
</p>

</td>
<td valign="top"><p class="text">
<a name="1089141"> </a>
The <code>-ZZZ</code> command enforces the use of Start TLS, and the server must respond that a Start TLS command was successful. If you use the <code>-ZZZ</code> command and the server does not support Start TLS, the operation is aborted immediately.
</p>
</td>
  </tr>

<tr><td  colspan="2">
<hr size="1" />
</td></tr>
</table>

<br />
<br />

<p class="text">
<a name="1089146"> </a>
For information on the command-line options available, see the <a href="../cli/utilities.htm"><em>Red Hat Directory Server Configuration, Command, and File Reference</em></a>.
</p>
<p class="h2">
<a name="1089149"> </a>
<a name="Troubleshooting Start TLS"> </a>
Troubleshooting Start TLS
</p>


<p class="text">
<a name="1089150"> </a>
With the <code>-ZZ</code> option, the following errors could occur:
</p>
<ul>

<li>
If there is no certificate database, the operation fails. See <a href="ssl.htm#1085091"  >"Obtaining and Installing Server Certificates"</a>, for information on using certificates.
<a name="1089154"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
If the server does not support Start TLS, the connection proceeds in cleartext. To enforce the use of Start TLS, use the <code>-ZZZ</code> command option.
<a name="1089161"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
If the certificate database does not have the Certifying Authority (CA) certificate, the connection proceeds in cleartext. See <a href="ssl.htm#1085091"  >"Obtaining and Installing Server Certificates"</a>, for information on using certificates.
<a name="1089162"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
</ul>
<p class="text">
<a name="1089166"> </a>
With the <code>-ZZZ</code> option, the following errors could occur, causing the Start TLS operation to fail:
</p>
<ul>

<li>
If there is no certificate database. See <a href="ssl.htm#1085091"  >"Obtaining and Installing Server Certificates"</a>, for information on using certificates.
<a name="1089169"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
If the certificate database does not have the Certifying Authority (CA) certificate. See <a href="ssl.htm#1085091"  >"Obtaining and Installing Server Certificates"</a>, for information on using certificates.
<a name="1089171"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
The server does not support Start TLS as an extended operation.
<a name="1089175"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
</ul>
<p class="text">
<a name="1089176"> </a>
For SDK libraries used in client programs, if a session is already in TLS mode and Start TLS is requested, then the connection continues to be in secure mode but prints the error <code>"DSA is unwilling to perform"</code>.
</p>
<p class="h1">
<a name="1085091"> </a>
<a name="Obtaining and Installing Server Certificates"> </a>
Obtaining and Installing Server Certificates
<hr size="1" noshade="noshade" />
</p>

<p class="text">
<a name="1042334"> </a>
This section describes the process of creating a certificate database, obtaining and installing a certificate for use with your Directory Server, and configuring Directory Server to trust the certification authority's (CA) certificate.
</p>
<p class="text">
<a name="1079253"> </a>
This process is a necessary first step before you can turn on SSL in your directory. If you have already completed these tasks, see <a href="ssl.htm#1087250"  >"Starting the Server with SSL Enabled"</a>. 
</p>
<p class="text">
<a name="1079254"> </a>
Obtaining and installing certificates consists of the following steps:
</p>
<ul>

<li>
<a href="ssl.htm#1041474"  >Step 1: Generate a Certificate Request</a>
<a name="1044650"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
<a href="ssl.htm#1079314"  >Step 2: Send the Certificate Request</a> to the Certificate Authority
<a name="1044654"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
<a href="ssl.htm#1041552"  >Step 3: Install the Certificate</a>
<a name="1044658"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
<a href="ssl.htm#1043718"  >Step 4: Trust the Certificate Authority</a>
<a name="1044662"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
<a href="ssl.htm#1046393"  >Step 5: Confirm That Your New Certificates Are Installed</a>
<a name="1044666"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
</ul>
<p class="text">
<a name="1041473"> </a>
You will use the Certificate Request Wizard to generate a certificate request (Step 1) and send it to a Certificate Authority (Step 2). You then use the Certificate Install Wizard to install the certificate (Step 3) and to trust the Certificate Authority's certificate (Step 4).
</p>
<p class="text">
<a name="1080491"> </a>
These wizards automate the process of creating a certificate database and of installing the key-pair.
</p>
<p class="h2">
<a name="1041474"> </a>
<a name="Step 1: Generate a Certificate Request"> </a>
Step 1: Generate a Certificate Request
</p>


<p class="text">
<a name="1041476"> </a>
To generate a certificate request and send it to a CA:
</p>
<ol type="1">

<li value="1">
In the Directory Server Console, select the Tasks tab, and click Manage Certificates.
<a name="1041482"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1079261"> </a>
The Manage Certificates window is displayed.
<br />&nbsp;</dt>  </dl>

<li value="2">
Select the Server Certs tab, and click the Request button.
<a name="1079262"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1079263"> </a>
The Certificate Request Wizard is displayed. 
<br />&nbsp;</dt>  </dl>

<li value="3">
Click Next.
<a name="1079273"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="4">
Enter the following Requestor Information in the blank text fields, then click Next:
<a name="1079284"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <ul>

<li>
<b>Server Name </b>&#151; Enter the fully qualified hostname of the Directory Server as it is used in DNS lookups; for example, <code>dir.example.com</code>.
<a name="1041519"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
<li>
<b>Organization </b>&#151; Enter the legal name of your company or institution. Most CAs require you to verify this information with legal documents such as a copy of a business license.
<a name="1041523"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
<li>
<b>Organizational Unit </b>&#151; <em>Optional</em>. Enter a descriptive name for your organization within your company. 
<a name="1041525"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
<li>
<b>Locality </b>&#151; <em>Optional</em>. Enter your company's city name.
<a name="1041527"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
<li>
<b>State or Province </b>&#151; Enter the full name of your company's state or province (no abbreviations).
<a name="1041529"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
<li>
<b>Country </b>&#151; Select the two-character abbreviation for your country's name (ISO format). The country code for the United States is US. 
<a name="1041531"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>  </ul>

<li value="5">
Enter the password that will be used to protect the private key, and click Next.
<a name="1041533"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1079290"> </a>
The Next field is grayed out until you supply a password. When you click Next, the Request Submission dialog box is displayed.
<br />&nbsp;</dt>  </dl>

<li value="6">
Select Copy to Clipboard or Save to File to save the certificate request information that you must send to the Certificate Authority.
<a name="1079289"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="7">
Click Done to dismiss the Certificate Request Wizard.
<a name="1079308"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
</ol>
<p class="text">
<a name="1041534"> </a>
Once you have generated the request, you are ready to send it to the CA.
</p>
<p class="h2">
<a name="1079314"> </a>
<a name="Step 2: Send the Certificate Request"> </a>
Step 2: Send the Certificate Request
</p>


<p class="text">
<a name="1079316"> </a>
Follow these steps to send the certificate information to the CA:
</p>
<ol type="1">

<li value="1">
Use your email program to create a new email message.
<a name="1079317"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="2">
Copy the certificate request information from the clipboard or the saved file into the body of the message.
<a name="1041542"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1054006"> </a>
The content will look similar to the following example:
<br />&nbsp;</dt>     <dt> <a name="1079336"> </a>
<code>-----BEGIN NEW CERTIFICATE REQUEST-----<br />MIIBrjCCARcCAQAwbjELMAkGA1UEBhMCVXMxEzARBgNVBAgTCkNBTElGT1J<br />OSUExLDAqBgVBAoTI25ldHNjYXBlIGNvbW11bmljYXRpb25zIGNvcnBvcmF<br />0aW9uMRwwGgYDVQQDExNtZWxsb24ubmV0c2NhcGUuY29tMIGfMA0GCSqGSI<br />b3DQEBAQUAA4GNADCBiQKBgQCwAbskGh6SKYOgHy+UCSLnm3ok3X3u83Us7<br />ug0EfgSLR0f+K41eNqqRftGR83emqPLDOf0ZLTLjVGJaH4Jn4l1gG+JDf/n<br />/zMyahxtV7+mT8GOFFigFfuxaxMjr2j7IvELlxQ4IfZgWwqCm4qQecv3G+N<br />9YdbjveMVXW0v4XwIDAQABoAAwDQYK<br />-----END NEW CERTIFICATE REQUEST-----</code>
<br />&nbsp;</dt>  </dl>

<li value="3">
Send the email message to the CA.
<a name="1041549"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
</ol>
<p class="text">
<a name="1041550"> </a>
Once you have emailed your request, you must wait for the CA to respond with your certificate. Response time for requests varies. For example, if your CA is internal to your company, it may only take a day or two to respond to your request. If your selected CA is external to your company, it could take several weeks to respond to your request.
</p>
<p class="text">
<a name="1047992"> </a>
When the CA sends a response, be sure to save the information in a text file. You will need the data when you install the certificate.
</p>
<p class="text">
<a name="1047990"> </a>
You should also back up the certificate data in a safe location. If your system ever loses the certificate data, you can reinstall the certificate using your backup file.
</p>
<p class="text">
<a name="1047984"> </a>
Once you receive your certificate, you are ready to install it in your server's certificate database. 
</p>
<p class="h2">
<a name="1041552"> </a>
<a name="Step 3: Install the Certificate"> </a>
Step 3: Install the Certificate
</p>


<p class="text">
<a name="1041553"> </a>
To install a server certificate:
</p>
<ol type="1">

<li value="1">
In the Directory Server Console, select the Tasks tab, and click Manage Certificates.
<a name="1079353"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1079354"> </a>
The Manage Certificates window is displayed.
<br />&nbsp;</dt>  </dl>

<li value="2">
Select the Server Certs tab, and click Install.
<a name="1079355"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1079356"> </a>
The Certificate Install Wizard is displayed. 
<br />&nbsp;</dt>  </dl>

<li value="3">
Choose one of the following options for the certificate location, then click Next.
<a name="1046318"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <ul>

<li>
<b>In this file </b>&#151;<b> </b>Enter the absolute path to the certificate in this field.
<a name="1050391"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
<li>
<b>In the following encoded text block </b>&#151;<b> </b>Copy the text from the CA's email or from the text file you created, and paste it in this field. For example:
<a name="1043576"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>  </ul>
  <dl>
     <dt> <a name="1043535"> </a>
<code>-----BEGIN CERTIFICATE-----<br />MIICMjCCAZugAwIBAgICCEEwDQYJKoZIhvcNAQEFBQAwfDELMAkGA1UEBhMCVVMx<br />IzAhBgNVBAoTGlBhbG9va2FWaWxsZSBXaWRnZXRzLCBJbmMuMR0wGwYDVQQLExRX<br />aWRnZXQgTWFrZXJzICdSJyBVczEpMCcGA1UEAxMgVGVzdCBUZXN0IFRlc3QgVGVz<br />dCBUZXN0IFRlc3QgQ0EwHhcNOTgwMzEyMDIzMzU3WhcNOTgwMzI2MDIzMzU3WjBP<br />MQswCQYDVQQGEwJVUzEoMCYGA1UEChMfTmV0c2NhcGUgRGlyZWN0b3J5IFB1Ymxp<br />Y2F0aW9uczEWMBQGA1UEAxMNZHVgh49dq2itLmNvbTBaMA0GCSqGSIb3<br />-----END CERTIFICATE-----</code>
<br />&nbsp;</dt>  </dl>

<li value="4">
Check that the certificate information displayed is correct, and click Next.
<a name="1044365"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="5">
Specify a name for the certificate, and click Next.
<a name="1079538"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="6">
Verify the certificate by providing the password that protects the private key.
<a name="1083263"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1083264"> </a>
This password is the same as the one you provided in "<a href="ssl.htm#1041474"  >Step 1: Generate a Certificate Request</a>," on <a href="ssl.htm#1079353"  >page 423</a>.
<br />&nbsp;</dt>  </dl>
</ol>
<p class="text">
<a name="1083268"> </a>
Now that you have installed your certificate, you need to configure your server to trust the Certificate Authority from which you obtained the server's certificate.
</p>
<p class="h2">
<a name="1043718"> </a>
<a name="Step 4: Trust the Certificate Authority"> </a>
Step 4: Trust the Certificate Authority
</p>


<p class="text">
<a name="1042273"> </a>
Configuring your Directory Server to trust the certificate authority consists of obtaining your CA's certificate and installing it into your server's certificate database. This process differs depending on the certificate authority you use. Some commercial CAs provide a web site that allows you to automatically download the certificate. Others will email it to you upon request.
</p>
<p class="text">
<a name="1054205"> </a>
Once you have the CA certificate, you can use the Certificate Install Wizard to configure the Directory Server to trust the Certificate Authority.
</p>
<ol type="1">

<li value="1">
In the Directory Server Console, select the Tasks tab, and click Manage Certificates.
<a name="1079564"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1079565"> </a>
The Manage Certificates window is displayed.
<br />&nbsp;</dt>  </dl>

<li value="2">
Go to the CA Certs tab, and click Install.
<a name="1079568"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1079572"> </a>
The Certificate Install Wizard is displayed.
<br />&nbsp;</dt>  </dl>

<li value="3">
If you saved the CA's certificate to a file, enter the path in the field provided. If you received the CA's certificate via email, copy and paste the certificate, including the headers, into the text field provided. Click Next.
<a name="1044549"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="4">
Check that the certificate information that is displayed is correct, and click Next.
<a name="1079595"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="5">
Specify a name for the certificate, and click Next.
<a name="1079596"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="6">
Select the purpose of trusting this Certificate Authority (you can select both):
<a name="1079606"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <ul>

<li>
<b>Accepting connections from clients (Client Authentication) </b>&#151; The server checks that the client's certificate has been issued by a trusted Certificate Authority.
<a name="1079609"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
<li>
<b>Accepting connections to other servers (Server Authentication) </b>&#151; This server checks that the directory to which it is making a connection (for replication updates, for example) has a certificate that has been issued by a trusted Certificate Authority.
<a name="1079610"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>  </ul>

<li value="7">
Click Done to dismiss the wizard.
<a name="1050583"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
</ol>
<p class="text">
<a name="1053860"> </a>
Once you have installed your certificate and trusted the CA's certificate, you are ready to activate SSL. However, you should first make sure that the certificates have been installed correctly.
</p>
<p class="h2">
<a name="1046393"> </a>
<a name="Step 5: Confirm That Your New Certificates Are Installed"> </a>
Step 5: Confirm That Your New Certificates Are Installed
</p>


<ol type="1">

<li value="1">
In the Directory Server Console, select the Tasks tab, and click Manage Certificates.
<a name="1079369"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1079370"> </a>
The Manage Certificates window is displayed.
<br />&nbsp;</dt>  </dl>

<li value="2">
Select the Server Certs tab.
<a name="1079373"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1054019"> </a>
A list of all the installed certificates for the server is displayed.
<br />&nbsp;</dt>  </dl>

<li value="3">
Scroll through the list. You should find the certificates you installed.
<a name="1042292"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1079376"> </a>
Your server is now ready for SSL activation.
<br />&nbsp;</dt><table border="0" cellpadding="0" width="90%">
<tr><td  colspan="2">
<hr size="1" />
</td></tr>
<tr>
<td valign="top"><p class="note">
<a name="1085779"> </a>
Note&nbsp;&nbsp;
</p>

</td>
<td valign="top"><p class="text">
<a name="1085781"> </a>
When you renew a certificate using the Certificate Wizard, the text on the introduction screen (step 1) doesn't clearly indicate that the process is renewal and not requesting a new certificate. Also, the requestor information (step 2) doesn't get filled automatically.
</p>
</td>
  </tr>

<tr><td  colspan="2">
<hr size="1" />
</td></tr>
</table>

<br />
<br />

  </dl>
</ol>
<p class="h1">
<a name="1089063"> </a>
<a name="Using certutil"> </a>
Using certutil
<hr size="1" noshade="noshade" />
</p>

<p class="text">
<a name="1087251"> </a>
The Directory Server has a command-line tool, <code>certutil</code>, which locally creates self-signed CA and client certificates, certificate databases, and keys. The default location for the Directory Server <code>certutil</code> tool is <em>serverRoot</em>/shared/bin/.
</p>
<p class="text">
<a name="1089269"> </a>
<code>certutil</code> can also be downloaded from <a href="ftp://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/"><code>ftp://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/</code></a>.
</p>
<p class="text">
<a name="1088112"> </a>
The following steps outline how to make the databases, key, CA certificate, and server/client certificate and convert the certificates into <code>pkcs12</code> format.
</p>
<ol type="1">

<li value="1">
Open the directory where the Directory Server certificate databases are stored.
<a name="1089299"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1089301"> </a>
<code>cd </code>serverRoot/alias
<br />&nbsp;</dt>  </dl>

<li value="2">
Make a backup copy of all of the filed in the directory as a precaution. If something goes awry with while managing certificates, the databases can then be restored. For example:
<a name="1089305"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1089307"> </a>
<code>tar -cf /tmp/db-backup.tar *</code>
<br />&nbsp;</dt>  </dl>

<li value="3">
Create a password file for the security token password.
<a name="1089311"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1089313"> </a>
<code>vi /tmp/pwdfile</code>
<br />&nbsp;</dt>     <dt> <a name="1089315"> </a>
<code>secretpw</code>
<br />&nbsp;</dt>     <dt> <a name="1089317"> </a>
This password locks the server's private key in the key database and is used when the keys and certificates are first created. The password in this file is also the default password to encrypt PK12 files used by <code>pk12util</code>. Because this password is stored in plaintext, the password file should be owned by the user as which Directory Server runs, by default <code>nobody</code>, and it must be set as read-only for the Directory Server user and allow no access to anyone else (mode <code>0400</code>). It's a good idea to have a secure backup of this file.
<br />&nbsp;</dt>  </dl>

<li value="4">
Set the environment variable for the shell to include the <code>certutil</code> directory path. For example:
<a name="1089320"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1089322"> </a>
<code>export PATH=</code>serverRoot/shared/bin/:$PATH
<br />&nbsp;</dt>     <dt> <a name="1089324"> </a>
The command varies depending on the shell.
<br />&nbsp;</dt>  </dl>

<li value="5">
Create the key and certificate databases databases.
<a name="1089327"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1089329"> </a>
<code>certutil -N -d . -f /tmp/pwdfile -P slapd-</code>instance_name-
<br />&nbsp;</dt>  </dl>

<li value="6">
Generate the self-signed CA certificate. <code>certutil</code> creates the required key pairs and the certificate. This certificate is used to generate the other server certificates and can be exported for use with other servers and clients.
<a name="1089333"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1089335"> </a>
<code>certutil -S -n "CA certificate" -s "cn=My Org CA cert, dc=example,dc=com" -x -t "CT,," -m 1000 -v 120 -d . -k rsa -g 1024 -f /tmp/pwdfile -P slapd-</code>instance_name-
<br />&nbsp;</dt>  </dl>

<li value="7">
Generate the Directory Server client certificate.
<a name="1089340"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1089342"> </a>
<code>certutil -S -n "Server-Cert" -s "cn=</code>FQDN,cn=Directory Server" -c "CA certificate" -t "u,u,u" -m 1001 -v 120 -d . -k rsa -g 1024 -f /tmp/pwdfile -P slapd-instance_name-
<br />&nbsp;</dt>     <dt> <a name="1089345"> </a>
The value of the <code>-s</code> argument is very important. The leftmost RDN must be <code>cn=</code>FQDN (where <em>FQDN</em> is the fully-qualified host and domain name of the Directory Server). For example, to issue a certificate for a server with the name <code>ldap.example.com</code>, specifiy at least <code>-s "cn=ldap.example.com"</code>; it is beneficial to have a more descriptive name to help with server identification, such as <code>"cn=ldap.example.com, ou=DS1"</code>. The <em>FQDN</em> must be available for DNS and reverse DNS lookups to Directory Server clients because certificate validation may fail if the clients cannot properly resolve the <em>FQDN</em>, and some clients refuse to connect if a server certificate does not have its <em>FQDN</em> in the subject. Additionally, using the format <code>cn=</code>hostname.domain is essential for Directory Server clients to protect themselves from man in the middle attacks.
<br />&nbsp;</dt>     <dt> <a name="1089347"> </a>
To provide a subjectAltName, as well as the nickname, use the <code>-8</code> argument in addition to the <code>-s</code> argument.
<br />&nbsp;</dt>     <dt> <a name="1089349"> </a>
To use the Directory Server behind a DNS round robin or any other scheme which aliases a single server certificate to multiple hostnames, see the TLS/SSL information about server name wildcards or subjectAltName.
<br />&nbsp;</dt>     <dt> <a name="1089351"> </a>
Server certificates for other servers are created using a similar command as for the Directory Server certificate. Make sure that every <code>-n</code> option (nickname) and <code>-m</code> option (serial number) is unique for every certificate, and make sure that the <code>-s</code> option gives the correct <em>FQDN</em> for the server.
<br />&nbsp;</dt>     <dt> <a name="1089470"> </a>
<b><table border="0" cellpadding="0" width="90%">
<tr><td  colspan="2">
<hr size="1" />
</td></tr>
<tr>
<td valign="top"><p class="note">
<a name="1089467"> </a>
Note&nbsp;&nbsp;
</p>

</td>
<td valign="top"><p class="text">
<a name="1089469"> </a>
Keep careful track on the numbers set with the -m option. The -m option sets the unique identifier for the server certificate, and a CA cannot issue two certificates with the same ID. Keep a log of issued serial numbers so that no number is ever duplicated.
</p>
</td>
  </tr>

<tr><td  colspan="2">
<hr size="1" />
</td></tr>
</table>
</b>
<br />&nbsp;</dt>  </dl>

<li value="8">
Export the CA certificate for use with other servers and clients. A client usually requires the CA certificate to validate the server certificate in an TLS/SSL connection. Use certutil to export the CA certificate in ASCII/PEM format:
<a name="1089357"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1089359"> </a>
<code>certutil -d . -L -n "CA certificate" -a &gt; cacert.asc -P slapd-</code>instance_name-
<br />&nbsp;</dt>     <dt> <a name="1089361"> </a>
The way that the CA certificate is imported is different for every client. For example, certutil can import a CA certificate into another Directory Server certificiate database:
<br />&nbsp;</dt>     <dt> <a name="1089363"> </a>
<code>cd </code>other-serverRoot/alias
<br />&nbsp;</dt>     <dt> <a name="1089364"> </a>
<code>certutil -A -d . -n "CA certificate" -t "CT,," -a -i cacert.asc -P slapd-</code>instance_name-
<br />&nbsp;</dt>  </dl>

<li value="9">
Use pk12util to export other server certificates and keys created with certutil so that they can be used on a remote server.
<a name="1089368"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1089370"> </a>
<code>pk12util -d . -o ldap1.p12 -n Server-Cert1 -w /tmp/pwdfile -k /tmp/pwdfile -P slapd-</code>instance_name-
<br />&nbsp;</dt>     <dt> <a name="1089372"> </a>
The <code>-w</code> argument is the password used to encrypt the <code>.p12</code> file for transport. The <code>-k</code> argument specifies the password for the key database containing the server certificate being exported to <code>.p12</code>.
<br />&nbsp;</dt>  </dl>

<li value="10">
If the Directory Server will run with TLS/SSL enabled, then create a password file (<code>pin.txt</code>) for the server to use so it will not prompt you for a password every time it restarts. Creating the password file is described in <a href="ssl.htm#1087372"  >"Creating a Password File"</a>.
<a name="1089295"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
</ol>
<p class="text">
<a name="1087756"> </a>
The certificates created by <code>certutil</code> are automatically available in the Encryption tab of the Console; there is not need to import them.
</p>
<p class="h1">
<a name="1087250"> </a>
<a name="Starting the Server with SSL Enabled"> </a>
Starting the Server with SSL Enabled
<hr size="1" noshade="noshade" />
</p>

<p class="text">
<a name="1080534"> </a>
Most of the time, you want your server to run with SSL enabled. If you temporarily disable SSL, make sure you re-enable it before processing transactions that require confidentiality, authentication, or data integrity.
</p>
<p class="text">
<a name="1088984"> </a>
There are two ways to use SSL:
</p>
<ul>

<li>
Enabling SSL communications to the Directory Server only
<a name="1088985"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
Requiring SSL among the Directory Server, Admin Server, Console, and other client applications
<a name="1088988"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
</ul>
<p class="text">
<a name="1088998"> </a>
For routine use, you only need to enable SSL to the Directory Server.
</p>
<p class="text">
<a name="1080536"> </a>
Before you can activate SSL, you must create a certificate database, obtain and install a server certificate, and trust the CA's certificate, as described in <a href="ssl.htm#1085091"  >"Obtaining and Installing Server Certificates"</a>.
</p>
<table border="0" cellpadding="0" width="90%">
<tr><td  colspan="2">
<hr size="1" />
</td></tr>
<tr>
<td valign="top"><p class="note">
<a name="1082196"> </a>
Note&nbsp;&nbsp;
</p>

</td>
<td valign="top"><p class="text">
<a name="1082198"> </a>
On SSL-enabled servers, be sure to check the file permissions on certificate-database files, key-databases files, and PIN files to protect the sensitive information they contain. Because the server does not enforce read-only permissions on these files, check the file modes to protect the sensitive information contained in these files.
</p>
</td>
  </tr>

<tr><td  colspan="2">
<hr size="1" />
</td></tr>
</table>

<br />
<br />

<p class="h2">
<a name="1087338"> </a>
<a name="Enabling SSL Only in the Directory Server:"> </a>
Enabling SSL Only in the Directory Server:
</p>


<ol type="1">

<li value="1">
Obtain and install CA and server certificates.
<a name="1087398"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="2">
Set the secure port you want the server to use for SSL communications. 
<a name="1087399"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1087658"> </a>
The encrypted port number that you specify must not be the same port number you use for normal LDAP communications. By default, the standard port number is <code>389</code>, and the secure port is <code>636</code>. if you did not install the server as <code>root</code>, change to a port number above <code>1024</code>:
<br />&nbsp;</dt>  </dl>
  <ol type="a">

<li>
Change the secure port number in the Configuration&gt;Settings tab of the Directory Server Console. Save.
<a name="1087694"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
<li>
Restart the Directory Server. It will restart still with the regular port.
<a name="1087687"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>  </ol>

<li value="3">
In the Directory Server Console, select the Configuration tab, and then select the topmost entry in the navigation tree in the left pane. Select the Encryption tab in the right pane.
<a name="1087691"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="4">
Select the "Enable SSL for this Server" checkbox.
<a name="1087406"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="5">
Check the "Use this Cipher Family" checkbox.
<a name="1087407"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="6">
Select the certificate that you want to use from the drop-down menu.
<a name="1087408"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="7">
Click Cipher Settings.
<a name="1087409"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1087410"> </a>
The Cipher Preference dialog box is displayed. By default, all ciphers are selected.
<br />&nbsp;</dt>  </dl>

<li value="8">
Set your preferences for client authentication. 
<a name="1087456"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <ul>

<li>
<b>Do not allow client authentication </b>&#151; With this option, the server will ignore the client's certificate. This does not mean that the bind will fail.
<a name="1087457"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
<li>
<b>Allow client authentication </b>&#151; This is the default setting. With this option, authentication is performed on the client's request. For more information about certificate-based authentication, see <a href="ssl.htm#1053102"  >"Using Certificate-Based Authentication"</a>.
<a name="1087458"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
<li>
<b>Require client authentication </b>&#151; With this option, the server requests authentication from the client.
<a name="1087462"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>  </ul>
  <dl>
     <dt> <a name="1087628"> </a>
If you are only enabling SSL in the Directory Server, do not select "Require client authentication" checkbox.
<br />&nbsp;</dt><table border="0" cellpadding="0" width="90%">
<tr><td  colspan="2">
<hr size="1" />
</td></tr>
<tr>
<td valign="top"><p class="note">
<a name="1087465"> </a>
Note&nbsp;&nbsp;
</p>

</td>
<td valign="top"><p class="text">
<a name="1087467"> </a>
If you are using certificate-based authentication with replication, then you must configure the consumer server either to allow or to require client authentication.
</p>
</td>
  </tr>

<tr><td  colspan="2">
<hr size="1" />
</td></tr>
</table>

<br />
<br />

  </dl>

<li value="9">
You can further configure the server to verify the authenticity of requests by selecting the "Check hostname against name in certificate for outbound SSL connections" option. The server does this verification by matching the hostname against the value assigned to the common name (<code>cn</code>) attribute of the subject name in the <a href="glossary.htm#1044149"  >certificate</a> being presented for authentication.
<a name="1087482"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1087486"> </a>
By default, this feature is disabled. If it's enabled and if the hostname does not match the <code>cn</code> attribute of the certificate, appropriate error and audit messages are logged. For example, in a replicated environment, messages similar to these are logged in the supplier server's log files if it finds that the peer server's hostname doesn't match the name specified in its certificate:
<br />&nbsp;</dt>     <dt> <a name="1087491"> </a>
<code>[DATE] - SSL alert: ldap_sasl_bind("",LDAP_SASL_EXTERNAL) 81 (Netscape runtime error -12276 - Unable to communicate securely with peer: requested domain name does not match the server's certificate.)</code>
<br />&nbsp;</dt>     <dt> <a name="1087492"> </a>
<code>[DATE] NSMMReplicationPlugin - agmt="cn=to ultra60 client auth" (ultra60:1924): Replication bind with SSL client authentication failed: LDAP error 81 (Can't contact LDAP server)</code>
<br />&nbsp;</dt>     <dt> <a name="1087496"> </a>
It is recommended that you enable this option to protect Directory Server's outbound SSL connections against a Man in the Middle (MITM) attack.
<br />&nbsp;</dt>  </dl>

<li value="10">
Click Save.
<a name="1087497"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="11">
Restart the Directory Server. You must restart from the command-line.
<a name="1087501"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
</ol>
<p class="h2">
<a name="1087514"> </a>
<a name="Enabling SSL in the Directory Server, Admin Server, and Console"> </a>
Enabling SSL in the Directory Server, Admin Server, and Console
</p>


<ol type="1">

<li value="1">
Obtain server certificates and CA certs, and install them on the Directory Server. 
<a name="1087451"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="2">
Obtain and install server and CA certificates on the Administration Server.
<a name="1087270"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1087271"> </a>
It is important that the Administration Server and Directory Server have their CA certificates in common so that they trust the other's certificates.
<br />&nbsp;</dt>  </dl>

<li value="3">
If you have not installed the servers as <code>root</code>, it is necessary to change the secure port setting from the default <code>636</code> to a number above <code>1024</code>. 
<a name="1087272"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <ol type="a">

<li>
Change the secure port number in the Configuration&gt;Settings tab of the Directory Server Console. Save.
<a name="1087273"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
<li>
Restart the Directory Server. It will restart still with the regular port.
<a name="1087274"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>  </ol>

<li value="4">
In the Configuration tab of the Directory Server Console, highlight the server name at the top of the table, and select the Encryption tab.
<a name="1087275"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="5">
Select the "Enable SSL" checkbox.
<a name="1087549"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="6">
Check the "Use this Cipher Family" checkbox.
<a name="1087702"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="7">
Select the certificate that you want to use from the drop-down menu.
<a name="1087703"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="8">
Click Cipher Settings.
<a name="1087704"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1087705"> </a>
The Cipher Preference dialog box is displayed. By default, all ciphers are selected.
<br />&nbsp;</dt>  </dl>

<li value="9">
Set your preferences for client authentication.
<a name="1087578"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <ul>

<li>
<b>Do not allow client authentication </b>&#151; With this option, the server will ignore the client's certificate. This does not mean that the bind will fail.
<a name="1087579"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
<li>
<b>Allow client authentication </b>&#151; This is the default setting. With this option, authentication is performed on the client's request. For more information about certificate-based authentication, see <a href="ssl.htm#1053102"  >"Using Certificate-Based Authentication"</a>.
<a name="1087580"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
<li>
<b>Require client authentication </b>&#151; With this option, the server requests authentication from the client.
<a name="1087584"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li><table border="0" cellpadding="0" width="90%">
<tr><td  colspan="2">
<hr size="1" />
</td></tr>
<tr>
<td valign="top"><p class="note">
<a name="1087587"> </a>
Note&nbsp;&nbsp;
</p>

</td>
<td valign="top"><p class="text">
<a name="1087589"> </a>
If you are using certificate-based authentication with replication, then you must configure the consumer server either to allow or to require client authentication.
</p>
</td>
  </tr>

<tr><td  colspan="2">
<hr size="1" />
</td></tr>
</table>

<br />
<br />

  </ul>

<li value="10">
You can further configure the server to verify the authenticity of requests by selecting the "Check hostname against name in certificate for outbound SSL connections" option. The server does this verification by matching the hostname against the value assigned to the common name (<code>cn</code>) attribute of the subject name in the <a href="glossary.htm#1044149"  >certificate</a> being presented for authentication.
<a name="1087640"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1087644"> </a>
By default, this feature is disabled. If it's enabled and if the hostname does not match the <code>cn</code> attribute of the certificate, appropriate error and audit messages are logged. For example, in a replicated environment, messages similar to these are logged in the supplier server's log files if it finds that the peer server's hostname doesn't match the name specified in its certificate:
<br />&nbsp;</dt>     <dt> <a name="1087645"> </a>
<code>[DATE] - SSL alert: ldap_sasl_bind("",LDAP_SASL_EXTERNAL) 81 (Netscape runtime error -12276 - Unable to communicate securely with peer: requested domain name does not match the server's certificate.)</code>
<br />&nbsp;</dt>     <dt> <a name="1087646"> </a>
<code>[DATE] NSMMReplicationPlugin - agmt="cn=to ultra60 client auth" (ultra60:1924): Replication bind with SSL client authentication failed: LDAP error 81 (Can't contact LDAP server)</code>
<br />&nbsp;</dt>     <dt> <a name="1087650"> </a>
It is recommended that you enable this option to protect Directory Server's outbound SSL connections against a Man in the Middle (MITM) attack.
<br />&nbsp;</dt>  </dl>

<li value="11">
Check the "Use SSL in the Console" box. Hit "Save."
<a name="1087638"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="12">
In the Administration Server Console, select the Configuration tab. Select the Encryption tab, check the "Enable SSL" checkbox, and fill in the appropriate certificate information.
<a name="1087281"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="13">
In the Configuration DS tab, change the port number to the new Directory Server secure port information. See <a href="intro.htm#1070843"  >"Changing Directory Server Port Numbers"</a>, for more information. Do this even if you are using the default port of <code>636</code>. 
<a name="1087282"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1089020"> </a>
Check the "Secure Connection" checkbox. 
<br />&nbsp;</dt>  </dl>

<li value="14">
In the User DS tab, select the "Set User Directory" radio button, and fill in the new Directory Server secure port information, the LDAP URL, and the user database information. 
<a name="1087286"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1089021"> </a>
Check the "Secure Connection" checkbox.
<br />&nbsp;</dt>  </dl>

<li value="15">
Save the new SSL settings, Configuration DS, and User DS information in the Administration Server.
<a name="1087287"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="16">
Restart the Admin Server. You must start the server from the command-line.
<a name="1087291"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="17">
Restart the Directory Server. You must start the server from the command-line.
<a name="1087292"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
</ol>
<p class="text">
<a name="1087293"> </a>
When you restart the Console, be certain that the address reads <code>https</code>; otherwise, the operation will time out, unable to find the Admin Server since it is running on a secure connection. When you successfully connect, a dialog box will appear, asking you to accept the certificate. Click OK to accept the certificate (you may choose whether to accept it only for that session or for always).
</p>
<p class="h2">
<a name="1087372"> </a>
<a name="Creating a Password File"> </a>
Creating a Password File
</p>


<p class="text">
<a name="1087374"> </a>
You can create a password file to store your certificate password. By placing your certificate database password in a file, you can start your server from the Console and also allow your server to restart automatically when running unattended.
</p>
<table border="0" cellpadding="0" width="90%">
<tr><td  colspan="2">
<hr size="1" />
</td></tr>
<tr>
<td valign="top"><p class="caution">
<a name="1087377"> </a>
Caution&nbsp;&nbsp;
</p>
</td>
<td valign="top"><p class="text">
<a name="1087379"> </a>
This password is stored in cleartext within the password file, so its usage represents a significant security risk. Do not use a password file if your server is running in an unsecured environment.
</p>
</td>
  </tr>

<tr><td  colspan="2">
<hr size="1" />
</td></tr>
</table>

<br />
<br />

<p class="text">
<a name="1087381"> </a>
The password file must be placed in the following location:
</p>
<p class="text">
<a name="1087382"> </a>
<em>serverRoot</em>&nbsp;<code>/alias/slapd-</code><em>serverID</em>&nbsp;<code>-pin.txt</code>
</p>
<p class="text">
<a name="1089038"> </a>
where <em>serverID</em> is the identifier you specified for the server when you installed it.
</p>
<p class="text">
<a name="1089039"> </a>
You need to include the token password in the file: 
</p>
<dl><p class="code">
<a name="1089040"></a>
mypassword

</p></dl><p class="text">
<a name="1087386"> </a>
When the server restarts, it will use this value as the token PIN.
</p>
<p class="h1">
<a name="1038525"> </a>
<a name="Setting Security Preferences"> </a>
Setting Security Preferences
<hr size="1" noshade="noshade" />
</p>

<p class="text">
<a name="1038529"> </a>
You can choose the type of ciphers you want to use for SSL communications. A <em>cipher</em> is the algorithm used in encryption. Some ciphers are more secure, or <em>stronger,</em> than others. Generally speaking, the more bits a cipher uses during encryption, the more difficult it is to decrypt the key. For a more complete discussion of algorithms and their strength, see <a href="../pdf/console60.pdf"><em>Managing Servers with Red Hat Console</em></a>.
</p>
<p class="text">
<a name="1038533"> </a>
When a client initiates an SSL connection with a server, the client tells the server what ciphers it prefers to use to encrypt information. In any two-way encryption process, both parties must use the same ciphers. There are a number of ciphers available. Your server needs to be able to use the ciphers that will be used by client applications connecting to the server.
</p>
<p class="text">
<a name="1038536"> </a>
Directory Server provides the following SSL 3.0 ciphers:
</p>
<ul>

<li>
RC4 cipher with 40-bit encryption and MD5 message authentication.
<a name="1038540"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
RC2 cipher with 40-bit encryption and MD5 message authentication.
<a name="1038542"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
No encryption, only MD5 message authentication.
<a name="1079481"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
DES with 56-bit encryption and SHA message authentication.
<a name="1040055"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
RC4 cipher with 128-bit encryption and MD5 message authentication.
<a name="1079466"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
Triple DES with 168-bit encryption and SHA message authentication.
<a name="1038546"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
FIPS DES with 56-bit encryption and SHA message authentication. This cipher meets the FIPS 140-1 U.S. government standard for implementations of cryptographic modules.
<a name="1079475"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
FIPS Triple DES with 168-bit encryption and SHA message authentication. This cipher meets the FIPS 140-1 US government standard for implementations of cryptographic modules.
<a name="1040124"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
</ul>
<p class="text">
<a name="1052945"> </a>
To select the ciphers you want the server to use:
</p>
<ol type="1">

<li value="1">
Make sure SSL is enabled for your server.
<a name="1083310"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1083314"> </a>
For information, see <a href="ssl.htm#1087250"  >"Starting the Server with SSL Enabled"</a>.
<br />&nbsp;</dt>  </dl>

<li value="2">
In the Directory Server Console, select the Configuration tab, and then select the topmost entry in the navigation tree in the left pane.
<a name="1083318"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="3">
Select the Encryption tab in the right pane.
<a name="1038569"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1079491"> </a>
This displays the current server encryption settings.
<br />&nbsp;</dt>  </dl>

<li value="4">
Click Cipher Settings.
<a name="1079493"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1079494"> </a>
The Cipher Preference dialog box is displayed.
<br />&nbsp;</dt>  </dl>

<li value="5">
In the Cipher Preference dialog box, specify which ciphers you want your server to use by selecting them from the list, and click OK.
<a name="1038571"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1079497"> </a>
Unless you have a security reason not to use a specific cipher, you should select all of the ciphers, except for <code>none,MD5</code>. 
<br />&nbsp;</dt>  </dl>

<li value="6">
In the Encryption tab, click Save.
<a name="1077547"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
<table border="0" cellpadding="0" width="90%">
<tr><td  colspan="2">
<hr size="1" />
</td></tr>
<tr>
<td valign="top"><p class="caution">
<a name="1077555"> </a>
Caution&nbsp;&nbsp;
</p>
</td>
<td valign="top"><p class="text">
<a name="1077562"> </a>
Avoid selecting the <code>none,MD5</code> cipher because the server will use this option if no other ciphers are available on the client. It is not secure because encryption doesn't occur.
</p>
</td>
  </tr>

<tr><td  colspan="2">
<hr size="1" />
</td></tr>
</table>

<br />
<br />

</ol>
<p class="text">
<a name="1053148"> </a>
In order to continue using the Red Hat Console with SSL, you must select at least one of the following ciphers:
</p>
<ul>

<li>
RC4 cipher with 40-bit encryption and MD5 message authentication.
<a name="1053073"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
No encryption, only MD5 message authentication.
<a name="1053091"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
DES with 56-bit encryption and SHA message authentication.
<a name="1053130"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
RC4 cipher with 128-bit encryption and MD5 message authentication.
<a name="1053135"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
Triple DES with 168-bit encryption and SHA message authentication.
<a name="1053141"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
</ul>
<p class="h1">
<a name="1053102"> </a>
<a name="Using Certificate-Based Authentication"> </a>
Using Certificate-Based Authentication
<hr size="1" noshade="noshade" />
</p>

<p class="text">
<a name="1047830"> </a>
Directory Server allows you to use certificate-based authentication for the command-line tools (which are LDAP clients) and for replication communications. Certificate-based authentication can occur between:
</p>
<ul>

<li>
An LDAP client connecting to the Directory Server.
<a name="1079732"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
A Directory Server connecting to another Directory Server (<a href="glossary.htm#1044601"  >replication</a> or <a href="glossary.htm#1044157"  >chaining</a>).
<a name="1079733"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
<table border="0" cellpadding="0" width="90%">
<tr><td  colspan="2">
<hr size="1" />
</td></tr>
<tr>
<td valign="top"><p class="note">
<a name="1082141"> </a>
Note&nbsp;&nbsp;
</p>

</td>
<td valign="top"><p class="text">
<a name="1082143"> </a>
When specifying the key and certificate database filenames, you may use absolute or relative paths. If using relative paths, ensure that they are relative to the server root (for example, <code>alias/slapd-phonebook-cert8.db</code> and <code>alias/slapd-phonebook-key3.db</code>). 
</p>
<p class="text">
<a name="1082211"> </a>
The name of the certificate database has been changed from <code>cert7.db</code> to <code>cert8.db</code>. Directory Server automatically converts the <code>cert7.db</code> to <code>cert8.db</code> and uses the new file. However, the <code>dse.ldif</code> file may not show the new database name. For example, you may still see this entry: 
</p>
<p class="text">
<a name="1082249"> </a>
<code>nsCertfile: alias/slapd-testDir-cert7.db</code>
</p>
<p class="text">
<a name="1082213"> </a>
If you want the database filename change reflected in the <code>dse.ldif</code> file, manually edit the filename in the <code>dse.ldif</code> file.
</p>
</td>
  </tr>

<tr><td  colspan="2">
<hr size="1" />
</td></tr>
</table>

<br />
<br />

</ul>
<p class="h2">
<a name="1080310"> </a>
<a name="Setting up Certificate-Based Authentication"> </a>
Setting up Certificate-Based Authentication
</p>


<p class="text">
<a name="1080345"> </a>
To set up certificate-based authentication, you must:
</p>
<ol type="1">

<li value="1">
Create a certificate database for the client and the server or for both servers involved in replication.
<a name="1038642"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1079758"> </a>
In the Directory Server, the certificate database creation automatically takes place when you install a certificate. For information on creating a certificate database for a client, see <a href="ssl.htm#1048777"  >"Configuring LDAP Clients to Use SSL"</a>.
<br />&nbsp;</dt>  </dl>

<li value="2">
Obtain and install a certificate on both the client and the server or on both servers involved in replication.
<a name="1054091"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="3">
Enable SSL on the server or on both servers involved in replication.
<a name="1038646"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1079627"> </a>
For information on enabling SSL, refer to <a href="ssl.htm#1087250"  >"Starting the Server with SSL Enabled"</a>.
<br />&nbsp;</dt><table border="0" cellpadding="0" width="90%">
<tr><td  colspan="2">
<hr size="1" />
</td></tr>
<tr>
<td valign="top"><p class="note">
<a name="1080319"> </a>
Note&nbsp;&nbsp;
</p>

</td>
<td valign="top"><p class="text">
<a name="1080321"> </a>
If Red Hat Console connects to Directory Server over SSL, selecting "Require client authentication" disables communication. This is because, although Red Hat Console supports SSL, it does not have a certificate to use for client authentication.
</p>
</td>
  </tr>

<tr><td  colspan="2">
<hr size="1" />
</td></tr>
</table>

<br />
<br />

  </dl>

<li value="4">
Map the certificate's distinguished name to a distinguished name known by your directory.
<a name="1079626"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1054122"> </a>
This allows you to set access control for the client when it binds using this certificate. This mapping process is described in <a href="../pdf/console60.pdf"><em>Managing Servers with Red Hat Console</em></a>.
<br />&nbsp;</dt>  </dl>
</ol>
<p class="h2">
<a name="1080341"> </a>
<a name="Allowing/Requiring Client Authentication"> </a>
Allowing/Requiring Client Authentication
</p>


<p class="text">
<a name="1080346"> </a>
If you have configured Red Hat Console to connect to your Directory Server using SSL <em>and</em> your Directory Server <em>requires</em> client authentication, you can no longer use Red Hat Console to manage server applications. You will have to use the appropriate command-line utilities instead.
</p>
<p class="text">
<a name="1080356"> </a>
However, if at a later date you wish to change your directory configuration to no longer <em>require</em> but <em>allow</em> client authentication, so that you can use Red Hat Console, you must follow these steps:
</p>
<ol type="1">

<li value="1">
Stop Directory Server.
<a name="1080342"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1080387"> </a>
For information on stopping and starting the server from the command-line, see <a href="intro.htm#1072054"  >"Starting and Stopping the Server from the Command-Line"</a>.
<br />&nbsp;</dt>  </dl>

<li value="2">
Modify the <code>cn=encryption,cn=config</code> entry by changing the value of the <code>nsSSLClientAuth</code> attribute from <code>required</code> to <code>allowed</code>.
<a name="1080372"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1080375"> </a>
For information on modifying entries from the command-line, see <a href="modify.htm#996824"  >chapter 2,  "Creating Directory Entries</a>."
<br />&nbsp;</dt>  </dl>

<li value="3">
Start Directory Server.
<a name="1080376"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1080391"> </a>
You can now start Red Hat Console.
<br />&nbsp;</dt>  </dl>
</ol>
<p class="h1">
<a name="1048777"> </a>
<a name="Configuring LDAP Clients to Use SSL"> </a>
Configuring LDAP Clients to Use SSL
<hr size="1" noshade="noshade" />
</p>

<p class="text">
<a name="1079713"> </a>
If you want all the users of your Directory Server to use SSL or certificate-based authentication when they connect using LDAP client applications, you must make sure they perform the following tasks:
</p>
<ul>

<li>
Create a certificate database.
<a name="1079714"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li>
Trust the Certificate Authority (CA) that issues the server certificate.
<a name="1048780"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
</ul>
<p class="text">
<a name="1048781"> </a>
These operations are sufficient if you want to ensure that LDAP clients recognize the server's certificate. However, if you also want LDAP clients to use their own certificate to authenticate to the directory, make sure that all your directory users obtain and install a personal certificate.
</p>
<table border="0" cellpadding="0" width="90%">
<tr><td  colspan="2">
<hr size="1" />
</td></tr>
<tr>
<td valign="top"><p class="note">
<a name="1080077"> </a>
Note&nbsp;&nbsp;
</p>

</td>
<td valign="top"><p class="text">
<a name="1080079"> </a>
Some client applications do not verify that the server has a trusted certificate.
</p>
</td>
  </tr>

<tr><td  colspan="2">
<hr size="1" />
</td></tr>
</table>

<br />
<br />

<ol type="1">

<li value="1">
On the client system, obtain a client certificate from the CA.
<a name="1048792"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="2">
On your client system, install your client certificate.
<a name="1079934"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1048793"> </a>
Regardless of how you receive your certificate (either in email or on a web page), there should be a link that you click to install the certificate.
<br />&nbsp;</dt>     <dt> <a name="1080095"> </a>
Make sure you record the certificate information that is sent to you in a file. In particular, you must know the subject DN of the certificate because you must configure the server to map it to an entry in the directory. Your client certificate will be similar to:
<br />&nbsp;</dt>     <dt> <a name="1080114"> </a>
<code>-----BEGIN CERTIFICATE-----<br />MIICMjCCAZugAwIBAgICCEEwDQYJKoZIhvcNAQEFBQAwfDELMAkGA1UEBh<br />MCVVMxIzAhBgNVBAoTGlBhbG9va2FWaWxsZSBXaWRnZXRzLCBJbmMuMR0w<br />GwYDVQQLExRXaWRnZXQgTWFrZXJzICdSJyBVczEpMCcGA1UEAxMgVGVzdC<br />BUZXN0IFRlc3QgVGVzdCBUZXN0IFRlc3QgQ0EwHhcNOTgwMzEyMDIzMzU3<br />WhcNOTgwMzI2MDIzMzU3WjBPMQswCQYDVQQGEwJVUzEoMCYGA1UEChMfTm<br />V0c2NhcGUgRGlyZWN0b3<br />-----END CERTIFICATE-----</code>
<br />&nbsp;</dt>  </dl>

<li value="3">
You must convert the client certificate into its binary format using the <code>certutil</code> utility. To do this:
<a name="1080096"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1080194"> </a>
<code>certutil -L -d </code><em>certdbPath</em>&nbsp;<code> -n </code><em>userCertName</em>&nbsp;<code> -r &gt; </code><em>userCert.bin</em>
<br />&nbsp;</dt>     <dt> <a name="1080183"> </a>
where <em>certdbPath</em> is the location of your certificate database, <em>userCertName</em> is the name you gave to your certificate when you installed it, and <em>userCert.bin</em> is the name you must specify for the output file that will contain the certificate in the binary format.
<br />&nbsp;</dt>  </dl>

<li value="4">
On the server, map the subject DN of the certificate that you obtained to the appropriate directory entry by editing the <code>certmap.conf</code> file.
<a name="1080182"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1079975"> </a>
This procedure is described in <a href="../pdf/console60.pdf"><em>Managing Servers with Red Hat Console</em></a>. 
<br />&nbsp;</dt><table border="0" cellpadding="0" width="90%">
<tr><td  colspan="2">
<hr size="1" />
</td></tr>
<tr>
<td valign="top"><p class="note">
<a name="1080643"> </a>
Note&nbsp;&nbsp;
</p>

</td>
<td valign="top"><p class="text">
<a name="1081629"> </a>
Do not map your certificate-based-authentication certificate to a distinguished name under <code>cn=monitor</code>. If you map your certificate to a DN under <code>cn=monitor</code>, your bind will fail. Map your certificate to a target located elsewhere in the directory information tree.
</p>
<p class="text">
<a name="1080652"> </a>
Make sure that the <code>verifyCert</code> parameter is set to <code>on</code> in the <code>certmap.conf</code> file. If this parameter is not set to <code>on</code>, Directory Server simply searches for an entry in the directory that matches the information in the <code>certmap.conf</code> file. If the search is successful, it grants access without actually checking the value of the <code>userCertificate</code> and <code>userCertificate;binary</code> attributes.
</p>
</td>
  </tr>

<tr><td  colspan="2">
<hr size="1" />
</td></tr>
</table>

<br />
<br />

  </dl>

<li value="5">
In the Directory Server, modify the directory entry for the user who owns the client certificate to add the <code>userCertificate</code> attribute.
<a name="1079987"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <ol type="a">

<li>
Select the Directory tab, and navigate to the user entry.
<a name="1080177"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
<li>
Double click the user entry, and use the Property Editor to add the <code>userCertificate</code> attribute, with the <code>binary</code> subtype.
<a name="1080221"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>    <dl>
       <dt> <a name="1080226"> </a>
When you add this attribute, instead of an editable field, the server provides a Set Value button.
<br />&nbsp;</dt>    </dl>

<li>
Click Set Value.
<a name="1080181"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>    <dl>
       <dt> <a name="1080234"> </a>
A file selector is displayed. Use it to select the binary file you created in <a href="ssl.htm#1080096"  >Step 3</a>.
<br />&nbsp;</dt>    </dl>
  </ol>
  <dl>
     <dt> <a name="1080035"> </a>
For information on using the Directory Server Console to edit entries, refer to "<a href="modify.htm#1128965"  >Modifying Directory Entries</a>," on <a href="modify.htm#1128965"  >page 49</a>.
<br />&nbsp;</dt>  </dl>
</ol>
<p class="text">
<a name="1079986"> </a>
You can now use SSL with your LDAP clients. For information on how to use SSL with <code>ldapmodify</code>, <code>ldapdelete</code>, and <code>ldapsearch</code>, refer to <a href="../cli/utilities.htm"><em>Red Hat Directory Server Configuration, Command, and File Reference</em></a>.
</p>
<p class="h1">
<a name="1083165"> </a>
<a name="Introduction to SASL"> </a>
Introduction to SASL
<hr size="1" noshade="noshade" />
</p>

<p class="text">
<a name="1083166"> </a>
Directory Server supports LDAP client authentication through the Simple Authentication and Security Layer (<a href="glossary.htm#1044886"  >SASL</a>), an alternative to SSL/TLS and a native way for some applications to share information securely. 
</p>
<p class="text">
<a name="1086536"> </a>
SASL is a framework, meaning it sets up a system that allows different mechanisms to authenticate a user to the server, depending on what mechanism is enabled in both client and server applications. SASL can also set up a security layer for an encrypted session. Directory Server utilizes the GSS-API mechanism to encrypt data during sessions.
</p>
<table border="0" cellpadding="0" width="90%">
<tr><td  colspan="2">
<hr size="1" />
</td></tr>
<tr>
<td valign="top"><p class="note">
<a name="1083920"> </a>
Note&nbsp;&nbsp;
</p>

</td>
<td valign="top"><p class="text">
<a name="1083922"> </a>
SASL data encryption is not supported for client connections that use SSL/TLS.
</p>
</td>
  </tr>

<tr><td  colspan="2">
<hr size="1" />
</td></tr>
</table>

<br />
<br />

<p class="h2">
<a name="1083896"> </a>
<a name="Authentication Mechanisms"> </a>
Authentication Mechanisms
</p>


<p class="text">
<a name="1083947"> </a>
Directory Server support the following SASL encryption mechanisms:
</p>
<ul>

<li>
EXTERNAL
<a name="1086152"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1086167"> </a>
The EXTERNAL authentication mechanism is utilized by services such as SSL/TLS. It can be used with public keys for strong authentication.
<br />&nbsp;</dt>  </dl>

<li>
DIGEST-MD5
<a name="1086157"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1086180"> </a>
DIGEST-MD5 is a mandatory authentication method for LDAPv3 servers. While it is not as strong as public key systems or Kerberos authentication methods, it is preferred over plaintext passwords and does protect against plaintext attacks.
<br />&nbsp;</dt>  </dl>

<li>
Generic Security Services (GSS-API)
<a name="1086158"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
  <dl>
     <dt> <a name="1086192"> </a>
Generic Security Services (GSS) is a security API that is the native way for UNIX-based operating systems to access and authenticate Kerberos services. <a href="glossary.htm#1044906"  >GSS-API</a> also supports session encryption via function calls that can be used to wrap and unwrap payload data. This allows LDAP clients to authenticate with the server using Kerberos version 5 credentials. 
<br />&nbsp;</dt><table border="0" cellpadding="0" width="90%">
<tr><td  colspan="2">
<hr size="1" />
</td></tr>
<tr>
<td valign="top"><p class="note">
<a name="1085243"> </a>
Note&nbsp;&nbsp;
</p>

</td>
<td valign="top"><p class="text">
<a name="1085245"> </a>
GSS-API and, thus, Kerberos are only supported on platforms that have GSS-API support.
</p>
</td>
  </tr>

<tr><td  colspan="2">
<hr size="1" />
</td></tr>
</table>

<br />
<br />

  </dl>
</ul>
<p class="text">
<a name="1086217"> </a>
DIGEST-MD5 and GSS-API are <em>shared secret</em> mechanisms. This means that the server challenge the client attempting to bind with a "secret," such as a password, that depends on the mechanism. The user sends back the response required by the mechanism. 
</p>
<p class="h2">
<a name="1085255"> </a>
<a name="SASL Identity Mapping"> </a>
SASL Identity Mapping
</p>


<p class="text">
<a name="1085259"> </a>
When processing a SASL bind request, the server matches, or maps, the SASL user ID used to authenticate to the Directory Server with an LDAP entry stored within the server.
</p>
<p class="text">
<a name="1086489"> </a>
If the user ID clearly corresponds to the LDAP entry for a person, it is possible to configure the Directory Server to map the authentication DN automatically to the entry DN. Every branch in the directory tree has a default map, and customized maps can be created. During a bind attempt, a randomly selected custom map is applied. If only one user identity is returned, the bind is successful; if none or more than one are returned, then the next custom map is tried, and so on, until the default is tried. If no map works, then the bind fails.
</p>
<table border="0" cellpadding="0" width="90%">
<tr><td  colspan="2">
<hr size="1" />
</td></tr>
<tr>
<td valign="top"><p class="note">
<a name="1087031"> </a>
Note&nbsp;&nbsp;
</p>

</td>
<td valign="top"><p class="text">
<a name="1087033"> </a>
SASL proxy authorization is not supported in Directory Server; therefore, the server will ignore any SASL <code>authzid</code> supplied by the client.
</p>
</td>
  </tr>

<tr><td  colspan="2">
<hr size="1" />
</td></tr>
</table>

<br />
<br />

<p class="text">
<a name="1086294"> </a>
SASL is configured by entries under a container entry:
</p>
<dl><p class="code">
<a name="1086282"></a>
dn: cn=sasl,cn=config<br />
objectClass: top<br />
objectClass: nsContainer<br />
cn: sasl

</p></dl><p class="text">
<a name="1086283"> </a>
SASL identity mapping entries are children of second container entry:
</p>
<dl><p class="code">
<a name="1086284"></a>
dn: cn=mapping,cn=sasl,cn=config<br />
objectClass: top<br />
objectClass: nsContainer<br />
cn: mapping

</p></dl><p class="text">
<a name="1086285"> </a>
Mapping entries contain three attributes, <code>nsSaslMapRegexString</code>, <code>nsSaslMapBaseDNTemplate</code>, and <code>nsSaslMapFilterTemplate</code>. The <code>nsSaslMapping</code> object class sets these identity mapping parameters. The <code>nsSaslMapRegexString</code> attribute sets variables of the form <code>\1</code>, <code>\2</code>, <code>\3</code>, etc., for bind IDs which are filled into the template attributes during a search. For example, assume the <code>nsSaslMapping</code> is set up as follows:
</p>
<dl><p class="code">
<a name="1085479"></a>
dn: cn=mymap,cn=mapping,cn=sasl,cn=config<br />
objectclass:top<br />
objectclass:nsSaslMapping<br />
cn: mymap<br />
nsSaslMapRegexString: (.*)@(.*)\.(.*)<br />
nsSaslFilterTemplate: (objectclass=inetOrgPerson)<br />
nsSaslBaseDNTemplate: uid=\1,ou=people,dc=\2,dc=\3

</p></dl><p class="text">
<a name="1086342"> </a>
A bind attempt with <code>mconnors@example.com</code> as the regular expression would "fill in" the base DN template with <code>uid=mconnors,ou=people,dc=example,dc=com</code> as the authentication ID, and authentication would proceed from there.
</p>
<p class="text">
<a name="1086891"> </a>
You could also write a broader mapping scheme, such as the following:
</p>
<dl><p class="code">
<a name="1086845"></a>
objectclass: top<br />
objectclass: nsSaslMapping<br />
cn: mymap2<br />
nsSaslMapRegexString: .*<br />
nsSaslMapBaseDNTemplate: ou=People,dc=example,dc=com<br />
nsSaslMapFilterTemplate: (cn=&amp;) 

</p></dl><p class="text">
<a name="1086852"> </a>
This will match any user ID and map to the result of the the subtree search with base <code>ou=People,dc=example,dc=com</code> and filter <code>cn=</code><em>userId</em>.
</p>
<p class="h3">
<a name="1086549"> </a>
<a name="Legacy Identity Mapping"> </a>
Legacy Identity Mapping
</p>
<p class="text">
<a name="1086553"> </a>
Older versions of Directory Server did support limited SASL mechanisms, EXTERNAL and DIGEST-MD5. These mechanisms have simple username-based identies, so the server implements a simple identity mapping scheme using the <code>uid</code> to find the corresponding directory entries. A user binds with an authentication DN such as <code>uid=bjensen,ou=people,dc=example,dc=com</code>, and the server searches across the entire directory contents, looking for an entry with a corresponding <code>uid</code>. This identity mapping is hard-coded and cannot be changed. 
</p>
<p class="text">
<a name="1086660"> </a>
Because Kerberos has more complicated identities (see <a href="ssl.htm#1086092"  >"Realms"</a>), Directory Server supports regular expression-based mapping schemes. In processing a bind request, the server first tries to apply any regular expression mapping, if configured. If no match is found, then the server tries to apply legacy mapping.
</p>
<p class="h2">
<a name="1085437"> </a>
<a name="Configuring SASL Identity Mapping from the Console"> </a>
Configuring SASL Identity Mapping from the Console
</p>


<ol type="1">

<li value="1">
In the Console, open the Directory Server.
<a name="1085267"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="2">
Open the "Configuration" tab.
<a name="1085268"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="3">
Select the "SASL Mapping" tab.
<a name="1085274"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>

<li value="4">
Select the "Add" button, and fill in the required values.
<a name="1085278"> </a>
<img src="pixel.gif" align="top" height="22" alt="" />
</li>
</ol>
<p class="text">
<a name="1085284"> </a>
Before you can modify a SASL identity, you must have saved that identity. Then you can click on the "Modify" button, and a text box appears with the current values. Change the values you want, and then close, and hit "Save." To delete a SASL identity, highlight it, and hit the "Delete" button.
</p>
<p class="h2">
<a name="1087006"> </a>
<a name="Configuring SASL Identity Mapping from the Command-Line"> </a>
Configuring SASL Identity Mapping from the Command-Line
</p>


<p class="text">
<a name="1087016"> </a>
To configure SASL identity mapping from the command-line, use the <code>ldapmodify</code> utility to configure an identity mapping scheme, such as the following:
</p>
<dl><p class="code">
<a name="1087017"></a>
ldapmodify -a -p 389 -h localhost -D <code>"</code>cn=directory manager<code>"</code> -w 
password33

</p><p class="code">
<a name="1089215"></a>
dn: cn=mymap2,cn=mapping,cn=sasl,cn=config<br />
objectclass: top<br />
objectclass: nsSaslMapping<br />
cn: mymap2<br />
nsSaslMapRegexString: .*<br />
nsSaslMapBaseDNTemplate: ou=People,dc=example,dc=com<br />
nsSaslMapFilterTemplate: (cn=&amp;) 

</p></dl><p class="text">
<a name="1087018"> </a>
This will match any user ID and map to the result of the the subtree search with base <code>ou=People,dc=example,dc=com</code> and filter <code>cn=</code><em>userId</em>.
</p>
<p class="h2">
<a name="1085885"> </a>
<a name="Configuring Kerberos"> </a>
Configuring Kerberos
</p>


<p class="text">
<a name="1084930"> </a>
Kerberos v5 must be deployed on your system to utilize the GSS-API mechanism for SASL authentication. <a href="ssl.htm#1083776"  >Table&nbsp;11-1</a> summarizes the Kerberos applications supported by various platforms. GSS-API must be enabled as a SASL mechanism in the Directory Server to take advantage of Kerberos services.
</p>
<br />
<p class="caption">
<a name="1083776"> </a>
<a name="Supported Kerberos Systems"> </a>
Table 11-1	&nbsp;&nbsp; Supported Kerberos Systems
</p>
<br/>
<table width="90%" border="1" cellspacing="0" cellpadding="4">
<tr>
<td valign="top">
<p class="tabletext">
<a name="1083780"> </a>
Linux
</p></td>
<td valign="top">
<p class="tabletext">
<a name="1083782"> </a>
MIT Kerberos version 5
</p></td>
  
</tr>
<tr>
<td valign="top">
<p class="tabletext">
<a name="1083784"> </a>
HP-UX 11i
</p></td>
<td valign="top">
<p class="tabletext">
<a name="1083786"> </a>
HP Kerberos version 2.1
</p></td>
  
</tr>
<tr>
<td valign="top">
<p class="tabletext">
<a name="1083788"> </a>
Sun Solaris
</p></td>
<td valign="top">
<p class="tabletext">
<a name="1083790"> </a>
SEAM 1.0.1
</p></td>
  
</tr>

</table>


<br />
<br />

<p class="h3">
<a name="1086092"> </a>
<a name="Realms"> </a>
Realms
</p>
<p class="text">
<a name="1086072"> </a>
A <em>realm</em> is a set of users and the authentication methods for those users to access the realm. A realm resembles a fully-qualified domain name and can be distributed across either a single server or a single domain across multiple machines. A single server instance can also support multiple realms.
</p>
<p class="text">
<a name="1086505"> </a>
Realms are used by the server to associate the DN of the client in the following form, which looks like an LDAP URL:
</p>
<p class="text">
<a name="1086506"> </a>
<code>uid=</code><em>user_name</em>&nbsp;<code>/[</code><em>server_instance</em>&nbsp;<code>],cn=</code><em>realm</em>&nbsp;<code>,cn=</code><em>mechanism</em>&nbsp;<code>,cn=auth</code>
</p>
<table border="0" cellpadding="0" width="90%">
<tr><td  colspan="2">
<hr size="1" />
</td></tr>
<tr>
<td valign="top"><p class="note">
<a name="1086075"> </a>
Note&nbsp;&nbsp;
</p>

</td>
<td valign="top"><p class="text">
<a name="1086077"> </a>
Kerberos systems treat the Kerberos realm as the default realm; other systems default to the server.
</p>
</td>
  </tr>

<tr><td  colspan="2">
<hr size="1" />
</td></tr>
</table>

<br />
<br />

<p class="text">
<a name="1086079"> </a>
Mike Connors in the <code>engineering</code> realm of the European division of <code>example.com</code> would have the following association if he tried to access a different server, such as <code>cyclops</code>:
</p>
<dl><p class="code">
<a name="1086080"></a>
uid=mconnors/cn=Europe.example.com, 
cn=engineering,cn=gssapi,cn=auth

</p></dl><p class="text">
<a name="1086081"> </a>
Babs Jensen in the <code>accounting</code> realm of <code>US.example.com</code> would not have to specify <em>server_instance</em>:
</p>
<dl><p class="code">
<a name="1086082"></a>
uid=bjensen,cn=accounting,cn=gssapi,cn=auth

</p></dl><p class="text">
<a name="1086083"> </a>
If realms are supported by the mechanism and the default realm was not used, <em>realm</em> must be specified; otherwise, it is omitted. Currently, only GSS-API supports the concept of realms.
</p>
<p class="h3">
<a name="1083840"> </a>
<a name="Configuring the KDC Server"> </a>
Configuring the KDC Server
</p>
<p class="text">
<a name="1084994"> </a>
To use GSS-API, the user first obtains a ticket granting ticket (TGT). The ticket and the ticket's lifetime are parameters in the <code>kdc</code> server configuration in the <code>/etc/krb5/krb5.conf</code> file. See <a href="ssl.htm#1084197"  ></a><a href="ssl.htm#1084197"  >"Example"</a>.
</p>
<table border="0" cellpadding="0" width="90%">
<tr><td  colspan="2">
<hr size="1" />
</td></tr>
<tr>
<td valign="top"><p class="note">
<a name="1086464"> </a>
Note&nbsp;&nbsp;
</p>

</td>
<td valign="top"><p class="text">
<a name="1086473"> </a>
The HP server and client are separate packages with their own configuration. The server stores config files in <code>/opt/krb5</code>. The client is classic MIT and uses <code>/etc/krb5.conf</code>. You need to configure both to have a working Kerberos system.
</p>
</td>
  </tr>

<tr><td  colspan="2">
<hr size="1" />
</td></tr>
</table>

<br />
<br />

<p class="text">
<a name="1086896"> </a>
In order to respond to Kerberos operations, the Directory Server requires access to its own cryptographic key which is read by the Kerberos libraries that the server calls via GSSAPI. The details of how it is found are implementation-dependent. However, in current releases of the supported Kerberos implementations, the mechanism is the same: the key is read from a file called a <em>keytab</em> file. This file is created by the Kerberos administrator by exporting the key from the KDC. Either the system default keytab file (typically <code>/etc/krb5.keytab</code>) is used, or a service-specific keytab file determined by the value of the <code>KRB5_KTNAME</code> environment variable. 
</p>
<p class="text">
<a name="1089263"> </a>
The Directory Server uses the service name <code>ldap</code>. Its Kerberos principal is <code>ldap/</code><em>host-fqdn</em>&nbsp;<code>@</code><em>realm</em>. A key with this identity must be stored in the server's keytab in order for Kerberos to work. For information on setting up the service key, see your Kerberos documentation.
</p>
<p class="h3">
<a name="1084197"> </a>
<a name="Example"> </a>
Example
</p>
<p class="text">
<a name="1084208"> </a>
<a href="ssl.htm#1083638"  >Code Example&nbsp;11-1</a> is an example code for a KDC server configured with the <code>company.example.com</code> realm.
</p>
<br />
<table width="90%" border="0" cellpadding="0" cellspacing="0">
<tr><td>
<p class="caption">
<a name="1083638"> </a>
<a name="Configuring an Example KDC Server"> </a>
Code Example 11-1	&nbsp;&nbsp; Configuring an Example KDC Server
</p>
</td></tr>
<tr><td><hr noshade size="1" /></td></tr>

<tr>
<td valign="top">
<code>
<a name="1083648"> </a>
[libdefaults]

</code>
<br /><code>
<a name="1083649"> </a>
         ticket_lifetime = 24000

</code>
<br /><code>
<a name="1083650"> </a>
         default_realm = COMPANY.EXAMPLE.COM

</code>
<br /><code>
<a name="1083651"> </a>
         dns_lookup_realm = false

</code>
<br /><code>
<a name="1083652"> </a>
         dns_lookup_kdc = false

</code>
<br /><code>
<a name="1083653"> </a>
         ccache_type = 1

</code>
<br /><code>
<a name="1083654"> </a>
         forwardable = true

</code>
<br /><code>
<a name="1083655"> </a>
         proxiable = true

</code>
<br /><code>
<a name="1083656"> </a>
         default_tgs_enctypes = des3-hmac-sha1 des-cbc-crc

</code>
<br /><code>
<a name="1083657"> </a>
         default_tkt_enctypes = des3-hmac-sha1 des-cbc-crc

</code>
<br /><code>
<a name="1083658"> </a>
         permitted_enctypes = des3-hmac-sha1 des-cbc-crc

</code>
<br /><code>
<a name="1083659"> </a>
[realms]

</code>
<br /><code>
<a name="1083660"> </a>
  COMPANY.EXAMPLE.COM = {

</code>
<br /><code>
<a name="1083661"> </a>
     kdc = kdcserver.company.example.com:88

</code>
<br /><code>
<a name="1083662"> </a>
     admin_server = adminserver.company.example.com:749

</code>
<br /><code>
<a name="1083663"> </a>
     default_domain = company.example.com

</code>
<br /><code>
<a name="1083642"> </a>
  }

</code>
<br /></td>
  </tr>
<tr>
<td valign="top">
<code>
<a name="1083668"> </a>
[appdefaults]

</code>
<br /><code>
<a name="1083669"> </a>
  pam = {

</code>
<br /><code>
<a name="1083670"> </a>
    debug = true

</code>
<br /><code>
<a name="1083671"> </a>
    ticket_lifetime = 36000

</code>
<br /><code>
<a name="1083672"> </a>
    renew_lifetime = 36000

</code>
<br /><code>
<a name="1083673"> </a>
    forwardable = true

</code>
<br /><code>
<a name="1083674"> </a>
    krb4_convert = false

</code>
<br /><code>
<a name="1083644"> </a>
 }

</code>
<br /></td>
  </tr>


<tr><td><hr noshade size="1" /></td></tr>
</table>
<br />
<br />

<p class="text">
<a name="1089264"> </a>

</p>

</blockquote>
<!--end bookcontent-->
<!--footercontent defines the bottom navigation and the copyright. It also includes
the revision date-->
<!--start footercontent-->


<br />
<br />
<span class="navigation">
<a style="text-decoration: none; color:#990000" href="index1.htm">
Previous
</a>
</span>

&nbsp;&nbsp;&nbsp;&nbsp;


<span class="navigation">
<a style="text-decoration: none; color:#990000" href="contents.htm">
Contents
</a>
</span>
&nbsp;&nbsp;&nbsp;&nbsp;


<span class="navigation">
<a style="text-decoration: none; color:#990000" href="ix.htm">
Index
</a>
</span>
&nbsp;&nbsp;&nbsp;&nbsp;


<span class="navigation">
<a style="text-decoration: none; color:#990000" href="../index.htm">
DocHome
</a>
</span>
&nbsp;&nbsp;&nbsp;&nbsp;


<span class="navigation">
<a style="text-decoration: none; color:#990000" href="dsstats.htm">
Next
</a>
</span>
&nbsp;&nbsp;&nbsp;&nbsp;

        
<hr noshade="noshade" size="1" />
<p class="copy">&copy; 2001 Sun Microsystems, Inc. Portions copyright 1999, 2002-2004 Netscape Communications Corporation, 2005 Red Hat, Inc. All rights reserved. <br>
<a href="../copyright/copyright.html">Read the Full Copyright and Third-Party Acknowledgments</a>. </p>
<br />
<p class="update">Last Updated <b>May 27, 2008</b></p>
    

<!--end footercontent-->
<!--end maincontent-->
</body>
</html>

Actions: View

Attachments on bug 441889: 304914 | 306859