Table of Contents

1.0 Overview
1.1 Acknowledgment

2.0 Software
2.1 Additional Software

3.0 Install and Configure aeSLAPD

4.0 Certificate Creation

4.1 Self Signed Certificate
4.2 CA Issued Certificate
4.3 Client Certificate

5.0 aeSLAPD Configuration
5.1 Server
5.1.1 Example slapd.conf
5.2 Client
5.2.1 LDAP Client Options
5.2.2 Example ldap.conf
5.3 Schema
5.4 Configuration Summary

6.0 Testing the Server
6.1 SSL Connection Check
6.2 aeSLAPD client commands
6.2.1 Adding Entries
6.2.2 Searching the Directory

7.0 Using TLS

8.0 Summary

The steps taken in this document ensure an LDAP version 3 level of compliance.

1.1 Acknowledgment

Significant credit goes to D. Kent Soper of IBM for the "OpenLDAP SSL/TLS How-To" upon which this is based. 

The Windows version of aeSLAPD version 4.1 LDAP Server must first be obtained from the download site. The aeSLAPD version 4.0 does not have integrated security, and the SSL Tunnel (stunnel) is recommended. If you wish to proceed with the install and setup of version 4.1 and already have an older version, it is strongly suggested that you first uninstall the older version to avoid conflicts.

2.1 Additional Software

Besides aeSLAPD, other development software may be required as dictated by the selected aeSLAPD configuration options. To create and sign certifications required for the server, the OpenSSL version 0.97d or greater is referenced. OpenSSL is included in the stunnel distribution in the download site.

There are two ways to create and install a server certificate. Both methods involve creating the server certificate, sending it to aeSLAPD clients, and making appropriate changes to the aeSLAPD configuration files. Also, both methods involve OpenSSL commands that query the user for information used to create the certificate.

When asked for a 'Common Name', you must enter the fully-qualified distinguished name of the server, e.g. myserver.com, and not 'your name' as is suggested by the OpenSSL prompt. This common mistake is the cause of over 90% of server certificate errors!

4.1 Self Signed Certificate

The first way to create a server certificate is to use OpenSSL and create a self signed server certificate. From a command line:

% openssl req -newkey rsa:1024 -x509 -nodes -out server.pem -keyout server.pem -days 365

aeSLAPD only works with unencrypted keys and the '-nodes' argument prevents encryption of the private key.

The next step would involve configuring aeSLAPD with the location of server.pem. Self-signed certificate usage is discouraged and their configuration is not discussed in detail in this document because of these two downsides:
1. The private key is included in the certificate which will be transported to all aeSLAPD client machines.
2. Interpreting error messages from OpenSSL commands (see section 6.1 "SSL Connection Check".) The following output from an "openssl s_client ..." command is not an actual error (output edited for clarity):

 

Self Signed Certificate Output % openssl s_client -connect localhost:636 -showcerts CONNECTED(00000003) depth=0 /O=Example Org/OU=Example Unit/CN=myserver.com/Email=me@example.com verify error:num=18:self signed certificate verify return:1 ( deleted output ) --- Key-Arg : None Start Time: 1050024298 Timeout : 300 (sec) Verify return code: 18 (self signed certificate)

For these reasons it is strongly recommended to use CA signed certificates!

However, to configure a self-signed certificate, only three entries in slapd.conf need to be set (see section 5.1.1):

TLSCACertificateFile c:/usr/local/pem/cacert.pem TLSCertificateFile c:/usr/local/pem/servercert.pem TLSCertificateKeyFile c:/usr/local/pem/serverkey.pem

Note that sample certificates are pre-loaded in the /usr/local/pem area with the server for test purposes, however, you are strongly advised to obtain actual  certificates from a recognized CA authority, such as RSA or Thawt, or create self-signed certificates using the procedures below.

4.2 CA Issued Certificate

If you have access to a trusted Certificate Authority (CA), then step through the CA process to get a CA certificate, server certificate and server private key. See section 5.0 for info on how to configure your server with these items.

However, if a trusted CA is not available, OpenSSL makes the same process quick and easy.

