LINUX distribution

The configurations were tested on the following environment, for others check working path, and available tested release.
See our best practices to install services and keep them up to date.

fedora-release-6-4 

openldap-2.3.30-2.fc6
openldap-clients-2.3.30-2.fc6
openldap-devel-2.3.30-2.fc6
openldap-servers-2.3.30-2.fc6
openldap-servers-sql

openssl-0.9.8b-8
cyrus-sasl-2.1.22-4
selinux-policy-targeted-2.4.6-1.fc6 

fedora-release-5-5  

openldap-2.3.19-4
openldap-clients-2.3.19-4
openldap-devel-2.3.19-4
openldap-servers-2.3.19-4
openldap-servers-sql-2.3.19-4

openssl-0.9.8a-5.4
cyrus-sasl-2.1.21-10
selinux-policy-targeted-2.3.7-2.fc5

PERMISSIONS

Check file permissions on openldap paths

Handy Hint It is wise tu run slapd (openLDAP daemon) in a chroot environment. It is out of the scope of this document to describe how. But keep in mind that when you copy (or mount --bind) your directories and files, you should keep permissions and SELinux context. The recommended chroot path for openldap is "/var/ldap/chroot"

SELINUX context

See our best practices to keep correct file paths and remember that SELinux context is inherited from the directory level. It means that if you change a default directory, you should check the context of the newly created one.

Check files context on path /etc/openldap

Check files context on path /etc/pki/tls

Others security features

Be Careful Remember that with certificates, acceptance is controlled by the Certification authorities (CA) certificates you store in your CA path (i.e: /etc/pki/tls/certs). A default bundle file of CA certs is located at "/etc/pki/tls/certs/ca-bundle.crt". Also remember that if your host private key is stolen, one can impersonate your host over the internet. Especially if you use all purposes certificates.

Enabling SSL - LDAPS

You need to attach certificates and related stuff to the slapd service. That is you have to perform the following steps:

1. Obtain a certificate for your host
   • Choose if you want to use an existing one existingCERT
   • Check the DNS naming scheme of your hosts and services
   • Adopt an external naming scheme, or define one for your OSI names osiNames
   • Check your host name, it defaults to your FQDN (ie:ldap.example.com)hostname
     • Configure virtual host name if desired virtualHostname
     • Update DNS or DNSSEC accordingly
   • Prepare a PKCS10 certificate request or go to an online certification enrollment
     • Choose between self signed certificates or certificates from an external CA
     • Use openssl command line opensslCli or CA web form
     • Enter your FQDN host name (or virtual host) as CN (Common name) ie:ldap.example.com fillingDN
     • Check that you request a certificate for client and server authentication purposes certsPurpose
   • Retrieve your signed certificate certRetrieve
     • Check it is in PEM format (base 64 encoded) and convert it if necessary
     • Verify your certificate purpose certVerify
     • check the content of your signed certificate certCheck
   • Get your associated certificate key keyRetrieve
2. Retrieve the Certification Authority certificate(s)CAcertsRetrieve
3. Retrieve the Certification Authority CRL (certificate revocation list) CRLcertsRetrieve
4. Update your certificates repository
   • copy your private key in /etc/pki/tls/private.ldap
   • copy your public key in /etc/pki/tls/certs
   • copy the CA public key in /etc/pki/tls/certs
   • update certificate repository with CRLs in /etc/pki/tls/crls CRLcertsStore
   • link the CRL's in /etc/pki/tls/certs settingCRL
   • Setup a cron job to retrieve regularly updated CRLs CRLcertsCron
   • Decide if you want to keep default Certification authorities bundled file certsBundle
5. Choose your SSL port (default: 636)
   • Attach a virtual server to the SSL port if needed portSSL
6. update /etc/openldap/slapd.conf
   • TLSCertificateFile /etc/pki/tls/certs/ldap.crt
   • TLSCertificateKeyFile /etc/pki/tls/private.ldap/ldap.key
   • TLSCACertificateFile /etc/pki/tls/certs/cacert.pem
   • TLSCACertificatePath /etc/pki/tls/certs
   • TLSCRLCheck peer
