Merge remote-tracking branch 'origin/mdb.master'

[openldap] / doc / guide / admin / tls.sdf

# $OpenLDAP$
# Copyright 1999-2014 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}} {{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
valid certificate in order to authenticate via SASL EXTERNAL.
For more information on creating and managing certificates,
see the {{PRD:OpenSSL}}, {{PRD:GnuTLS}}, or {{PRD:MozNSS}} documentation,
depending on which TLS implementation libraries you are using.

H3: Server Certificates

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

The DN of a client certificate can be used directly as an
authentication DN.
Since X.509 is a part of the {{TERM:X.500}} standard and LDAP
is also based on X.500, both use the same DN formats and
generally the DN in a user's X.509 certificate should be
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}}
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.

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
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.

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
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}}.

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
{{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.

This directive is ignored with GnuTLS and Mozilla NSS.

H4: TLSDHParamFile <filename>

This directive specifies the file that contains parameters for
Diffie-Hellman ephemeral key exchange.  This is required in order
to use DHE-based cipher suites, including all DSA-based suites (i.e.
{{EX:TLSCertificateKeyFile}} points to a DSA key), and RSA when the 'key
encipherment' key usage is not specified in the certificate.  Parameters can be
generated using the following command

>       openssl dhparam [-dsaparam] -out <filename> <numbits>
or
>       certtool --generate-dh-params --bits <numbits> --outfile <filename>

This directive is ignored with Mozilla NSS.

H4: TLSECName <name>

This directive specifies the curve to use for Elliptic Curve
Diffie-Hellman ephemeral key exchange.  This is required in order
to use ECDHE-based cipher suites in OpenSSL.  The names of supported
curves may be shown using the following command

>       openssl ecparam -list_curves

This directive is not used for GnuTLS and is ignored with Mozilla NSS.
For GnuTLS the curves may be specified in the ciphersuite.

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.  If using Mozilla NSS, <path> may contain a cert/key database.

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.

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
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.