The steps:
1. Create any directory for creating and signing your certificates.
For example, /var/myca.

 

% mkdir /var/myca

2. Change to /var/myca and run the OpenSSL CA script (in /usr/share/ssl/misc/ on my box):

 

% cd /var/myca/ % /usr/share/ssl/misc/CA.sh -newca CA certificate filename (or enter to create) <enter> Making CA certificate ... Using configuration from /etc/ssl/openssl.cnf Generating a 1024 bit RSA private key ..........................++++++ .........................++++++ writing new private key to './demoCA/private/./cakey.pem' Enter PEM pass phrase: <ca pass> Verifying password - Enter PEM pass phrase: <ca pass again> ----- 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]:Texas Locality Name (eg, city) []:Austin Organization Name (eg, company) [Internet Widgits Pty Ltd]:Example Org Organizational Unit Name (eg, section) []:Example Unit Common Name (eg, YOUR name) []:example.com Email Address []:. %

This creates demoCA/cacert.pem and demoCA/private/cakey.pem (CA cert and private key).

3. Make your server certificate signing request (CSR):

 

% openssl req -newkey rsa:1024 -nodes -keyout newreq.pem -out newreq.pem Using configuration from /etc/ssl/openssl.cnf Generating a 1024 bit RSA private key ..............++++++ ..........................++++++ writing new private key to 'newreq.pem' ----- 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]:Texas Locality Name (eg, city) []:Austin Organization Name (eg, company) [Internet Widgits Pty Ltd]:Example Org Organizational Unit Name (eg, section) []:Example Org Unit Common Name (eg, YOUR name) []:myserver.com Email Address []:ldap@myserver.com Please enter the following 'extra' attributes to be sent with your certificate request A challenge password []: <pass> An optional company name []:. %

The result is newreq.pem.

4. Have the CA sign the CSR:

 

% /usr/share/ssl/misc/CA.sh -sign Using configuration from /etc/ssl/openssl.cnf Enter PEM pass phrase: <ca pass> Check that the request matches the signature Signature ok The Subjects Distinguished Name is as follows countryName :PRINTABLE:'US' stateOrProvinceName :PRINTABLE:'Texas' localityName :PRINTABLE:'Austin' organizationName :PRINTABLE:'Example Org' organizationalUnitName:PRINTABLE:'Example Org Unit' commonName :PRINTABLE:'myserver.com' emailAddress :IA5STRING:'ldap@myserver.com' Certificate is to be certified until Apr 10 18:58:58 2004 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 Certificate: Data: Version: 3 (0x2) Serial Number: 1 (0x1) Signature Algorithm: md5WithRSAEncryption Issuer: C=US, ST=Texas, L=Austin, O=Example Org, OU=Example Unit, CN=example.com Validity Not Before: Apr 11 18:58:58 2003 GMT Not After : Apr 10 18:58:58 2004 GMT Subject: C=US, ST=Texas, L=Austin, O=Example Org, OU=Example Org Unit, CN=myserver.com/Email=ldap@myserver.com Subject Public Key Info: Public Key Algorithm: rsaEncryption RSA Public Key: (1024 bit) Modulus (1024 bit): < ... > Exponent: 65537 (0x10001) X509v3 extensions: X509v3 Basic Constraints: CA:FALSE Netscape Comment: OpenSSL Generated Certificate X509v3 Subject Key Identifier: D0:C0:9D:46:30:65:2A:9C:63:63:6A:E6:FE:E4:AC:F7:21:F8:33:61 X509v3 Authority Key Identifier: keyid:31:2E:0D:FB:A0:74:5A:0B:4B:C5:C4:E0:69:7F:32:6D:AF:46:82:F1 DirName:/C=US/ST=Texas/L=Austin/O=Example Org/OU=Example Unit/CN=example.com serial:00 Signature Algorithm: md5WithRSAEncryption < ... > -----BEGIN CERTIFICATE----- < ... > -----END CERTIFICATE----- Signed certificate is in newcert.pem %

This creates newcert.pem (server certificate signed by CA) with private key, newreq.pem.

