mirror of
https://git.openldap.org/openldap/openldap.git
synced 2024-12-21 03:10:25 +08:00
256 lines
10 KiB
Plaintext
256 lines
10 KiB
Plaintext
# $OpenLDAP$
|
|
# Copyright 1999-2020 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 certificates, 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}} or {{PRD:GnuTLS}} 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.
|
|
|
|
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}}.
|
|
|
|
To obtain the list of ciphers in GnuTLS use:
|
|
|
|
> gnutls-cli -l
|
|
|
|
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.
|
|
|
|
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>
|
|
|
|
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.
|
|
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.
|
|
|
|
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.
|
|
|