-# Copyright 1999-2002, The OpenLDAP Foundation, All Rights Reserved.
+# $OpenLDAP$
+# Copyright 1999-2013 The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: Using TLS
OpenLDAP clients and servers are capable of using the
{{TERM[expand]TLS}} ({{TERM:TLS}}) framework to provide
integrity and confidentiality protections and to support
-LDAP authentication using the {{TERM:SASL}} EXTERNAL mechanism.
+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
-identities. All servers are required to have valid certificates,
-whereas client certificates are optional. Clients must have a
+identities. All servers are required to have valid certificates,
+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
-The DN of a server certificate must use the CN attribute
-to name the server, and the {{EX:CN}} must carry the server's
-fully qualified domain name. Additional alias names and wildcards
-may be present in the {{EX:subjectAltName}} certificate extension.
-More details on server certificate names are in {{REF:RFC2830}}.
+The {{TERM:DN}} of a server certificate must use the {{EX:CN}}
+attribute to name the server, and the {{EX:CN}} must carry the
+server's fully qualified domain name. Additional alias names and
+wildcards may be present in the {{EX:subjectAltName}} certificate
+extension. More details on server certificate names are in
+{{REF:RFC4513}}.
H3: Client Certificates
identical to the DN of their LDAP entry. However, sometimes
the DNs may not be exactly the same, and so the mapping
facility described in
-{{SECT:Mapping Authentication identities to LDAP entries}}
+{{SECT:Mapping Authentication Identities}}
can be applied to these DNs as well.
H2: TLS Configuration
-After obtaining the required certificates, a
-number of options must be configured on both the client
-and the server to enable TLS and make use of the certificates.
-At a minimum, the clients must be configured with the filename
-containing all of the {{TERM[expand]CA}} (CA) certificates it
-will trust. The server must be configured with the {{TERM:CA}}
-certificates and also its own server certificate and private key.
+After obtaining the required certificates, a number of options must
+be configured on both the client and the server to enable TLS and
+make use of the certificates. At a minimum, the clients must be
+configured with the name of the file containing all of the
+{{TERM[expand]CA}} (CA) certificates it will trust. The server must
+be configured with the {{TERM:CA}} certificates and also its own
+server certificate and private key.
Typically a single CA will have issued the server certificate
and all of the trusted client certificates, so the server only
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
-{{EX:/dev/urandom}} is not available. If the
-system provides {{EX:/dev/urandom}} then this option is not needed,
-otherwise a source of random data must be configured.
-Some systems (e.g. Linux)
-provide {{EX:/dev/urandom}} by default, while others (e.g. Solaris)
+{{FILE:/dev/urandom}} is not available. If the system provides
+{{FILE:/dev/urandom}} then this option is not needed, otherwise a
+source of random data must be configured. Some systems (e.g. Linux)
+provide {{FILE:/dev/urandom}} by default, while others (e.g. Solaris)
require the installation of a patch to provide it, and others may
not support it at all. In the latter case, EGD or PRNGD should be
installed, and this directive should specify the name of the EGD/PRNGD
-socket. The environment variable {{EX:RANDFILE}} can also be used to specify
-the filename. Also, in the absence of these options, the {{EX:.rnd}}
-file in the slapd user's home directory may be used if it exists. To
-use the {{EX:.rnd}} file, just create the file and copy a few hundred
-bytes of arbitrary data into the file. The file is only used to
-provide a seed for the pseudo-random number generator, and it doesn't
-need very much data to work.
+socket. The environment variable {{EX:RANDFILE}} can also be used
+to specify the filename. Also, in the absence of these options, the
+{{EX:.rnd}} file in the slapd user's home directory may be used if
+it exists. To use the {{EX:.rnd}} file, just create the file and
+copy a few hundred bytes of arbitrary data into the file. The file
+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
+Diffie-Hellman ephemeral key exchange. This is required in order
+to use a DSA certificate on the server side (i.e.
+{{EX:TLSCertificateKeyFile}} points to a DSA key). Multiple sets
+of parameters can be included in the file; all of them will be
+processed. Parameters can be generated using the following command
+
+> openssl dhparam [-dsaparam] -out <filename> <numbits>
+
+This directive is ignored with GnuTLS and Mozilla NSS.
H4: TLSVerifyClient { never | allow | try | demand }
be configured on a system-wide basis, they may all be overridden by
individual users in their {{.ldaprc}} files.
+The LDAP Start TLS operation is used in LDAP to initiate TLS
+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
+command to continue.
+
+In LDAPv2 environments, TLS is normally started using the LDAP
+Secure URI scheme ({{EX:ldaps://}}) instead of the normal LDAP URI
+scheme ({{EX:ldap://}}). OpenLDAP command line tools allow either
+scheme to used with the {{EX:-H}} flag and with the {{EX:URI}}
+{{ldap.conf}}(5) option.
+
+
H4: TLS_CACERT <filename>
This is equivalent to the server's {{EX:TLSCACertificateFile}} option. As
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
option. However, for clients the default value is {{EX:demand}}
and there generally is no good reason to change this setting.
-H4: TLS { never | hard }
-
-This directive specifies whether client connections should use TLS
-by default. The default setting is {{EX:never}} which specifies that
-connections will be opened in the clear unless TLS is explicitly
-specified using an "ldaps://" URL. When set to {{EX:hard}} all
-connections will be established with TLS, as if an "ldaps://" URL
-was specified. Note that the use of ldaps is a holdover from LDAPv2
-and this setting is incompatible with the LDAPv3 StartTLS request.
-As such, it's best not to use this option.
projects / openldap / blobdiff