mirror/openldap
2
0
Fork 0
mirror of https://git.openldap.org/openldap/openldap.git synced 2024-12-27 03:20:22 +08:00
Code Issues Packages Projects Releases Wiki Activity

Added TLS configuration, mostly the same as the man pages but fleshed

Browse Source 
out a little more.
This commit is contained in:
Howard Chu 2002-06-16 12:24:16 +00:00
parent 98b1e09c44
commit 4405c1ab27
1 changed files with 179 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

181
doc/guide/admin/tls.sdf
View File

@ -8,6 +8,8 @@ OpenLDAP clients and servers are capable of using the
integrity and confidentiality protections and to support
LDAP authentication using the {{TERM:SASL}} EXTERNAL mechanism.
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
@ -15,7 +17,7 @@ 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 {{EX:CN}} must carry the server's
@ -23,7 +25,7 @@ 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}}.
H2: Client Certificates
H3: Client Certificates
The DN of a client certificate can be used directly as an
authentication DN.
@ -35,3 +37,178 @@ the DNs may not be exactly the same, and so the mapping
facility described in
{{SECT:Mapping Authentication identities to LDAP entries}}
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.
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
{{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)
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: 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.
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 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.
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.