(back to mod_auth_ldap page)

Table of Contents

• Introduction
• Using SSL for encryption
  • If Compiled with iPlanet C SDK
  • If Compiled with OpenLDAP C SDK (module v3.05+)
• How to use SSL with MS Active Directory (AD)(module v3.05+)
• How to use self signed certificate for SSL
• Using TLS for encryption
• Copyright

Introduction
This document describes how to configure and use SSL/TLS with my LDAP authentication module for Apache 1.3.x and 2.x.

Using SSL for encryption
In order to get SSL capabilities, the module can be compiled with

• Old Netscape or new iPlanet C SDK 5.08
  or
  
• OpenLDAP C SDK.

If compiled with either of the SDK, SSL will work with any SSL enabled LDAP server e.g., iPlanet, OpenLDAP, Microsoft AD. Howerver, module configuration is different for each SDK.

If Compiled with iPlanet C SDK
If compiled with iPlanet C SDK 5.08, in order to use SSL, you will need the certificate database file comes with netscape 4.x browser. The reason you need certificate database from netscape 4.x browser is that the LDAP API uses this database for certificate authorities' (CA) certificate. netscape 4.x keeps the certificate of certificate authorities (CA) in the file cert7.db file. This database is platform independent. To view the list, start netscape 4.x and click on the lock icon. A window will pop, click on the Signers. If the certificate you're using in your LDAP server is from one of the CAs in the list, you can use the cert7.db with the module for SSL. If you are using your own self signed certificate with your LDAP server, you can insert your self signed certificate in this database. Please look at the section How to use self signed certificate for SSL.

To configure SSL for the module, do the following:

• Start netscape 4.x browser. (Please don't ask me where to get it)

• Find the files cert7.db and key3.db. In Linux/Unix, the files are in $HOME/.netscape directory.

• Copy them to a directory say /usr/local/ssl. Note: as the files are platform independent, you can use them in Windows as well. (Note: I supplied cert7.db and key3.db files from Netscape Communicator 4.75 for your convenience)

• Specify the path of the db files to the module with directive: LDAP_CertDbDir

  Example:

  LDAP_CertDbDir /usr/local/ssl # in Windows LDAP_CertDbDir c:/usr/local/ssl

• Specify the LDAP server's SSL port to the module. You must specify that.

  Example:

  LDAP_Port 636

• Start Apache. Make sure module is loaded correctly.

• Verify that SSL is working with your LDAP server. Use the tool ldapsearch comes with iPlanet C SDK 5.08 or iPlanet Directory Server.

  Example:

  $ ldapsearch -Z -h ldap.muquit.com -b "o=muquit.com" \ -P /usr/local/ssl "uid=muquit"

  If the above command works, the module will work as well. If CA certificate in cert7.db is not trusted by your LDAP server, the error message will look like:

  ldap_search: Can't contact LDAP server SSL error -8172 (Peer's certificate issuer has been marked as not trusted by the user.)

  Turn debugging on with the directive LDAP_Debug On and watch the Apache's error_log to make sure SSL is used.

If Compiled with OpenLDAP C SDK (module v3.05+)
If the module is compiled with SSL enabled OpenLDAP SDK, you can use StartTLS. If you use openLDAP server, it's the easiest and proper way to get SSL.

For SSL (port 636) support (ldaps) using OpenLDAP SDK, you'll need:

Create ldaprc file as follows:

Note cacert.pem is the CA certificate. Before starting apache set a env variable (probably in apachectl) like:

Make sure apache can read the ldaprc file and the certificate you specified there.

How to use SSL with MS Active Directory (AD)
To use SSL with AD, first you've to obtain the CA certificate from AD. Here's how to do it:

• Start the Certification Authority tool from: Start->Administrative Tools->Certification Authority
• Highlight the Certificate authority of the machine, Click right mouse button and click on Properties.
• From General menu, click on View Certificate
• Select Details Tab and click on Copy to File...
• Certificate Export Wizard will start. Click on Next button.
• Select DER encoded binary X.509(.CER)
• Click on Next button
• Specify the filename e.g. "ms_cacert.cer" and clck on Next button. Click on Finish button.
• Transfer the file "ms_cert.cer" to the machine where the ldapauth client will be running.
• Dump the certificate using and make sure everything looks correct.

  $ openssl x509 -inform DER -text < ms_cacert.cer

