# $OpenLDAP$
-# Copyright 1999-2007 The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 1999-2013 The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: Using TLS
LDAP authentication using the {{TERM:SASL}} {{TERM:EXTERNAL}} mechanism.
TLS is defined in {{REF:RFC4346}}.
+Note: For generating certifcates, please reference {{URL:http://www.openldap.org/faq/data/cache/185.html}}
+
H2: TLS Certificates
TLS uses {{TERM:X.509}} certificates to carry client and server
whereas client certificates are optional. Clients must have a
valid certificate in order to authenticate via SASL EXTERNAL.
For more information on creating and managing certificates,
-see the {{PRD:OpenSSL}} documentation.
+see the {{PRD:OpenSSL}}, {{PRD:GnuTLS}}, or {{PRD:MozNSS}} documentation,
+depending on which TLS implementation libraries you are using.
H3: Server Certificates
symbolic links. In general, it is simpler to use the
{{EX:TLSCACertificateFile}} directive instead.
+When using Mozilla NSS, this directive can be used to specify the
+path of the directory containing the NSS certificate and key database
+files. The {{certutil}} command can be used to add a {{TERM:CA}} certificate:
+
+> certutil -d <path> -A -n "name of CA cert" -t CT,, -a -i /path/to/cacertfile.pem
+
+. This command will add a CA certficate stored in the PEM (ASCII) formatted
+. file named /path/to/cacertfile.pem. {{EX:-t CT,,}} means that the certificate is
+. trusted to be a CA issuing certs for use in TLS clients and servers.
+
H4: TLSCertificateFile <filename>
This directive specifies the file that contains the slapd server
certificate. Certificates are generally public information and
require no special protection.
+When using Mozilla NSS, if using a cert/key database (specified with
+{{EX:TLSCACertificatePath}}), this directive specifies
+the name of the certificate to use:
+
+> TLSCertificateFile Server-Cert
+
+. If using a token other than the internal built in token, specify the
+. token name first, followed by a colon:
+
+> TLSCertificateFile my hardware device:Server-Cert
+
+. Use {{EX:certutil -L}} to list the certificates by name:
+
+> certutil -d /path/to/certdbdir -L
+
H4: TLSCertificateKeyFile <filename>
This directive specifies the file that contains the private key
doesn't support encrypted keys so the key must not be encrypted
and the file itself must be protected carefully.
+When using Mozilla NSS, this directive specifies the name of
+a file that contains the password for the key for the certificate specified with
+{{EX:TLSCertificateFile}}. The modutil command can be used to turn off password
+protection for the cert/key database. For example, if {{EX:TLSCACertificatePath}}
+specifes /etc/openldap/certdb as the location of the cert/key database, use
+modutil to change the password to the empty string:
+
+> modutil -dbdir /etc/openldap/certdb -changepw 'NSS Certificate DB'
+
+. You must have the old password, if any. Ignore the WARNING about the running
+. browser. Press 'Enter' for the new password.
+
H4: TLSCipherSuite <cipher-suite-spec>
This directive configures what ciphers will be accepted and the
> openssl ciphers -v ALL
to obtain a verbose list of available cipher specifications.
+
Besides the individual cipher names, the specifiers {{EX:HIGH}},
{{EX:MEDIUM}}, {{EX:LOW}}, {{EX:EXPORT}}, and {{EX:EXPORT40}}
may be helpful, along with {{EX:TLSv1}}, {{EX:SSLv3}},
and {{EX:SSLv2}}.
+To obtain the list of ciphers in GnuTLS use:
+
+> gnutls-cli -l
+
+When using Mozilla NSS, the OpenSSL cipher suite specifications are used and
+translated into the format used internally by Mozilla NSS. There isn't an easy
+way to list the cipher suites from the command line. The authoritative list
+is in the source code for Mozilla NSS in the file sslinfo.c in the structure
+
+> static const SSLCipherSuiteInfo suiteInfo[]
+
H4: TLSRandFile <filename>
This directive specifies the file to obtain random bits from when
is only used to provide a seed for the pseudo-random number generator,
and it doesn't need very much data to work.
+This directive is ignored with GnuTLS and Mozilla NSS.
+
H4: TLSEphemeralDHParamFile <filename>
This directive specifies the file that contains parameters for
> openssl dhparam [-dsaparam] -out <filename> <numbits>
+This directive is ignored with GnuTLS and Mozilla NSS.
+
H4: TLSVerifyClient { never | allow | try | demand }
This directive specifies what checks to perform on client certificates
individual users in their {{.ldaprc}} files.
The LDAP Start TLS operation is used in LDAP to initiate TLS
-negotatation. All OpenLDAP command line tools support a {{EX:-Z}}
+negotiation. All OpenLDAP command line tools support a {{EX:-Z}}
and {{EX:-ZZ}} flag to indicate whether a Start TLS operation is to
be issued. The latter flag indicates that the tool is to cease
processing if TLS cannot be started while the former allows the
This is equivalent to the server's {{EX:TLSCACertificatePath}} option. The
specified directory must be managed with the OpenSSL {{c_rehash}}
-utility as well.
+utility as well. If using Mozilla NSS, <path> may contain a cert/key database.
H4: TLS_CERT <filename>
This is a user-only directive and can only be specified in a user's
{{.ldaprc}} file.
+When using Mozilla NSS, if using a cert/key database (specified with
+{{EX:TLS_CACERTDIR}}), this directive specifies
+the name of the certificate to use:
+
+> TLS_CERT Certificate for Sam Carter
+
+. If using a token other than the internal built in token, specify the
+. token name first, followed by a colon:
+
+> TLS_CERT my hardware device:Certificate for Sam Carter
+
+. Use {{EX:certutil -L}} to list the certificates by name:
+
+> certutil -d /path/to/certdbdir -L
+
+
H4: TLS_KEY <filename>
This directive specifies the file that contains the private key