-# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
+# $OpenLDAP$
+# Copyright 1999-2008 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.
-H2: Server Certificates
+H3: Server Certificates
-The DN of a server certificate must use the CN attribute
-to name the server, and the CN must carry the server's
-fully qualified domain name. Additional alias names and wildcards
-may be present in the 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}}.
-H2: Client Certificates
+H3: Client Certificates
The DN of a client certificate can be used directly as an
authentication DN.
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 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
+needs to trust that one signing CA. However, a client may wish
+to connect to a variety of secure servers managed by different
+organizations, with server certificates generated by many
+different CAs. As such, a client is likely to need a list of
+many different trusted CAs in its configuration.
+
+H3: Server Configuration
+
+The configuration directives for slapd belong in the global directives
+section of {{slapd.conf}}(5).
+
+H4: TLSCACertificateFile <filename>
+
+This directive specifies the {{TERM:PEM}}-format file containing
+certificates for the CA's that slapd will trust. The certificate for
+the CA that signed the server certificate must be included among
+these certificates. If the signing CA was not a top-level (root) CA,
+certificates for the entire sequence of CA's from the signing CA to
+the top-level CA should be present. Multiple certificates are simply
+appended to the file; the order is not significant.
+
+H4: TLSCACertificatePath <path>
+
+This directive specifies the path of a directory that contains
+individual {{TERM:CA}} certificates in separate files. In addition,
+this directory must be specially managed using the OpenSSL {{c_rehash}}
+utility. When using this feature, the OpenSSL library will attempt to
+locate certificate files based on a hash of their name and serial number.
+The {{c_rehash}} utility is used to generate symbolic links with the
+hashed names that point to the actual certificate files. As such,
+this option can only be used with a filesystem that actually supports
+symbolic links. In general, it is simpler to use the
+{{EX:TLSCACertificateFile}} directive instead.
+
+H4: TLSCertificateFile <filename>
+
+This directive specifies the file that contains the slapd server
+certificate. Certificates are generally public information and
+require no special protection.
+
+H4: TLSCertificateKeyFile <filename>
+
+This directive specifies the file that contains the private key
+that matches the certificate stored in the {{EX:TLSCertificateFile}}
+file. Private keys themselves are sensitive data and are usually
+password encrypted for protection. However, the current implementation
+doesn't support encrypted keys so the key must not be encrypted
+and the file itself must be protected carefully.
+
+H4: TLSCipherSuite <cipher-suite-spec>
+
+This directive configures what ciphers will be accepted and the
+preference order. {{EX:<cipher-suite-spec>}} should be a cipher
+specification for OpenSSL. You can use the command
+
+> 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}}.
+
+H4: TLSRandFile <filename>
+
+This directive specifies the file to obtain random bits from when
+{{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.
+
+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>
+
+H4: TLSVerifyClient { never | allow | try | demand }
+
+This directive specifies what checks to perform on client certificates
+in an incoming TLS session, if any. This option is set to {{EX:never}}
+by default, in which case the server never asks the client for a
+certificate. With a setting of {{EX: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. With a setting of
+{{EX:try}} the certificate is requested, and if none is provided,
+the session proceeds normally. If a certificate is provided and it
+cannot be verified, the session is immediately terminated. With a
+setting of {{EX:demand}} the certificate is requested and a valid
+certificate must be provided, otherwise the session is immediately
+terminated.
+
+Note: The server must request a client certificate in order to
+use the SASL EXTERNAL authentication mechanism with a TLS session.
+As such, a non-default {{EX:TLSVerifyClient}} setting must be configured
+before SASL EXTERNAL authentication may be attempted, and the
+SASL EXTERNAL mechanism will only be offered to the client if a valid
+client certificate was received.
+
+H3: Client Configuration
+
+Most of the client configuration directives parallel the server
+directives. The names of the directives are different, and they go
+into {{ldap.conf}}(5) instead of {{slapd.conf}}(5), but their
+functionality is mostly the same. Also, while most of these options may
+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
+noted in the {{SECT:TLS Configuration}} section, a client typically
+may need to know about more CAs than a server, but otherwise the
+same considerations apply.
+
+H4: TLS_CACERTDIR <path>
+
+This is equivalent to the server's {{EX:TLSCACertificatePath}} option. The
+specified directory must be managed with the OpenSSL {{c_rehash}}
+utility as well.
+
+H4: TLS_CERT <filename>
+
+This directive specifies the file that contains the client certificate.
+This is a user-only directive and can only be specified in a user's
+{{.ldaprc}} file.
+
+H4: TLS_KEY <filename>
+
+This directive specifies the file that contains the private key
+that matches the certificate stored in the {{EX:TLS_CERT}}
+file. The same constraints mentioned for {{EX:TLSCertificateKeyFile}}
+apply here. This is also a user-only directive.
+
+H4: TLS_RANDFILE <filename>
+
+This directive is the same as the server's {{EX:TLSRandFile}}
+option.
+
+H4: TLS_REQCERT { never | allow | try | demand }
+
+This directive is equivalent to the server's {{EX:TLSVerifyClient}}
+option. However, for clients the default value is {{EX:demand}}
+and there generally is no good reason to change this setting.
+