• Convert the certificate from DER to PEM format using openssl.

  $ openssl x509 -inform DER -outform PEM \ -in ms_cacert.cer -out ms_cacert.pem

• Dump the PEM formatted certificate to make sure it looks correct.

  $ openssl x509 -inform PEM -text < ms_cacert.pem

• If compiled with OpenLDAP C SDK, create a directory say /usr/local/certs and copy the file ms_cacert.pem there. Make sure the directory /usr/local/certs accessible and the certificate ms_cacert.pem is readable by world.
  Create the ldaprc file and specify the path of ms_cacert.pem.
  Look at the section If Compiled with OpenLDAP C SDK.

• If compiled with iPlanet C SDK, please look at the section If Compiled with iPlanet C SDK.

How to use self signed certificate for SSL
If you're using iPlanet Directory Server and want to use encryption but don't have certificate from one of the certificate authorities in cert7.db, this document is for you. We'll use OpenSSL to create certificates. Please follow the steps:

1. Install OpenSSL. We'll use the tool CA.sh from OpenSSL. It's in the apps directory.
2. At the shell prompt, type:

   $ mkdir my_ca $ cd my_ca $ CA.sh -newca A example session is shown below: $ CA.sh -newca CA certificate filename (or enter to create) Making CA certificate ... Using configuration from /opt1/users/mmuquit/openssl/ssl/openssl.cnf Generating a 1024 bit RSA private key ....................++++++ .......................++++++ writing new private key to './demoCA/private/./cakey.pem' Enter PEM pass phrase: Verifying password - Enter PEM pass phrase: ----- You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [AU]:US State or Province Name (full name) [Some-State]:Pennsylvania Locality Name (eg, city) []:Philadelphia Organization Name (eg, company) [Internet Widgits Pty Ltd]:muquit.com Organizational Unit Name (eg, section) []:ca Common Name (eg, YOUR name) []:muquit.com Email Address []:muquit@muquit.com

   The file cacert.pem inside the directory demoCA is the self signed certificate. This certificate will be used to sign the certificate request of the ldap server. You can look at the certificate by running the command:

   $ openssl x509 -inform PEM -text < ./demoCA/cacert.pem

3. Generate the certificate request for the iPlanet Directory Server. Follow the iPlanet directory administration guide for instruction on how to generate the certificate request. Copy the certificate request in the file newreq.pem in the my_ca directory. Run the command CA.sh -sign to sign the certificate. Here's an example session:

   $ CA.sh -sign Using configuration from /opt1/users/mmuquit/openssl/ssl/openssl.cnf Enter PEM pass phrase: Check that the request matches the signature Signature ok The Subjects Distinguished Name is as follows countryName :PRINTABLE:'US' stateOrProvinceName :PRINTABLE:'Pennsylvania' localityName :PRINTABLE:'Philadelphia' organizationName :PRINTABLE:'Example Inc.' organizationalUnitName:PRINTABLE:'Software Dev' commonName :PRINTABLE:'ldap.example.com' Certificate is to be certified until Dec 26 20:17:30 2003 GMT (365 days) Sign the certificate? [y/n]:y 1 out of 1 certificate requests certified, commit? [y/n]y Write out database with 1 new entries Data Base Updated ....

   The file newcert.pem is the signed certificate. Please follow the iPlanet directory administration guide for instruction on how to install the certificate. From the file newcert.pem copy the section from -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- and use it as certificate in the text area of the iPlanet console.

4. Follow the iPlanet directory administration guide to install the CA certificate cacert.pem as a trusted CA certificate.