5. Now the certificates can be copied to the desired certificate repository and renamed.
aeSLAPD creates a X:/usr/local/pem certificate directory (where X is the drive corresponding to the configuration setup, drive C by default).

 

% copy demoCA\cacert.pem c:\usr\local\pem\cacert.pem % copy newcert.pem c:\usr\local\pem\servercrt.pem % copy newreq.pem c:\usr\local\pem\serverkey.pem

The private key should be made read-only by the user who runs slapd. A 'chown' command will be necessary if the owner of the server key is not the same as the user who runs slapd. The certificates should be publicly readable.

6. Make the CA certificate available to your LDAP clients.
If the client is on the same machine, copy cacert.pem to a location accessible by the client. If clients are on other machines, then cacert.pem will have to be copied to those machines and also made accessible.

---

This process requires a few more steps than creating a self signed certificate, but the benefits gained outweigh any extra time spent creating the CA.

4.3 Client Certificate

Client certificates are created similarly to server certificates. Using the steps outlined in section 4.2 "CA Issued Certificate", the only changes are as follow:

Step 1 and 2: Do nothing ... the CA does not need to be created again. The plan is to use the same CA certificate to sign the client certificate.

Step 3: Same command but actually enter the client's name instead of the server name when prompted for the Common Name. Of course, all of the other responses should be descriptive of the client as well as defining the client's subject DN.

Step 4: Same command with the same resulting files for the cert and private key. Note that the last certificate was renamed in step 5!

Step 5: Now the certificates can be moved to the user's desired certificate repository and renamed.
For example:

 

% copy newcert.pem c:\usr\local\pem\ldap.client.pem % copy newreq.pem c:\usr\local\pem\ldap.client.key.pem

The private key should be read-only by the user who runs the LDAP client. A special common group may be necessary if the owner of the server key is not the same as the user who runs the client. The certificate should be publicly readable.

Step 6: Shouldn't have to do anything here after the previous commands were executed.

With the certificates created, only one more step remains before the server can be started: LDAP configuration.

5.0 aeSLAPD Configuration

5.1 Server

Most of the configuration occurs in the slapd daemon configuration file, slapd.conf. Verify that the file corresponding to your new slapd daemon is the one that is being edited before proceeding. Also, the Admin Guide chapter, "Administration Guide: Configuration File section", goes into more detail than this section and should be reviewed.

5.1.1 Example slapd.conf

The slapd.conf file contains many comments that are very helpful. One of the first states that the file should not be world readable. If it doesn't already have 600 protection mode, make it so.

Here is the example slapd.conf with important comments and entries in bold. It is displayed in its entirety due to the importance of the file.

####################################################################### #  allow bind_v2 ucdata-path C:/usr/local/ucdata include C:/usr/local/etc/schema/core.schema include C:/usr/local/etc/schema/cosine.schema include C:/usr/local/etc/schema/nis.schema include C:/usr/local/etc/schema/inetorgperson.schema schemacheck off TLSCipherSuite HIGH:MEDIUM:+SSLv2  TLSCACertificateFile C:/usr/local/pem/cacert.pem  TLSCertificateFile C:/usr/local/pem/servercrt.pem  TLSCertificateKeyFile C:/usr/local/pem/serverkey.pem  # Use the following if client authentication is required  #TLSVerifyClient demand # ... or not desired at all  TLSVerifyClient never  database ldbm cachesize 1000 dbcachesize 100000 sizelimit 500 timelimit 3600 suffix "o=ACME" rootdn "cn=Directory Manager,o=ACME" rootpw "secret" directory C:/usr/local/database readonly off lastmod off replogfile C:/usr/local/replog include C:/usr/local/etc/slapd.acl.conf #######################################################################

The important directives in slapd.conf are described in Table 2.

Table 2: LDAP Server Directives

