StartTLS is the name of the standard LDAP operation for initiating TLS/SSL. TLS/SSL is initiated upon successful completion of this LDAP operation. No alternative port is necessary. It is sometimes referred to as the TLS upgrade operation, as it upgrades a normal LDAP connection to one protected by TLS/SSL.

ldaps:// and LDAPS refers to "LDAP over TLS/SSL" or "LDAP Secured". TLS/SSL is initated upon connection to an alternative port (normally 636). Though the LDAPS port (636) is registered for this use, the particulars of the TLS/SSL initiation mechanism are not standardized.

Once initiated, there is no difference between ldaps:// and StartTLS. They share the same configuration options (excepting ldaps:// requires configuration of a separate listener, see slapd(8)'s -h option) and result in like security services being established.

See the Using TLS chapter of the OpenLDAP Software Admin Guide for more information.

  cd /var/myca
  CA.sh -newca

  openssl req -new -nodes -keyout newreq.pem -out newreq.pem

  CA.sh -sign

  cp cacert.pem /usr/local/etc/openldap/cacert.pem
  mv newcert.pem /usr/local/etc/openldap/servercrt.pem
  mv newreq.pem /usr/local/etc/openldap/serverkey.pem
  chmod 600 /usr/local/etc/openldap/serverkey.pem

  TLSCACertificateFile /usr/local/etc/openldap/cacert.pem
  TLSCertificateFile /usr/local/etc/openldap/servercrt.pem
  TLSCertificateKeyFile /usr/local/etc/openldap/serverkey.pem

  TLS_CACERT /usr/local/etc/openldap/cacert.pem

As OpenLDAP clients implement certificate checking, you should make sure that the domain name provided to the client matches that in the server's certificate. Generally, you should use fully qualified domain names on the command line and in the certificate.

RFC 4513 also specifies a means for additional names to be set in a certificate. This is done using the subjectAltName field which is an X.509v3 extension of the basic certificate. This field can be used to list aliases for a server, shared names in a load-balancing setup, or any other desired purpose. A wildcard can also be used, to allow a single certificate to match all hostnames within a given domain.

In the openssl.cnf file, the syntax for this extension is

subjectAltName=DNS:alias1.domain1,DNS:host2.domain2,DNS:*.domain3

Not much of this has been tested in practice and is under evolution. Currently, only slapd works and it has only be tested with Netscape Communicator as a client.

Most things here will be obvious if you already use Apache with mod_ssl or some similar package. If, however, 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, since those packages are better tested and documented.

First of all you need to rebuild OpenLDAP with support for TLS/SSL. 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:

  env CPPFLAGS=-I/path/to/openssl/include \
      LDFLAGS=-L/path/to/openssl/lib-dir \
      configure --with-tls ...

Now, hopefully you have a TLS/SSL-capable OpenLDAP.

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 useful communication will happen, but the side effect is what matters. Neither the server nor the client will notice there is something wrong until the have completed 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.

If you are not experienced in this you may be wondering how to get the CA certificate into Netscape in the first place if it is a CA you created yourself. There are a couple of methods. The easiest method is to use a web server that you may have around. First, arrange for the web server to give the correct MIME type to the certificate using mime.types or including a line in the configuration file like this (for Apache):

AddType application/x-x509-ca-cert .crt

You may have to translate the certificate into a format that Netscape likes, as far as I remember, it won't like the default PEM format used by OpenSSL. You can do it like this:

openssl x509 -in cert.pem -out cert.crt -outform net

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/server-certificate.pem
TLSCertificateKeyFile   /path/to/private-key.pem
TLSCACertificateFile    /path/to/CA-certificates

Now stop slapd and start it again like this:

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

If everything went OK, now open your Address Book on Netscape, right click on the directory, 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.

 Subject Name: CN=myhost.mycompany.com,<DN suffix>
 subjectAltName=DNS:*.mycompany.com,IP:127.0.0.1

Replication using TLS/SSL

Just add few lines into your "syncrepl" session, like:

        starttls=yes
        tls_cacert=/etc/openldap/cacerts/cacert.pem
        tls_cert=/etc/openldap/cacerts/amazon-cert.pem
        tls_key=/etc/openldap/cacerts/amazon-key.pem

For using perfect forward secrecy you have to set configuration directive TLSDHParamFile (see also ITS#7506).

$ openssl dhparam -out /etc/openldap/ssl.key/dhparam 2048
Generating DH parameters, 2048 bit long safe prime, generator 2
This is going to take a long time
.................................................................

TLSDHParamFile /etc/openldap/ssl.key/dhparam

dn: cn=config
changetype: modify
replace: olcTLSDHParamFile
olcTLSDHParamFile: /etc/openldap/ssl.key/dhparam

Problem: slapd does not start up, and you see main: TLS init def ctx failed: -1 in your syslog. Possible solution: check permissions on certificate and private key files. If slapd does not run as root, make sure the private key is readable by the user it does run as. Perhaps also check for SELinux.

Problem: on an old version of openldap (e.g., from a Linux distribution), slapd starts up fine, but when you connect to the ldaps port, ssl negotiation fails and the connection is closed. Possible solution: same as above. (Preferable solution: run the latest release of openldap.)