7. Check your sldapd configuration (command: slaptest -v)
8. Start or restart ldap (command: service ldap restart)
9. Check log files for errors (command: tail /var/log/openldap.log)
10. Check for proper SSL activation (with ldaps: // ldap.example.com)
    
    

---

Return to top of page topLDAPS

Choose if you want to use an existing one

You MAY choose an already existing SSL certificate for your host or your virtual host. One of these could be used for HTTP or SENDMAIL SSL.

Be Careful You MAY use the same certificate public file providing its directory is world readable and searchable, and the certificate is world readable. You MUST copy the private key of the certificate to a file having only read right for LDAP user, unless you define the sendmail special feature confDONT_BLAME_SENDMAIL (in case of sharing with sendmail).

---

Return to top of page topLDAPS

Adopt an external naming scheme, or define one for your OSI names

OSI stands for "Open Standards for Interconnection" from ISO / ITU
an OSI name is called a "Distinguished name" which is used in all OSI related technologies such as

• Certificates (X509)
• LDAP directories including Microsoft Active directory (X500)
• Military and aeronautical messaging systems (X400)

A "Distinguished name" (DN) is a collection of one or more of the following components

• CN Common name
• OU Organisation Unit
• O Organization
• C Country
• and many others like "gn givenname","sn surname","l location" ......

Example DN
DN: cn=My_full_FQDN_name,ou=Related_Organisation_Unit,ou=other_related_unit,o=Company_name,c=country

or with the alternate DC scheme mostly used in directories.

DN:cn=My_full_FQDN_name,ou=Related_Organisation_Unit,ou=other_related_unit,dc=example,c=com

Useful Information If you want to participate in the openLDAP referral service (ldap://root.openldap.org) you MUST use the DC scheme and set appropriate SRV records in your DNS.

Common meanings of OU are as follows:

• OU=Hosts
• OU=People # users
• OU=Services # Daemons

openOSI also uses in its naming scheme:

• OU=VirtualHosts
• OU=VirtualPeople # nicknames
• OU=PKI # Certification authorities

In principle you are free to use what you want as DN components value, unless you request a certification authority to certify these values. That is unless you intend a public use of these names to participate in an Internet of trust (similarly to the dns - Domain name system).

You MUST use a "Distinguished name" to generate a certificate request, see fillingDN

For additional information check the various OSI X500 and RFC

Useful Information There could be links between DNS and OSI naming scheme, especially when domain components are used for distinguished names. Some people stores DNS DB in an LDAP directory (like Microsoft optionally). Most people don't in order to keep loosely coupling between DNS and Directories. There is an interesting use of LDAP directories for certificates when storing these certificates and their revocation list (CRL) in the directories. Therefore you MAY imagine a scheme that facilitate directory searching for your certificate retrieval. That is unless you use a third part directory like openOSI (directory.opensosi.org). openOSI practice is to store your certificate in virtual OU unit according the openOSI naming scheme without relying on the distinguished name of the certificate. See certCheck, CAcertsRetrieve, and CRLcertsRetrieve

---

Return to top of page topLDAPS

Check your FQDN host name

---

Configure virtual host name if desired

The idea here is to have a different name than the hostname for the ldap service. This is why we call it a virtual host. Details about real LDAP virtual hosting is out of the scope of this document.

Be Careful By nature the SSL - TLS protocol doesn't support virtual hosting on the same port (636 by default for LDAPS), unlike unencrypted http protocol. This is because the SSL connection is checked before it's virtual name processing. If you want to enable SSL virtual hosts you should choose alternate ports or network interface (one for each slapd instance), see portSSL.

You configure the virtual hostname in /etc/openldap/slapd.conf

---

Return to top of page topLDAPS

Use openssl to generate a certificate request ldap.csr

The outputs will be

1. a private key, without password, with RSA coding and 1024 bit coding key named ldap.key
2. a PKCS10 format certificate signing request named ldap.csr

Option You may want to first generate the private key, then the signing request [root@example-host conf.d]# openssl genrsa -out ldap.key 1024 [root@example-host conf.d]# openssl req -nodes -new -key ldap.key -out ldap.csr You may also want a shorter key length (i.e: 512 instead of 1024), if exchanged data are not sensitive, processing will be faster, unless you have SSL accelerator hardware.

To verify the content of your signing certificate request (CSR)

For more detailed information hit openssl request reference

---

Return to top of page topLDAPS

Filling your certificate subject

This subject is bind to the cryptographic material of your certificate. Here is the real nature of a certificate. Therefore a certificate for ldap service should be bind to the virtual host running the service
see virtualHostname.

Assign your host name to common name component. ie: cn=ldap.example.com
The others, optional, parts of the subject are

1. Either a set of Organisation name and Country code_ ie: o=My_Organisation, c=US
2. Either a set of many Domain Components ie: "dc=example,dc=com" standing for example.com
3. Optionally you may have organisation units ie: ou=Finance or ou=hosts or ou=services
4. Optionally you may have additional cn as used by Microsoft naming scheme (cn=Host_Name,cn=Domain Controller,..)

Finally you obtain your subject value called a Distinguished Name abreviated as DN

1. example 1: cn=ldap.example.com
2. example 2: cn=ldap.example.com,o=My_Organisation,c=US
3. example 3: cn=ldap.example.com,dc=example,dc=com
4. example 4: cn=ldap.example.com,ou=Services,dc=example,dc=com

This is the OSI naming scheme, also used in LDAP directories (like Microsoft AD) and X400 mail systems. If your certificate is stored in an LDAP directory, it could be stored in the same DIT (Directory Information Tree) as the one of it's Distinguished name, or it could be stored under another DIT.
openOSI stores the public signed certificates this way for class 1

• DIT is "ou=VirtualHosts,dc=openosi,dc=org"
• ObjectClass=top, ObjectClass=Device, ObjectClass=StrongAuthenticationUser
• cn=ldap.example.com - The cn value of certificate subject
• userCertificate="Binary form of your public certificate"

That is, if requesting an openOSI signed certificate, there is no need to fill something else than the common name as your host name, because openOSI will not certify additional information for its class 1 certification. Others parts like "o=My_Organisation, c=US" will be removed from the certificate unless you require a class 2 certificate (not available for now and subject to peer agreement).

Handy Hint If you choose to generate yourself a certificate request (CSR) using openssl or any other tools including Microsoft windows based tools it could be mandatory to fill all attributes like country, organisation, organisation unit, location .... We recommend you enter as few information as possible, entering blanks where appropriate, because a certification authority is supposed to verify all the requested attributes. This is not necessary for LDAP operations and is costly (however the CA could silently drop some of your unverified attributes). Many HOW TO on internet suggest you create self signed certificates which avoid this problem. We don't recommend this, unless you have the ability to manage a complete secure PKI (Public Key Infrastructure) to handle secure storage, directories, renewals and revocations. openOSI offers you a free open source PKI infrastructure for class 1 / 2 certification (you have also others open source PKI).

Here is the openssl dialog

---

Return to top of page topLDAPS

Verify your certificate purpose: client/server authentication

• If you use an on line submission, choose the appropriate submission form
• If you generate your request use the appropriate template
  • If you use openssl check /etc/pki/tls/openssl.cnf for
    • nsCertType= server,client
    • keyUsage= digitalSignature,keyEncipherment
    • default is to have nothing which allows all usage for your certificate, avoid this!

Key usage should be:

• Digital signature
• Key encipherment
• Data encipherment

Extended key usage should be (see RFC 3280):

• Server auth(include OID=1.3.6.1.5.5.7.3.1)
• client auth (include OID=1.3.6.1.5.5.7.3.2)

---

Return to top of page topLDAPS

Retrieve your signed certificate

You can retrieve your certificate from an on line certification authority or from an LDAP directory. In the later case you could only retrieve the public key, providing the private key was generated locally.

• For an on line retrieval go the appropriate URL of the certification authority
• For an LDAP retrieval, launch an LDAP query
  • ie: for openOSI LDAP directory use the following URI
    

    ldap://directory.openosi,org/ou=VirtualHost,dc=openosi,dc=org?userCertificate?one?cn=ldap.example.com

---

Return to top of page topLDAPS

Verify your certificate purpose

You may use several tools to edit your certificate, including Windows, providing the file have an appropriate file extension corresponding to its format(.crt for DER format which is different from PEM). Conversion tools are out of the scope of this document.

When editing the certificate details under "Enhanced key usage" it should show
Server Authentication(1.3.6.1.5.5.7.3.1)
Client Authentication(1.3.6.1.5.5.7.3.2)

When editing the certificate details under "key usage" it should show
Digital Signature, Key Encipherment, Data Encipherment(b0)

There is an openssl command to verify the purpose
In the example the certificate file name is: ldap.example.com.pem using PEM format

Or with Certification authority certificate file name: openosiCA1-DC.crt
Should answer as shown

Be Careful A certificate with no purpose (or Any Purpose : Yes) is a security risk. It could be misused if it is silently stolen from your host with its private key. It could allow anybody to impersonate you or any of your daemons over the Internet. This risk is greater when you have not appropriate Public Key Infrastructure managing revocation lists of certificates. It's a good practice to limit the certificate to its main purpose. Be aware that silent defaults of most HOW TO over Internet build any purpose certificates

---

Return to top of page topLDAPS

check the content of your signed certificate for a correct cn

This cn should contain the FQDN of your host see virtualHostname
The subject (DN) could be slightly different of the request because the Certification authority has removed the attributes it can't verify under its current policy (namely a level of assurance of class 1, 2 ...). This policy is indicated as a certificate practice statement or CSR

You may use several tools to edit your certificate, including Windows, providing the file have an appropriate file extension corresponding to its format(.crt for DER format which is different from PEM). Conversion tools are out of the scope of this document.

When editing the certificate details under "Subject", it shows i.e
The order is not important (display order doesn't necessarily reveal coding order)
DC = com
DC = example
OU = VirtualHosts
CN = ldap.example.com

When editing the certificate details with openssl command line, it should show:
In the example the certificate file name is: ldap.example.com.pem using PEM format

Note that DC and OU components MAY be empty. CN component MUST be present and reflect your fully qualified host name (or LDAP virtual host name)

---

Return to top of page topLDAPS

Get your associated certificate private key

Either locally or from the online enrollment

If it is from an on line certification authority, you probably retrieve a bundle of

• Your private key
• You signed certificate
• The Certification Authority certificate(s)

It comes in PKCS12 format (with .p12 extension for MS Windows)
You will have to export all the components to PEM format
Although the PKCS12 bundle is protected by a password, you should export your SSL TLS private key with no password (as for a web server).

To export the private key from a PKCS12 bundle of name ldap.p12

For more detailed information hit openssl pkcs12 reference

---

Return to top of page topLDAPS

Retrieve the Certification Authority certificate(s)

Put the CA certificates in /etc/pki/tls/certs or see certsBundle
Ensure they are readable by openldap user (default to ldap)

If you used the openOSI Certification authority you will get the certificates here.

• Intermediate CA certificate of class 1: openosiCA1-DC
• Root CA certificate of class 3: openosiCA3-FR

You can also check our LDAP directory

If you have received a PKCS12 bundle of name ldap.p12

Create a hash symbolic link to the CA certificates in the same directory to speed up access.
Use the following command

---

Return to top of page topLDAPS

Retrieve the Certification Authority CRL (certificate revocation list)

If you used the openOSI Certification authority you can retrieve the CRL for each CA certificate at the following URL
http://crl.openosi.org/pki/publicweb/webdist/certdist?cmd=crl&issuer=cn=opeosiCA1-DC,ou=pki,dc=openosi,dc=org
http://crl.openosi.org/pki/publicweb/webdist/certdist?cmd=crl&issuer=cn=opeosiCA3-FR,ou=pki,o=osi,c=fr

You can also check our LDAP directory

Otherwise you should check the value of "CRL Distribution points" in your certificate details, to get the appropriate URL.

Be Careful Check the size of the retrieved CRL file, it could be several megabytes in some cases.

---

Return to top of page topLDAPS

Update certificate repository with CRLs in /etc/pki/tls/crls

Or in /etc/pki/tls/certs see settingCRL, unless you .

You also need to create a symbolic link to the hash of your crls as with certificates. But before, you should convert the CRL files you retrieve to PEM format. CRL files are often provided in DER format to fit browsers needs.

Counvert crl from der format to pem format
This example is with openosi crl files names, replace as appropriate to feet your needs

Create the symbolic link to the hash
This example is with openosi crl files names, replace as appropriate to feet your needs

If you use /etc/pki/tls/crls directory add symbolic links in /etc/pki/tls/certs to your CRL's
see settingCRL
example for CRL hash 591df605.r0

Check that you set TLSCACertificatePath in your slapd.conf.

---

Return to top of page topLDAPS

Setup a cron job to retrieve regularly updated CRLs

Be Careful A Certificate revocation list is an important security feature. It allows checking for revoked certificates. When a certificate owner feels that a private key was compromised he revokes the certificate and get a new one.

Cron job example for openOSI
No need to update the hash (the subject name doesn't change)
replace as appropriate to feet your needs

---

Return to top of page topLDAPS

Decide if you want to keep default Certification authorities bundled file

Generally it is ca-bundle.crt as used in our example of slapd.conf

These external CA certificates are used for TLS authentication. From that point of view, the more you have, more likely you could authenticate a peer.

Useful Information If your certification authority certificate is not by default in that bundle of your remote clients, they will be prompted to accept your CA certificate. Which will not work for a daemon.

If you want a small ca-bundle.crt you could copy additional CA certificates in the CA certificate path that is indicated in our example slapd configuration. You could also go this way to keep the default ca-bundle.crt file untouched and set additional accepted CA (Certification authorities).

Handy Hint Do not forget to set a hash symbolic link to the certificate. See CAcertsRetrieve

---

Return to top of page topLDAPS

Choose your SSL port (default: 636) portSSL

This is obtained when modifying startup script
Edit /etc/rc.d/init.d/ldap
Change the value of "harg="$harg ldaps:///" which means default port 636 on all network interfaces
Where 1636 is the new SSL port (First harg value is about regular 389 port).

You need to get the following startup command if you want to listen on ldaps port 1636 and ldap port 1639 for virtual host ldap.example.com. The later could be a dns name bind to an alternate NIC (Network Interface Card)

As already stated the SSL / TLS protocol supports only one hostname with each couple of network interface and port. If you have several virtual host names you should attached them to different network interface or port.

---

Return to top of page topLDAPS

TLSCRLCheck peer in /etc/openldap/slapd.conf

The possible values are:

• none no CRL check it is the default
• all the CRL of whole CA chain will be checked
• peer verify only the issuer CA

Be Careful! The value of TLSCACertificatePath is used to search the CRL. In general we have a dedicated directory for CRL /etc/pki/tls/crls for LDAP you will need to copy your CRL in the path of TLSCACertificatePath.

You could use information extracted from certificates to authenticate clients, providing you trust their issuing certification authority (CA). This is a Single Sign On (SSO) solution, where no additional identification, username or passwords are required from the client.

1. Check your SASL configuration configureSASL
2. Understand related openLDAP User Name environment variable variablesLDAPS
3. Choose which CA you want to trust trustCA
4. Allow EXTERNAL SASL mechanism allowEXTERNAL
5. Set client certificate verification TLSVerifyClient
6. Set a client configuration to check yout configuration
   • Get a client certificate getCLientCERT
     • Check your subject DN i.e: "cn=ldap-client,ou=People,ou=group,dc=example,dc=com"
     • Check client certificate purpose clientPurposeCERT
   • Store your certificate in a safe place storeClientCERT
7. Update your default openLDAP client settings ldaprcDEFAULT
8. Set your openLDAP trust & access control lists (ACL) setACL
9. Check your sldapd configuration (command: slaptest -v)
10. Restart openLDAP daemon slapd (command: service ldap restart)
11. Check log files for errors (command: tail /var/log/openldap.log)
12. Verify the availability of SASL EXTERNAL mechanism verifyEXTERNAL
    
    

---

Check your SASL configuration

Authenticating with certificates to openLDAP uses the SASL mechanism EXTERNAL. SASL is a third part library (cyrus-sasl) standing for Simple Authentication and Security Layer. Therefore it is required to have sasl up and running, that is salsauthd service started.

For EXTERNAL mechanism, authentication is implicit in the context (e.g., for protocols already using TLS like LDAPS), therfore default configuration will work "out of the box". That is when STARTTLS is running, SASL only retrieve the client certificate's DN and pass it to openLDAP as an authentication regular expression.

You MAY want to restrict the default SASL configuration, to limit the number of accepted mechanisms.
Check for mechanisms allowed by your existing configuration
Note that EXTERNAL is never listed (because it is "external")

update /usr/lib/sasl2/slapd.conf
This is the SASL configuration file for openLDAP slapd daemon
Where you can retrict sasl mechanisms to EXTERNAL with a fall back to GSSAPI (kerberos 5)
If EXTERNAL is not listed, it will be disabled

Be Careful Avoid confusion between authenticating with client certificates to openLDAP through SASL and using LDAP directory to authenticate against other services through SASL i.e. sendmail using LDAP to authenticate clients.

Your /etc/saslauthd.conf configuration file MAY be empty for authenticating with client certificates to openLDAP through SASL

To check the availability of SASL EXTERNAL mechanism, setup a client configuration and see verifyEXTERNAL

---

Return to top of page topsslLDAPSAUTH

Understand related openLDAP User Name environment variables

*SASL_User_Name
*openLDAP_User_Name

When using SASL, openldap delegate the retrieval of the User Name to SASL. That is SASL get a User Name through one of its authentication mechanism and pass it to openLDAP. Let's call this USER Name SASL_User_Name

Using the EXTERNAL mechanism, the SASL_User_Name is the subject of the certificate (the DN or Distinguished name). It could not be anything else. This SASL_User_Name is authenticated if the issuer CA is in your trust path, see trustCA

openLDAP has it's own naming space for users, using DN (Distinguished name) inside it's own DIT (Directory Information Tree). Let's call this USER Name openLDAP_User_Name.

When using SASL EXTERNAL, openLDAP will try to match the SASL_User_Name against an existing openLDAP_User_Name. Fortunately these names are constructed similarly (because certificates rely on X509 standard and LDAP on a subset of X500 standard).

---

Return to top of page topsslLDAPSAUTH

Choose which CA you want to trust

This is your authentication level. Depending the CA you trust, the identity coming with the client certificate will be authenticated or not (at the TLS level). That is before SASL level, which check your LDAP directory, to confirm the accepted identity.

You have roughly the following alternatives (you can mix)

• Trusting all default certification authorities
• Trusting a selected set of external certification authorities
• Trusting only the CA you use for your certificates
• Trusting a subset of the CAs you use for your certificates

When TLS is started, the remote client trust your CA certificate. When you want to verify the client certificate, it is verified if it's signing CA certificate is present in your CA trust file or trust path. That is bundle file ca-bundle.crt or trust directory.

Check settings in /etc/openldap/slapd.conf

You get the remote CA certificate as you get your's CA certificate, or by any other trust mean. You should also similarly create a hash link

Example
where example-CAcert.crt is a certificate file.

Useful Information You may not need to retrieve the remote signing CA certificate because it is already in your trust path. That is in the following "distro" default file, which is a bundle of many certification authorities: TLSCACertificateFile /etc/pki/tls/certs/ca-bundle.crt

Warning With the default bundled file, you accept any client having a signed certificate from these CA. Of course you can modify yourself the CA bundled file, adding or removing CA certififcates.

---

Return to top of page topsslLDAPSAUTH

Allow EXTERNAL SASL mechanism

You need to ask for client certificate verification to allow SASL EXTERNAL mechanism

Update /etc/openldap/slapd.conf
Where the value try ask for a certificate, if none is presented authentication continue with an other mechanism, if an untrusted certificate is presented the session terminate.

others options are: allow or demand

allow: the server will ask for a client certificate; if none is provided the session proceeds normally. If a certificate is provided but the server is unable to verify it, the certificate is ignored and the session proceeds normally, as if no certificate had been provided

demand: the certificate is requested and a valid certificate must be provided, otherwise the session is immediately terminated.

---

Return to top of page topsslLDAPSAUTH

Set client certificate verification

When you want to authenticate with client certificates to openLDAP through SASL, the SASL_User_Name MUST match the openLDAP_User_Name . For this to work you generally have to use sasl-regxp directives for user Name conversion.

You have two situations:

1. SASL_User_Name has it's DN components ordered like openLDAP_User_Name
2. SASL_User_Name has it's DN components in reverse order compared to openLDAP_User_Name

In the first case, there is nothing more to do. But note, that this situation depends on the DN coding inside the certificate subject. This coding order depends of the cryptographic tools used by the CA (Certification authority). Therefore it is likely that you'll have others situations.

In the second case, i.e: when openssl is used to sign a certificate, you get the DN components in reverse order. To be able to get a match against your openLDAP_User_Name you will need to map the SASL_User_Name to an openLDAP_User_Name using sasl_regxp directive in /etc/openldap/slapd.conf.

Update /etc/openldap/slapd.conf for classical style DN
Example where:
SASL_User_Name="c=us,o=My_company,ou=People,cn=My_name"
openLDAP_User_Name="cn=My_name,ou=People,o=My_company,c=us"

Update /etc/openldap/slapd.conf for domain component style DN
Example where:
SASL_User_Name="dc=com,dc=example,ou=People,cn=My_name"
openLDAP_User_Name="cn=My_name,ou=People,dc=example,dc=com"
or
SASL_User_Name="dc=com,dc=example,ou=People,ou=group,cn=My_name"
openLDAP_User_Name="cn=My_name,ou=group,ou=People,dc=example,dc=com"

You MAY have many sasl-regxp directives in your slapd.conf file.

How sasl-regxp works

The authentication request DN is compared to the search pattern using the regular expression functions regcomp() and regexec(), and if it matches, it is rewritten as the replacement pattern. If there are multiple sasl-regexp directives, only the first whose search pattern matches the authentication identity is used. The string that is output from the replacement pattern should be the authentication DN of the user or an LDAP URL. If the replace string produces an LDAP URL, that LDAP URL must evaluate to one and only one entry held by this server. Note, that sasl-regexp replaces authz-regexp in previous openLDAP versions.

DN reverse order question

Be Careful LDAP directories and Certification authorities have not always the same approach of the components order in the DN. This situation will be fixed by RFC3280bis allowing both approach, but requiring same order for a comparizon to match.

RFC 2253 (UTF-8 String Representation of Distinguished Names) defines the order for presenting RDNs in an LDAP DN string: least-significant RDN on the left to most-significant on the right. OpenLDAP adheres to this RFC.

With openSSL the order of the attributes is highest-order first, and thus country always precedes state, organization always precedes OU, and common name, serial number or the personal name fields normally follow any of those four attributes (or locality) which are present. Reason: ASN1 / DER encoding of a SET OF values requires ordering of the encodings of the values. In particular, this issue arises with respect to distinguished names (DN).

RFC3280bis

Learn more on RFC3280bis

email address in DN

Remember that email (emailAddress 1.2.840.113549.1.9.1) in DN is deprecated since RFC3280, instead the certification authorities should use RFC822Name attribute in subjectAlternativeName.

Note that unlike for LDAP, PKCS#9 (which defines the attribute emailAddress for certificates) does not define a standard abbreviation for the attribute, therfore you MAY find "E:", "email", "emailAddress" ...

Content of cn component in DN

Most of the time it is useful to have a unique value in that field, although, unique is always in a "local" context. The subject alternative name refine (or replace) the subject (i.e: with e-mail address), but SASL EXTERNAL only uses the subject DN.

emailAddress in DN was usefull as a global identifier, because SASL extract it as follows:
SASL_User_Name="dn:email=me@example.com,cn=My_name,o=My_company"
It is therefore possible to get an authentication mapping, using sasl-regxp to search for openLDAP mail attribute of an entry. But avoid this solution as it is deprecated, see above.

It is possible to put an e-mail address in the cn value, but many applications will fail (i.e: Liferay) when the client certificate is used in an other context than SASL. Therefore, avoid this solution because you may have impredictable situations with a given application.

Finaly, I recommend, when possible, to insert an "uid" component in the DN, which may look like this;
SASL_User_Name="dn:uid=My_name1234,cn=My_name,o=My_company,c=us"
Where "uid" in example, MAY be build like follows:
FirstName: John
LastName: SMITH
Last 4 digit of social security number: 1234 (or whatever algorytm)
uid=JohnSmith1234
cn="John SMITH"

This uid is supposed to be unique in the scope of a given openLDAP directory (MUST be unique if you enforce controlled uid delivery). The email address remains the only worldwide unique id, if present in the subject alternative name. Note that a person MAY have multiple virtual identities, one for each of it's email addresses.

You may also put an UID value in the CN.

---

Return to top of page topsslLDAPSAUTH

Get a client certificate

• If you use an on line submission, choose the appropriate submission form
• If you generate your request use the appropriate template
  • If you use openssl check /etc/pki/tls/openssl.cnf for
    • nsCertType= client
    • keyUsage= digitalSignature, keyEncipherment
    • default is to have nothing which allows all usage for your certificate, avoid this!

Key usage should be:

• Digital signature
• Key encipherment

Extended key usage should be (see RFC 3280):

• client auth (include OID=1.3.6.1.5.5.7.3.2)

Useful Information If the KeyUsage extension is marked critical, the certificate cannot be used for other purposes

---

Return to top of page topsslLDAPSAUTH

Check client certificate purpose

You may use several tools to edit your certificate, including Windows, providing the file have an appropriate file extension corresponding to its format(.crt for DER format which is different from PEM). Conversion tools are out of the scope of this document.

When editing the certificate details under "key usage" it should show
digitalSignature, Key Encipherment

When editing the certificate details under "Enhanced key usage" it should show
Client Authentication(1.3.6.1.5.5.7.3.2)

There is an openssl command to verify the purpose
In the example the certificate file name is: ldap-client.pem using PEM format

Verify certificate chain with Certification authority certificate file name: ldap-clientCA.crt
Should answer as shown

Be Careful A certificate with no purpose (or Any Purpose : Yes) is a security risk. It could be misused if it is silently stolen from your host with its private key. It could allow anybody to impersonate you or any of your hosts daemons over the Internet. This risk is greater when you have not appropriate Public Key Infrastructure managing revocation lists of certificates. It's a good practice to limit the certificate to its main purpose AND to set it as critical. Be aware that silent defaults of most openssl HOW TO over Internet build any purpose certificates

---

Return to top of page topsslLDAPSAUTH

Store your certificate in a safe place

You get your certificate and private key in one of the follwing forms

1. A PKCS12 bundle file (Mirosoft extension .pfx, .p12) i.e: ldap-client.p12
2. A set of 3 PEM files
   1. Client key file i.e: ldap-client.key
   2. Client certificate file i.e: ldap-client.pem
   3. CLient CA certificates file i.e: ldap-clientCA.crt

For openLDAp configuration you need PEM files. Extract from PKCS12 bundle if necessary

Extraction example

Store these files in the test user home directory
Store ldap-clientCA.crt certification authority file in /etc/pki/tls/certs/trust
Make a hash link of ldap-clientCA.crt

---

Return to top of page topsslLDAPSAUTH

Update your default openLDAP client settings

The default system wide client configuration file is /etc/openldap/ldap.conf
The default user file name is $HOME/.ldaprc (override ldap.conf)

Update system wide client defaults in /etc/openldap/ldap.conf
Set the default LDAP servers (i.e ldaps://directory.openosi.org:636) may be several
Set the default base DIT (Directory Information Tree) for search (i.e dc=openosi,dc=org)
Set system wide trust CA in /etc/pki/tls/certs/trust (when client verifies server's certificate)
Set LDAP server verification mode to Try (similar to allowEXTERNAL)

Update client defaults in $HOME/.ldaprc
Set your client key file i.e: ldap-client.key
Set your client certificate file i.e: ldap-client.pem

---

Return to top of page topsslLDAPSAUTH

Set your access control lists (ACL)

This is your authorization level
Anyone who connects with a valid certificate is an authenticated ACL "users"

in addition:
You MAY use certificate DN corresponding to static groups defined in LDAP
You MAY use certificate DN corresponding to dn.children subset and grant corresponding rights
You MAY use certificate DN corresponding to dn.base and grant corresponding rights
A lot of others possibilities are available when you use regex in "by" statement
Check slapd.access manual

Example of a basic ACL
Where base DIT is dc=openosi,dc=org

Example of a group ACL

Example of a dn.children ACL

Check here for more information

Enabling LDAP Sync Replication using SASL EXTERNAL

Before proceeding you need to check that the following features are working properly

1. LDAPS SSL AUTHENTICATION on the master server
2. LDAPS queries on the slave server

When using SASL EXTERNAL with Syncrepl features, the LDAP Content Synchronization. You need to follow these steps:

1. Update your LDAP master server configuration
   1. Update your regexp directives for proper UserName to bind with regexpSYNC
   2. Update your acl directives to authorize the authenticated UserName aclSYNC
   3. Check your sldapd configuration (command: slaptest -v)
   4. Restart openLDAP daemon slapd (command: service ldap restart)
   5. Check log files for errors (command: tail /var/log/openldap.log)
2. Update your LDAP slave server configuration
   1. Update /etc/openldap/slapd.conf with SYNCREPL configuration configSYNC
   2. Check your sldapd configuration on LDAP slave (command: slaptest -v)
   3. Restart openLDAP daemon slapd (command: service ldap restart)
   4. Check log files for errors (command: tail /var/log/openldap.log)replicaLOG
3. Test LDAP directory replication with a test update
   
   

---

Return to top of page topSYNC

Update your regexp directives for proper UserName to bind with LDAP master server

Remember that you have multiple User Names (DN) to deal with :

1. The certificate's DN (Client's Certificate subject)
2. SASL_User_Name = certificate's DN (with some SASL conversion and addition)
3. openLDAP_User_Name = a user (or host, or Service) entry in your LDAP directory (used in your acl's)

As with "LDAPS SSL AUTHENTICATION", there may be a need to map the SASL_User_Name to an openLDAP_User_Name , who is the User Name (DN) having rights to read the master LDAP directory. Note that you may choose arbitrarily the openLDAP_User_Name suiting your acl (access control list) authorizations.

Useful Information The certificate presented for client authentication of the remote slave LDAP server is the certificate used to setup SSL / TLS on this remote host. That is with a certificate subject containing its FQDN host name, (or FQDN Virtual host name) i.e ldap-slave.example.com.

Example of updated sasl-regexp (or deprecated authz-regexp)
Where:

• Certificate's DN ="CN=ldap-slave.example.com,OU=Services,DC=example,DC=com"
• SASL_User_Name="DC=com,DC=example,OU=Services,cn=ldap-slave.example.com"
• openLDAP_User_Name="cn=syncrepl@ldap-master.example.com,OU=Services,o=Example,C=us"
  

Remember that the first sasl-regexp match will be used. In the example, the second sasl-regexp directive is used to match all the trusted certificates having the same component's structure. Note that sasl-regexp directives are not only used for SASL EXTERNAL, but for all openLDAP authentication mechanisms.

Example of a more simple updated sasl-regexp
Where:

• Certificate's DN ="CN=ldap-slave.example.com,OU=Services,DC=example,DC=com"
• SASL_User_Name="DC=com,DC=example,OU=Services,cn=ldap-slave.example.com"
• openLDAP_User_Name="CN=ldap-slave.example.com,OU=Services,DC=example,DC=com"
  

You MAY have already defined such sasl-regexp directive for generic authentication purpose with client's certificates. If this is the case you have nothing more to do.

Note that you can map multiple SASL_User_Name (i.e: from different mechanisms) to a single openLDAP_User_Name if desired.

---

Return to top of page topSYNC

Update your acl directives to authorize the authenticated UserName

If your openLDAP_User_Name is already authorized to have read access over the directory you want to replicate, there is nothing more to do.

Example of a basic ACL
Where base DIT is ou=People,dc=example,dc=com
Where ACL1 dn.base is the openLDAP_User_Name

---

Return to top of page topSYNC

Update /etc/openldap/slapd.conf with SYNCREPL configuration

Your syncrepl directives are in slapd.conf. I suggest that you insert an include statement in /etc/openldap/slapd.cnf

Example
Where conf.d is a sub configuration directory
Where syncrepl_example.com.conf is the file name containing syncrepl directives for example.com

Update /etc/openldap/conf.d/syncrepl_example.com.conf
Where master server id ldap-master.example.com
Where base directory to replicate is dc=example,dc=com
Where rid=001 uniquely identifies the syncrepl specification described by the current syncrepl directive

Warning SASL EXTERNAL is as secure as your file containing the unencrypted key of your LDAP server (/etc/pki/tls/private.ldap/ldap.key). Note that similarly for GSSAPI you have to protect the ldap keytab file.

Discussion

SASL EXTERNAL versus SASL GSSAPI (Kerberos)

Others mechanisms are not discussed because they have a much lower security level. Currently kerberos is used more commonly although I think that EXTERNAL is a bit more secure. You MAY use both mechanisms on several slaves replicating from one master.

GSSAPI pro

• Fit in pre existing kerberos infrastructure
• Secure
• No passwords exchanged nor stored in clear text

GSSAPI cons

• expertise needed to setup the kerberos infrastructure
• expertise needed for daemon authentication and ticket updating
• expertise needed for SASL setup (poorly documented)
• expertise needed for encrypted replication

EXTERNAL pro

• Fit in pre existing PKI infrastructure
• Fit in open source Internet PKI infrastructure (like openosi.org)
• Secure
• Encrypted replication
• Single Sign On capability

EXTERNAL cons

• expertise needed for openssl CA setup and maintenance
• Attention must be given to CRL (Certificates Revocation Lists) management

---

Return to top of page topSYNC

Check log files for errors (command: tail /var/log/openldap.log)

Example of regular log on master LDAP
Where default sasl-realm is EXAMPLE.COM

Note the following successful steps:

1. TLS established
2. anonymous bind dn=""
3. Subject certificate authentication (authcid and authzid)
4. Mapping to openLDAP name and bind with mech=EXTERNAL
5. Read base dn "dc=example,dc=com" for replication with no errors

REMINDER

• Have a protected master LDAP server and several slaves for public access
• Use include statements in slapd.conf to split your configuration files
• Self-signed certificate usage is discouraged unless for non production environments
• Rudimentary openssl PKI usage is discouraged unless for non production environments
• Keep your certification revocation lists (CRL) up to date
• Downgrade to kerberos_V (GSSAPI) when SASL EXTERNAL is unavailable
• LDAP directory is an identity repository, not an authentication nor an authorization service

and as usual
...

• Always check your trusted certification authorities (CA)
• Check the CA CPS (Certificate practice statement)to learn about the security policy
• Do not disable SELinux targeted
• Try to use -Multi categories security_ (MCS) to protect your files
• Use yum to update your packages
• Avoid to compile and install packages versions not supported / tested by your distro
• Have as many as possible linux box to handle separate services
• Use chrooted environments
• Keep Microsoft box out of Internet direct access
• Confine as much as possible RPC, XML-RPC and netbios
  ...