DIRECTIVE	VALUE	DESCRIPTION
include	filename	additional configuration files or schema
TLSCipherSuite	cipher suite spec	describes what ciphers will be accepted
TLSCACertificateFile	filename	file that contains the certificates of all trusted CA certs
TLSCACertificatePath	directory	directory containing CA certificates. Usually this or TLSCACertificateFile is used.
TLSCertificateFile	filename	server certificate filename
TLSCertificateKeyFile	filename	server private key filename
TLSVerifyClient	level	Client Authentication: level of checks to perform on incoming client certs ( never | allow | try | demand,hard )
database	type	database definition ( ldbm | shell | null | sql and others )
suffix	dn suffix	DN suffix of queries passed to database backend
rootdn	dn	DN that is not subject to access control for the database
rootpw	password	password or hash of password for rootdn
directory	directory	database directory which must exist prior to starting slapd

There are other variables that may be used. Table 2 summarizes a basic set of server configuration directives.

5.2 Client

The ldap.conf file sets system-wide defaults for LDAP clients. In aeSLAPD, it is sometimes convenient to include the client configuration in the slapd.conf file. 

5.2.1 LDAP Client Configuration Directives

In the following table, user-only refers to ldaprc or .ldaprc file directives and are not global LDAP directives.

Table 3: LDAP Client Directives

DIRECTIVE	VALUE	DESCRIPTION
BASE	dn	default base (DN form) to use when performing ldap operations
BINDDN	dn	default bind DN to use when performing ldap operations user-only
HOST	name[:port]	name of LDAP servers to connect to (separate by spaces)
PORT	number	default port used when connecting to LDAP servers. 636 = SSL!
SIZELIMIT	number	search return limit (0 = unlimited search)
TIMELIMIT	number	search time limit (0 = unlimited time)
TLS	level	whether clients should use TLS by default (never | hard) use of this directive is discouraged; incompatible with LDAPv3 StartTLS request
TLS_CACERT	filename	specifies the file that contains all of the CA certificates the client recognizes
TLS_CACERTDIR	directory	used if TLS_CACERT fails
TLS_REQCERT	level	specifies what checks to perform on a server certificate ( never | allow | try | demand,hard )
TLS_CERT	filename	Client Authentication: specifies the client certificate user-only
TLS_KEY	filename	Client Authentication: specifies the private key for TLS_CERT entry user-only

5.2.2 Example ldap.conf

Example ldap.conf:

# # Global LDAP settings # # See ldap.conf(5) for details # This file should be world readable but not world writable. HOST myserver.com PORT 636 TLS_CACERT /etc/ssl/certs/cacert.pem TLS_REQCERT demand

This configuration will connect to ldaps://myserver.com:636 without the need to specify the host and port in client commands.

5.3 Schema

In slapd.conf, schema are listed near the top of the file. Initial slapd.conf files may contain one schema with several commented schemas. The example slapd.conf file added a few other schemas found in the schema directory.

Example slapd.conf schema entries:

include /usr/etc/aeSLAPD/schema/core.schema include /usr/etc/aeSLAPD/schema/cosine.schema include /usr/etc/aeSLAPD/schema/inetorgperson.schema include /usr/etc/aeSLAPD/schema/misc.schema include /usr/etc/aeSLAPD/schema/aeSLAPD.schema

No additional configuration is necessary to get the server up and running.

5.4 Configuration Summary

There are varying degrees of SSL configuration one may institute. Table 3 summarizes the various directives and values that can be used to set up basic server side SSL ("basic") up to strict server side and client side SSL ("best").

Table 4: SSL/TLS Directives

File	Directive	Basic	OK	Good	Better	Best
slapd.conf	TLSCACertificateFile or TLSCACertificatePath	x	x	x	x	x
	TLSCertificateFile	x	x	x	x	x
	TLSCertificateKeyFile	x	x	x	x	x
	TLSCipherSuite	-	x	x	x	x
	TLSVerifyClient	never	never	allow	try	demand
ldap.conf	TLS_CACERT	-	x	x	x	x
	TLS_CACERTDIR (optional)	-	x	x	x	x
	TLS_REQCERT	never	never	allow	try	demand
ldaprc or .ldaprc	TLS_CERT	-	-	-	x	x
	TLS_KEY	-	-	-	x	x

KEY
- : no entry
x : use directive and enter filename or directory
Note: TLSVerifyClient default is 'never' and TLS_REQCERT default is 'demand'

6.0 Testing the Server

 

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

