Learn LDAP - TLS/SSL Configuration

#Introduction

In episode 15 you realized that an unsecured simple bind sends passwords in the clear, and that olcSecurity: ssf=1 only makes sense if there's a security layer to enforce. Episode 16 installs that layer itself: TLS. You'll prepare certificates, decide between StartTLS and LDAPS, configure the server and the client, and prove the encryption works with ldapsearch -ZZ.

#Why TLS for LDAP

TLS turns LDAP from a text protocol into an encrypted channel. Four benefits:

Encryption in transit — passwords and data can't be sniffed on the network.
Server authentication — clients verify they're talking to the right server, not an impostor.
Client authentication (optional) — with mutual TLS, the server also verifies client certificates; this becomes the basis of SASL EXTERNAL in episode 17.
Integrity protection — data changes in transit are detected because every message is protected by a cryptographic checksum.

Without TLS, the episode 15 threats — eavesdropping and man-in-the-middle — apply in full, even on internal networks.

#Certificate Requirements

To run TLS on slapd, you need a set of certificate files:

Component	Contents	Example path
CA certificate	the issuing authority's certificate (or your own root CA)	`/etc/ssl/certs/ca.crt`
Server certificate	certificate for the server's hostname	`/etc/ssl/certs/slapd.crt`
Certificate key	the private key belonging to the server certificate	`/etc/ssl/private/slapd.key`
Certificate chain	intermediate CAs up to the root, if any	merged into the server cert
Validation	client checks the certificate against a trusted CA	via `TLS_CACERT`

In a lab, you can be your own CA. Create a self-signed certificate for the server with openssl:

Creating a self-signed certificate

openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout slapd.key -out slapd.crt -days 365 \
  -subj "/CN=ldap.example.com"
sudo chown root:ssl-cert slapd.key

On Debian and Ubuntu, the ssl-cert group lets slapd read /etc/ssl/private; make sure the private key is in that group. The common name (CN) or Subject Alternative Name must match the hostname clients use when connecting, otherwise validation will fail.

#StartTLS versus LDAPS

Two ways to put TLS on LDAP:

StartTLS (port 389) — the connection starts plain, then the client asks to upgrade to TLS with a StartTLS command on the same connection.
LDAPS (port 636) — TLS is active from the moment the connection is established, no upgrade step.

Aspect	StartTLS (389)	LDAPS (636)
Port	389	636
Initiation	upgrade in the middle of the connection	encrypted immediately
Standard	LDAP standard, interoperable	legacy practice, not an RFC standard
Advantage	one port for everything, can serve non-TLS when enabled	mentally simple
When to use	modern default	legacy systems or connections that need explicit TLS from the start

StartTLS is preferred because it uses only one port and can still serve non-TLS connections if olcSecurity allows. However, many legacy integrations demand LDAPS. OpenLDAP 2.5 supports both at once, so you don't have to choose.

#TLS Configuration on the Server

Certificates and TLS settings go on the cn=config entry:

olcTLSCertificateFile and olcTLSCertificateKeyFile — required; the server certificate and key pair.
olcTLSCACertificateFile — the CA that validates clients when mutual TLS is enabled.
olcTLSCipherSuite — the list of allowed ciphers; this is a common example, adjust to your organization's policy.
olcTLSVerifyClient — never for one-way authentication; try or demand when clients must also present certificates.

#TLS Configuration on the Client

On the client side, configuration lives in /etc/ldap/ldap.conf (and per-user ~/.ldaprc):

TLS_CACERT points to the CA the client trusts. TLS_REQCERT determines the attitude toward the server certificate:

Value	Behavior
`never`	doesn't verify the certificate at all
`allow`	verifies if presented, continues if not
`try`	verifies when possible, continues on failure
`demand`	requires a valid certificate, drops the connection otherwise

demand is the correct value for production — anything below it opens the door to man-in-the-middle attacks.

#Testing TLS

Prove the encryption actually works:

Testing with ldapsearch and openssl

ldapsearch -x -H ldap://ldap.example.com -ZZ \
  -b dc=example,dc=com cn
openssl s_client -connect ldap.example.com:636 \
  -CAfile /etc/ssl/certs/ca.crt

ldapsearch -ZZ demands StartTLS — the connection fails if the server doesn't support the upgrade. openssl s_client -connect ...:636 checks the LDAPS handshake directly and shows the certificate chain; verify that verify return code reads ok. For negotiation debugging, run slapd with olcLogLevel: conns,stats and watch the TLS messages in the log.

Warning

Never deploy TLS_REQCERT never or -Z (singular, which only allows TLS) to production. -Z is optional — the connection still goes plain if TLS isn't available. Always use -ZZ when enforcing, and demand as TLS_REQCERT.

#Closing

In this episode 16 you secured LDAP with TLS: the four benefits of transport encryption, preparing a CA, server certificate, key, and validation; the difference between StartTLS on port 389 and LDAPS on port 636; the olcTLSCertificateFile, olcTLSCertificateKeyFile, olcTLSCACertificateFile, olcTLSCipherSuite, and olcTLSVerifyClient configuration; client settings with TLS_CACERT and TLS_REQCERT; and testing with ldapsearch -ZZ and openssl s_client.

Key takeaways:

Certificates must match the hostname — a mismatch fails validation even with the correct CA.
StartTLS on 389, LDAPS on 636 — both are valid; StartTLS is the modern choice.
TLS_REQCERT demand and -ZZ — non-negotiable for production.
Guard the private key's access — the ssl-cert group on Debian protects /etc/ssl/private.

In the next episode, episode 17, the TLS layer you just installed becomes the stage for SASL & external authentication — Kerberos-based GSSAPI authentication and SASL EXTERNAL using client certificates, then integration with PAM, NSS, and SSSD.