5. Incert the cacert.pem in cert7.db. There're two ways it can be done:
   • use netscape 4.x browser
   • use certutil from mozilla.org. You've to compile it yourself. (Do not confuse it with the one available from Microsoft. They're not the same tool)

     * Use netscape 4.x browser to insert CA certificate in cert7.db
     

     1. To do that, first we'll have to convert the certificate to DER format from PEM format. Here's how you do it:

        $ openssl x509 -inform PERM -outform DER < cacert.pem > cacert.der

     2. Install the supplied CGI program inst_cacert.pl in your CGI directory.
     3. Copy cacert.der to your CGI directory.
     4. Start netscape 4.x and access the URL of the CGI program inst_cacert.pl, e.g. http://your_web_server/cgi-bin/inst_cacert.pl. A dialog will pop to accept the certificate. Accept the certificate for ever. Exit netscape 4.x and restart it. Click on the lock icon and then click on Signers. Make sure your CA certificate shows up in the list.
     5. Copy to a directory say /usr/local/ssl which must be accessible and readable by your apache 2 server. Verify that SSL is working with your LDAP server. Use the tool ldapsearch comes with iPlanet C SDK 5.08 or iPlanet Directory Server.

        Example:

        $ ldapsearch -Z -h ldap.muquit.com -b "o=muquit.com" \ -P /usr/local/ssl "uid=muquit"

        If search works, use the directive LDAP_CertDbDir to specify the path /usr/local/ssl and the directive LDAP_port to specify the SSL port of your ldap server.

     * Use certutil to insert CA certificate in cert7.db
     

     1. Convert the CA certificate to DER format as instructed above.

     2. create a new database first:

        $ mkdir ./ssl $ certutil -N -d ./ssl

        Eenter a password as asked

     3. Insert the CA certificate to the new database:

        $ certutil -A -n "muquit.com CA" -t "C,C,C" -i ./cacert.der -d ./ssl

     4. To make sure iist the certificates in the db:

        $ ./certutil -L -d ./ssl

        The output should be something like:

        Certificate Name Trust Attributes muquit.com CA C,C,C p Valid peer P Trusted peer (implies p) c Valid CA T Trusted CA to issue client certs (implies c) C Trusted CA to certs(only server certs for ssl) (implies c) u User cert w Send warning

     5. Verify that SSL is working with your LDAP server using the new certificate db file. Use the tool ldapsearch comes with iPlanet C SDK 5.08 or iPlanet Directory Server.

        Example:

        $ ldapsearch -Z -h ldap.muquit.com -b "o=muquit.com" \ -P ./ssl "uid=muquit"

        If you inserted the cacert.pem as a trusted CA in iplanet LDAP server's certificate database, it will work. Otherwise the error will look like:

        ldap_search: Can't contact LDAP server SSL error -8172 (Peer's certificate issuer has been marked as not trusted by the user.)

        If search works, use the directive LDAP_CertDbDir to specify the path of ssl directory and the directive LDAP_port to specify the SSL port of your ldap server. Make sure this directory is accessible and readable my Apache.

        Note: certutil can be used as a replacement for OpenSSL we described above as a tool to create/manage certificates. Please read the document of certutil and figure it out yourself.

Using StartTLS for encryption
At this time only OpenLDAP SDK and Server supports StartTLS. That means StartTLS will work if you compile the module with OpenLDAP C SDK with TLS support and your OpenLDAP LDAP server is complied with TLS and configured to support the same. StartTLS is part of LDAPv3 protocol and encryption works over the regular ldap port.

• First of all verify that StartTLS is working with ldapsearch. You can run slapd in debug mode to see what's going on,
  Example:

  # slapd -h "ldap:///" -d 10

  From another window search something with TLS mode:

  $ ldapsearch -ZZ -x -b "dc=foo,dc=com" "(sn=doe)"

  You'll see certificate stuff in hex in server debug messages if TLS is working and your search will succeed. Note, the ldapsearch used above must be the one compiled with TLS with OpenLDAP, not the one from iPlanet.

• Make sure ldap.conf file is readable by the web server, because the TLS code in the module needs to be able to read the CA certificate as specified with TLS_CACERT in your ldap.conf file. If your LDAP and Web servers are running in different machines, you've to make sure that you've the ldap.conf in the directory your OpenLDAP SDK expects and the CA certificate matches with the one, the LDAP server is using as specified with TLS_CACERT in ldap.conf.

• Set LDAP protocol version to 3 in the ldap module with:
  LDAP_Protocol_Version 3

• Turn on StartTLS with
  LDAP_StartTLS On

Note: I personally tested TLS with openLDAP-2.1.25.

Copyright
Copyright © 2003 Muhammad A Muquit, muquit@muquit.com.

URL of this page: http://www.muquit.com/muquit/software/mod_auth_ldap/ssl_tls.html