This starts the server running on the two default ports of 389 (ldap://) and 636 (ldaps://). On Windows, the slapd daemon resides in the default aeSLAPD install directory. The "-d127" is a debug level and a value of '-1' will produce max debug output.

If alternate ports are desired, you can also start the server like this:

 

% slapd -d9 -h "ldaps:/// ldaps://:12345"

This command only starts the server on SSL ports 636 and 12345. It also uses a debug level of '9' which will display SSL connect information (and less of the other gorp associated with '-d -1').

How do you know if the server is really doing anything? OpenSSL has a utility that verifies the SSL connection and you can also add some entries and then search for them via an aeSLAPD client.

6.1 SSL Connection Check

To check the SSL connection, try this command:

 

% openssl s_client -connect localhost:636 -showcerts -state -CAfile <ca cert>

If the LDAP server is not executing on your client machine, "localhost" must be substituted with the server name, e.g. "myserver.com".

Also, to verify the server certificate, you must provide the client CA certificate to the CAfile argument. Why does the CA certificate have to be specified if it already is in ldap.conf? Because the command is an OpenSSL client command and not an LDAP client command.

The command can also be used to verify a TLS connection on non-ldaps ports, e.g. port 389.

Good output looks like this (edited):

OpenSSL Output Using Server Side SSL

% openssl s_client -connect myserver.com:636 -showcerts -state \ -CAfile cacert.pem CONNECTED(00000003) SSL_connect:before/connect initialization SSL_connect:SSLv2/v3 write client hello A SSL_connect:SSLv3 read server hello A depth=1 /C=US/ST=Texas/L=Austin/O=Example Org/OU=Example Unit/CN=example.com verify return:1 depth=0 /C=US/ST=Texas/L=Austin/O=Example Org/OU=Example Org Unit/CN=myserver.com/Email=ldap@myserver.com verify return:1 SSL_connect:SSLv3 read server certificate A SSL_connect:SSLv3 read server done A SSL_connect:SSLv3 write client key exchange A SSL_connect:SSLv3 write change cipher spec A SSL_connect:SSLv3 write finished A SSL_connect:SSLv3 flush data SSL_connect:SSLv3 read finished A --- ( ... Certificate chain output deleted ... ) --- No client certificate CA names sent --- SSL handshake has read 1804 bytes and written 314 bytes --- New, TLSv1/SSLv3, Cipher is DES-CBC3-SHA Server public key is 1024 bit SSL-Session: Protocol : TLSv1 Cipher : DES-CBC3-SHA Session-ID: E7E1D275B86A9695BEB1B15E4C0E681F55505016A6AC9F4E55B88FD... Session-ID-ctx: Master-Key: 2DC9724A4978BEF82B7FCCE6FA3E72C55C3D6A915AD7B7FC8E0F... Key-Arg : None Start Time: 1050452423 Timeout : 300 (sec) Verify return code: 0 (ok) ---

The command will hang after the final return code output. This is normal. "Control-c" will end the command.

The line "No client certificate CA names sent" is indicative of a server side SSL set up. If client authentication had been configured, the OpenSSL command and output would resemble this:

OpenSSL Output Using Client Authentication

% openssl s_client -connect myserver.com:636 -state \ -CAfile cacert.pem \ -cert client.cert.pem \ -key client.key.pem CONNECTED(00000003) SSL_connect:before/connect initialization SSL_connect:SSLv2/v3 write client hello A SSL_connect:SSLv3 read server hello A depth=1 /C=US/ST=Texas/L=Austin/O=Example Org/OU=Example Unit/CN=example.com verify return:1 depth=0 /C=US/ST=Texas/L=Austin/O=Example Org/OU=Example Org Unit/CN=myserver.com/Email=ldap@myserver.com verify return:1 SSL_connect:SSLv3 read server certificate A SSL_connect:SSLv3 read server certificate request A SSL_connect:SSLv3 read server done A SSL_connect:SSLv3 write client certificate A SSL_connect:SSLv3 write client key exchange A SSL_connect:SSLv3 write certificate verify A SSL_connect:SSLv3 write change cipher spec A SSL_connect:SSLv3 write finished A SSL_connect:SSLv3 flush data SSL_connect:SSLv3 read finished A --- ( ... Certificate chain output deleted ... ) subject=/C=US/ST=Texas/L=Austin/O=Example Org/OU=Example Org Unit/CN=myserver.com/Email=ldap@myserver.com issuer=/C=US/ST=Texas/L=Austin/O=Example Org/OU=Example Unit/CN=example.com --- Acceptable client certificate CA names /C=US/ST=Texas/L=Austin/O=Example Org/OU=Example Unit/CN=example.com --- SSL handshake has read 1916 bytes and written 2102 bytes --- New, TLSv1/SSLv3, Cipher is DES-CBC3-SHA Server public key is 1024 bit SSL-Session: Protocol : TLSv1 Cipher : DES-CBC3-SHA Session-ID: 96B9C18DAC585050EDC30C1BB7792A6C33C44F2DDB98EBAEBEC68B270... Session-ID-ctx: Master-Key: 540C7F9FAD1CBE503C9A3BA5D47A76A005BDEEEB1908F270669D32... Key-Arg : None Start Time: 1052237883 Timeout : 300 (sec) Verify return code: 0 (ok) ---

Note the extra SSL handshake output in bold.

6.2 aeSLAPD client commands

aeSLAPD has several client commands. Most common: ldapsearch, ldapadd, ldapmodify, and ldapdelete. This document will show example commands but will not explain the details of their operation. Please consult the online man pages for more details.

The sections that follow show examples that add entries to the LDAP directory and then search the directory for various entries.

6.2.1 Adding Entries

Using sdmgr.exe, or any editor, copy and paste the following LDIF file to "init.ldif". Any leading and trailing white space should be eliminated. Change the DN values to mirror your slapd.conf suffix values. For example if your suffix is "dc=ldap,dc=com", then the DN entries below would be "dn: dc=ldap,dc=com".

init.ldif

#init.ldif dn: dc=myserver,dc=com objectclass: dcObject objectclass: organization o: Example Org dc: myserver dn: cn=my-name,dc=myserver,dc=com objectclass: organizationalRole cn: my-name dn: ou=my system,dc=myserver,dc=com objectclass: organizationalUnit ou: my system description: Test organizational unit to hold admin user dn: cn=mr admin,ou=my system,dc=myserver,dc=com objectclass: person userPassword: testpass description: mr admin test user cn: mr admin sn: admin

Now add the LDIF entries to the LDAP database (using your rootdn):

% ldapadd -x -D "cn=Manager,dc=myserver,dc=com" -W -f init.ldif

You will be prompted for the rootpw because of the "-W" argument. If successful, you will see four "adding new entry <entry>" lines.

To ensure an SSL connection, you can specify a host with: "-H ldaps://myserver.com". This argument is needed if the host is not set on a stand alone client.

6.2.2 Searching the Directory

Use the following commands to search the directory. To understand the different command flags, consult the man pages for ldapsearch. In all of the commands that follow, the argument ' -D "cn=Manager,dc=myserver,dc=com" ' is necessary because of this access block in slapd.acl.conf:

access to * by self write by users read by anonymous auth

If this block had been commented out as in a default slapd.conf , then none of the "-D" arguments would be needed in the ldapsearch commands here and in the following sections.

Return all entries

Client on same machine:

% ldapsearch -x -b 'dc=myserver,dc=com' -D "cn=Manager,dc=myserver,dc=com" '(objectclass=*)' -W

Stand alone LDAP client:

% ldapsearch -x -b 'dc=myserver,dc=com' -D "cn=Manager,dc=myserver,dc=com" '(objectclass=*)' -H ldaps://myserver.com -W

The output should look like:

version: 2 # # filter: (objectclass=*) # requesting: ALL # # myserver, com dn: dc=myserver,dc=com objectClass: dcObject objectClass: organization o: Example Org dc: myserver # my-name, myserver, com dn: cn=my-name,dc=myserver,dc=com objectClass: organizationalRole cn: my-name # my system, myserver, com dn: ou=my system,dc=myserver,dc=com objectClass: organizationalUnit ou: my system description: Test organizational unit to hold admin user # mr admin, my system, myserver, com dn: cn=mr admin,ou=my system,dc=myserver,dc=com objectClass: person userPassword:: dGVzdHBhc3M= description: mr admin test user cn: mr admin sn: admin # search result search: 2 result: 0 Success # numResponses: 5 # numEntries: 4 %

Return some entries (part one)

Command with output:

% ldapsearch -x -b 'cn=my-name,dc=myserver,dc=com' -D"cn=Manager,dc=myserver,dc=com" -H ldaps://myserver.com '(objectclass=*)' -w secret version: 2 # # filter: (objectclass=*) # requesting: ALL # # my-name, myserver, com dn: cn=my-name,dc=myserver,dc=com objectClass: organizationalRole cn: my-name # search result search: 2 result: 0 Success # numResponses: 2 # numEntries: 1

Return some entries (part two)
Command with output:

% ldapsearch -x -b 'ou=my system,dc=myserver,dc=com' -D"cn=Manager,dc=myserver,dc=com" -H ldaps://myserver.com '(objectclass=*)' -w secret version: 2 # # filter: (objectclass=*) # requesting: ALL # # my system, myserver, com dn: ou=my system,dc=myserver,dc=com objectClass: organizationalUnit ou: my system description: Test organizational unit to hold admin user # mr admin, my system, myserver, com dn: cn=mr admin,ou=my system,dc=myserver,dc=com objectClass: person userPassword:: dGVzdHBhc3M= description: mr admin test user cn: mr admin sn: admin # search result search: 2 result: 0 Success # numResponses: 3 # numEntries: 2

7.0 Using TLS

TLS requires the same configuration settings as SSL. Upon examination, all of the important SSL directives start with "TLS" in section 5.4 "Configuration Summary" which should have tipped you off to the dual relationship.

However, simply accessing ldap://:389 does not ensure a TLS encrypted connection. Accessing ldaps:// is not a TLS connection either. In order to use TLS over an ldap:// connection, add a ldap_start_tls_s() call to your client code:

 

int rc, port=389; int ldap_version=LDAP_VERSION3; LDAP *ld; ... ld=ldap_init("myserver.com", port); ldap_set_option(ld, LDAP_OPT_PROTOCOL_VERSION, &ldap_version); rc = ldap_start_tls_s(ld, NULL, NULL); ...

Another difference between SSL and TLS in the above code is that SSL doesn't use ldap_init(). Instead it uses ldap_initialize(**LDAP, string) where the string is a URI, e.g. "ldaps://myserver.com:636". Attempting to use ldap_init() over SSL will cause a broken pipe error. Also, attempting to call ldap_start_tls_s() when an SSL connection is already utilized will also be in error.

Another TLS method that can be used is to add a "-Z" or "-ZZ" flag to client commands:

 

% ldapsearch -x -b 'dc=myserver,dc=com' -D "cn=Manager,dc=myserver,dc=com" '(objectclass=*)' -H ldaps://myserver.com -W -ZZ ...

The "-ZZ" flag forces TLS handshake to be successful. The single "-Z" flag tries to enable TLS and will proceed without using encrypted connections if the TLS handshake fails.

It would be nice to set a TLS configuration directive in either slapd.conf or ldap.conf but my attempts to do so have not resulted in a successful TLS handshake in the server output. aeSLAPD documentation does suggest using a "Start TLS" call in a configuration file which has not been successful for me.

Although enabling an SSL connection to a server is straight forward if the steps outlined in this document are followed, problems can arise when trying to execute the LDAP client. aeSLAPD is sophisticated software with several nuances that take experience to understand and use correctly. Execution errors can arise when the following occurs:

• Incorrect slapd.conf and ldap.conf entries.
• Punctuation errors between slapd.conf entries (suffix, rootdn, rootpw) and the aeSLAPD client commands.
• Accessing aeSLAPD server ports that have not been started.
• Calling a "start tls" command on an SSL port. Calling this command on any SSL/TLS port is an error.
• Making changes to the wrong slapd.conf and ldap.conf configuration files.
• Incorrect password.
• Not using a fully qualified domain name in the server certificate (very common!).