Using TLS/SSL with slapd, a quick guide

[Julio Sánchez Fernández <j_sanchez@stl.es>]

Let me give you a quick guide on using SSL with slapd.  I will presume
your client is Netscape Communicator and that you are using OpenSSL,
nothing else has been tested.  Most things will be obvious or trivial
if you are already using mod_ssl or somesuch.  If this is your first
project with SSL, then I recommend you play a little bit with Apache
mod_ssl and OpenSSL until you feel confident.

First of all you need to rebuild OpenLDAP with support for TLS.  This
can be automatic or it may require some help at configure time.  You
may have to use --with-tls and you may need to do something like:

	CPPFLAGS=-I<path-to-openssl-include-dir> \
	LDFLAGS=-L<path-to-openssl-lib-dir> \
	configure --with-tls <other-options>

The above is valid for most Bourne shells, use setenv on csh and the
like to set the above environment variables to whatever you need.

Then 'make depend; make' to rebuild OpenLDAP and 'make install' to install
it.  Be careful if you have dynamic libraries for OpenSSL and you are
using nss_ldap or pam_ldap linked dynamically with libldap and liblber:
your system may become hosed as soon as you install the new libraries.
If this is the case, you will have to rebuild nss_ldap and pam_ldap so
that they know they have additional dependencies on libssl and libcrypto.

Now, hopefully you have a TLS-capable OpenLDAP.  Forget for the time being
about the clients provided: they will not do TLS yet (though you can use
the client-mode stunnel to workaround this).  However, slapd will *if*
you set up everything right.

You need a certificate for your server.  That certificate will have to be
trusted by your Netscape client and this will have to be prepared
beforehand.  You may be used to Netscape prompting a dialog box so that
you decide to trust an unknown certificate and such: forget about it,
this will not happen with LDAP: either everything is properly setup or
it will not work (typical error from Netscape is 0xFFFFFFFF).

There are a number of ways you can make this happen.  You can have
Netscape learn the certificate of your server by abusing the HTTP dialog.
For this, open URL https://yourserver:636 and the dialog will appear,
there you can select to accept that server certificate for this and all
future sessions.  You can only do this when you have your slapd running
with the right magic.  Of course, the protocols will not match and
no results will be returned, but the side effect is what matters.
Neither the server nor the client know there is something wrong until
the have done the negotiation and, by then, you already got the dialog
and have installed the certificate in the client.

If your certificate is directly signed by a CA that is itself installed in
your browser and marked as trusted, it will work too.

If your certificate is indirectly signed by a CA that is installed and
trusted in the browser, that will work, but you will have to tell slapd
to send the intermediate CA certificates to the browser as I explain
below.

I think I have tried all methods above and all of them worked for me.
Then, I may be wrong.

OK, if you have a certificate and a private key pair ready, then we can
proceed.  First the bad news: you need a copy of the private key in the
clear: it cannot be encrypted, slapd will not prompt for the decoding
password.  So be careful with the permissions on that file.  Now include
the following lines in slapd.conf:

TLSCertificateFile      <path-to-your-pem-server-certificate>
TLSCertificateKeyFile   <path-to-your-pem-private-key>
TLSCACertificateFile    <file-with-your-CA-certificates>

The latter will be needed if there are multiple CAs from the root to
the server certificate.  I think it can be left out if only one level
is used, but I don't think I tried it, so if you want to play safe,
catenate together your root certificate and all intermediate CA
certificates (PEM format!!!) in a file and use that.

Now stop slapd and start it again like this:

	slapd -h "ldap:/// ldaps:///"

By default, it will now listen on port 389 for LDAP and 636 for LDAP over
SSL.  You may leave out the first URL and it will not talk normal LDAP
anymore.  You can use option -P to change the default port for LDAPS or
you can use a specific port on the URL.

If everything went OK, now open your Address Book on Netscape, right
click on the directoy, choose properties and select the secure option.
If you were running on the standard port 389, the port will change
automatically to 636, otherwise set the correct port.  Do not set
'Login with Name and Password', there is some problem there that
has not been diagnosed yet.  Click on accept and you are all set,
do a search and the results will appear on your Address Book window.
The lock on the lower left corner will show as closed.

If things did not work alright, stop slapd and start it with debugging
(see option -d) and read the output, I have tried to provide a complete
error trace from OpenSSL, it should be apparent what the problem is.
If it isn't, then let us know.

Ok, I think that's it.

Happy TLSing,

Julio