1 files changed, 305 insertions, 0 deletions
diff --git a/doc/guide/admin/tls.sdf b/doc/guide/admin/tls.sdf
new file mode 100644
index 0000000..47dc9dc
--- /dev/null
+++ b/doc/guide/admin/tls.sdf
@@ -0,0 +1,305 @@
+# $OpenLDAP$
+# Copyright 1999-2018 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: 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.
+