commit 1e8f4dbcf6c953feb412da9b26a5b1201d83de38
Author: Stephen Wadeley <swadeley(a)redhat.com>
Date: Sat Feb 28 09:53:06 2015 +0100
Establishing a Secure Connection
en-US/OpenLDAP.xml | 324 ++++++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 324 insertions(+), 0 deletions(-)
---
diff --git a/en-US/OpenLDAP.xml b/en-US/OpenLDAP.xml
index e4159cc..857030a 100644
--- a/en-US/OpenLDAP.xml
+++ b/en-US/OpenLDAP.xml
@@ -1067,6 +1067,330 @@ Re-enter new password:
Since OpenLDAP 2.3, the <filename
class="directory">/etc/openldap/slapd.d/</filename> directory also
contains LDAP definitions that were previously located in <filename
class="directory">/etc/openldap/schema/</filename>. It is possible to
extend the schema used by OpenLDAP to support additional attribute types and object
classes using the default schema files as a guide. However, this task is beyond the scope
of this chapter. For more information on this topic, see <ulink
url="http://www.openldap.org/doc/admin/schema.html" />.
</para>
</section>
+ <section id="s3-establishing_a_secure_connection">
+ <title>Establishing a Secure Connection</title>
+ <indexterm>
+ <primary>OpenLDAP</primary>
+ <secondary>configuration</secondary>
+ <tertiary>TLS</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>OpenLDAP</primary>
+ <secondary>files</secondary>
+
<tertiary><filename>/etc/openldap/ldap.conf</filename></tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>OpenLDAP</primary>
+ <secondary>files</secondary>
+
<tertiary><filename>/etc/openldap/slapd.d/cn=config.ldif</filename></tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>OpenLDAP</primary>
+ <secondary>security</secondary>
+ </indexterm>
+ <para>
+ OpenLDAP clients and servers can be secured using the Transport Layer Security
(TLS) framework. TLS is a cryptographic protocol designed to provide communication
security over the network. As noted above, OpenLDAP suite in Red Hat Enterprise Linux 7
uses Mozilla NSS as the TLS implementation.
+ </para>
+ <para>
+ To establish a secure connection using TLS, obtain the required certificates as
described in <ulink
url="http://www.openldap.org/faq/index.cgi?file=1514"><ci...
pubwork="webpage">How do I use TLS/SSL with Mozilla
NSS</citetitle></ulink>. Then, a number of options must be configured on both
the client and the server. At a minimum, a server must be configured with the Certificate
Authority (CA) certificates and also its own server certificate and private key. The
clients must be configured with the name of the file containing all the trusted CA
certificates.
+ </para>
+ <para>
+ Typically, a server only needs to sign a single CA certificate. A client may want
to connect to a variety of secure servers, therefore it is common to specify a list of
several trusted CAs in its configuration.
+ </para>
+ <bridgehead id="br-server_configuration">Server
Configuration</bridgehead>
+ <para>
+ This section lists global configuration directives for <systemitem
class="daemon">slapd</systemitem> that need to be specified in the
<filename>/etc/openldap/slapd.d/cn=config.ldif</filename> file on an OpenLDAP
server in order to establish TLS.
+ </para>
+ <para>
+ While the old style configuration uses a single file, normally installed as
<filename>/usr/local/etc/openldap/slapd.conf</filename>, the new style uses a
slapd backend database to store the configuration. The configuration database normally
resides in the <filename
class="directory">/usr/local/etc/openldap/slapd.d/</filename>
directory.
+ </para>
+ <para>
+ The following directives are also valid for establishing SSL. In addition to TLS
directives, you need to enable a port dedicated to SSL on the server side – typically it
is port 636. To do so, edit the <filename>/etc/sysconfig/slapd</filename> file
and append the <literal>ldaps:///</literal> string to the list of URLs
specified with the <option>SLAPD_URLS</option> directive.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <option>olcTLSCACertificateFile</option>
+ </term>
+ <listitem>
+ <para>
+ The <option>olcTLSCACertificateFile</option> directive
specifies the file encoded with Privacy-Enhanced Mail (PEM) schema that contains trusted
CA certificates. The directive takes the following form:
+ </para>
+ <synopsis><option>olcTLSCACertificateFile</option>:
<replaceable>path</replaceable></synopsis>
+ <para>
+ Replace <replaceable>path</replaceable> either with a path to
the CA certificate file, or, if you use Mozilla NSS, with a certificate name.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>olcTLSCACertificatePath</option>
+ </term>
+ <listitem>
+ <para>
+ The <option>olcTLSCACertificatePath</option> directive
specifies the path to a directory containing individual CA certificates in separate files.
This directory must be specially managed with the OpenSSL
<application>c_rehash</application> utility that generates symbolic links with
the hashed names that point to the actual certificate files. In general, it is simpler to
use the <option>olcTLSCACertificateFile</option> directive instead.
+ </para>
+ <para>
+ If Mozilla NSS is used,
<option>olcTLSCACertificatePath</option> accepts a path to the Mozilla NSS
database (as shown in <xref
linkend="ex-using_olcTLSCACertificatePath_with_Mozilla_NSS" />). In such a
case, <application>c_rehash</application> is not needed.
+ </para>
+ <para>
+ The directive takes the following form:
+ </para>
+ <synopsis><option>olcTLSCACertificatePath</option>:
<replaceable>path</replaceable></synopsis>
+ <para>
+ Replace <replaceable>path</replaceable> with a path to the
directory containing the CA certificate files, or with a path to a Mozilla NSS database
file.
+ </para>
+ <example
id="ex-using_olcTLSCACertificatePath_with_Mozilla_NSS">
+ <title>Using olcTLSCACertificatePath with Mozilla NSS</title>
+ <para>
+ With Mozilla NSS, the
<option>olcTLSCACertificatePath</option> directive specifies the path of the
directory containing the NSS certificate and key database files. For example:
+ </para>
+ <synopsis><option>olcTLSCACertificatePath</option>:
<filename>sql:/home/nssdb/sharednssdb</filename></synopsis>
+ <para>
+ The <command>certutil</command> command is used to add a CA
certificate to these NSS database files:
+ </para>
+ <synopsis><command>certutil</command>
<option>-d</option> <filename
class="directory">sql:/home/nssdb/sharednssdb</filename>
<option>-A</option> <option>-n</option>
"<replaceable>CA_certificate</replaceable>"
<option>-t</option> <literal>CT,,</literal>
<option>-a</option> <option>-i</option>
<filename>certificate.pem</filename></synopsis>
+ <para>
+ The above command adds a CA certificate stored in a PEM-formatted file
named <replaceable>certificate.pem</replaceable>. The
<option>-d</option> option specifies the database directory containing the
certificate and key database files, the <option>-n</option> option sets a name
for the certificate, <option>-t</option> <literal>CT,,</literal>
means that the certificate is trusted to be used in TLS clients and servers. The
<option>-A</option> option adds an existing certificate to a certificate
database, the <option>-a</option> option allows the use of ASCII format for
input or output, and the <option>-i</option> option passes the
<filename>certificate.pem</filename> input file to the command.
+ </para>
+ </example>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>olcTLSCertificateFile</option>
+ </term>
+ <listitem>
+ <para>
+ The <option>olcTLSCertificateFile</option> directive specifies
the file that contains the <systemitem
class="daemon">slapd</systemitem> server certificate. The directive
takes the following form:
+ </para>
+ <synopsis><option>olcTLSCertificateFile</option>:
<replaceable>path</replaceable></synopsis>
+ <para>
+ Replace <replaceable>path</replaceable> with a path to the
<systemitem class="daemon">slapd</systemitem> server certificate
file, or, if you use Mozilla NSS, with a certificate name.
+ </para>
+ <example
id="ex-using_olcTLSCertificateFile_with_Mozilla_NSS">
+ <title>Using olcTLSCertificateFile with Mozilla NSS</title>
+ <para>
+ When using Mozilla NSS with certificate and key database files specified
with the <option>olcTLSCACertificatePath</option> directive,
<option>olcTLSCertificateFile</option> is used to specify the name of the
certificate to use. First, execute the following command to view a list of certificates
available in your NSS database file:
+ </para>
+ <synopsis><command>certutil</command>
<option>-d</option> <filename
class="directory">sql:/home/nssdb/sharednssdb</filename>
<option>-L</option></synopsis>
+ <para>
+ Select a certificate from the list and pass its name to
<option>olcTLSCertificateFile</option>. For example:
+ </para>
+ <synopsis><command>olcTLSCertificateFile</command>
<emphasis>slapd_cert</emphasis></synopsis>
+ </example>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>olcTLSCertificateKeyFile</option>
+ </term>
+ <listitem>
+ <para>
+ The <option>olcTLSCertificateKeyFile</option> directive
specifies the file that contains the private key that matches the certificate stored in
the file specified with <option>olcTLSCertificateFile</option>. Note that the
current implementation does not support encrypted private keys, and therefore the
containing file must be sufficiently protected. The directive takes the following form:
+ </para>
+ <synopsis><option>olcTLSCertificateKeyFile</option>:
<replaceable>path</replaceable></synopsis>
+ <para>
+ Replace <replaceable>path</replaceable> with a path to the
private key file if you use PEM certificates. When using Mozilla NSS,
<replaceable>path</replaceable> stands for the name of a file that contains
the password for the key for the certificate specified with the
<option>olcTLSCertificateFile</option> directive (see <xref
linkend="ex-using_olcTLSCertificateKeyFile_with_Mozilla_NSS" />).
+ </para>
+ <example
id="ex-using_olcTLSCertificateKeyFile_with_Mozilla_NSS">
+ <title>Using olcTLSCertificateKeyFile with Mozilla NSS</title>
+ <para>
+ When using Mozilla NSS, this directive specifies the name of a file that
contains the password for the key for the certificate specified with
<option>olcTLSCertificateFile</option>:
+ </para>
+ <synopsis><option>olcTLSCertificateKeyFile</option>:
<emphasis>slapd_cert_key</emphasis></synopsis>
+ <para>
+ The <command>modutil</command> command can be used to turn
off password protection or to change the password for NSS database files. For example:
+ </para>
+ <synopsis><command>modutil</command>
<option>-dbdir</option> <filename
class="directory">sql:/home/nssdb/sharednssdb</filename>
<option>-changepw</option></synopsis>
+ </example>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <bridgehead id="br-client_configuration">Client
Configuration</bridgehead>
+ <para>
+ Specify the following directives in the
<filename>/etc/openldap/ldap.conf</filename> configuration file on the client
system. Most of these directives are parallel to the server configuration options.
Directives in<filename>/etc/openldap/ldap.conf</filename> are configured on a
system-wide basis, however, individual users may override them in their
<filename>~/.ldaprc</filename> files.
+ </para>
+ <para>
+ The same directives can be used to establish an SSL connection. The
<literal>ldaps://</literal> string must be used instead of
<literal>ldap://</literal> in OpenLDAP commands such as
<command>ldapsearch</command>. This forces commands to use the default port
for SSL, port 636, configured on the server.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <option>TLS_CACERT</option>
+ </term>
+ <listitem>
+ <para>
+ The <option>TLS_CACERT</option> directive specifies a file
containing certificates for all of the Certificate Authorities the client will recognize.
This is equivalent to the <option>olcTLSCACertificateFile</option> directive
on a server. <option>TLS_CACERT</option> should always be specified before
<option>TLS_CACERTDIR</option> in
<filename>/etc/openldap/ldap.conf</filename>. The directive takes the
following form:
+ </para>
+ <synopsis><option>TLS_CACERT</option>
<replaceable>path</replaceable></synopsis>
+ <para>
+ Replace <replaceable>path</replaceable> with a path to the CA
certificate file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>TLS_CACERTDIR</option>
+ </term>
+ <listitem>
+ <para>
+ The <option>TLS_CACERTDIR</option> directive specifies the path
to a directory that contains Certificate Authority certificates in separate files. As with
<option>olcTLSCACertificatePath</option> on a server, the specified directory
must be managed with the OpenSSL <application>c_rehash</application> utility.
Path to Mozilla NSS database file is also accepted,
<application>c_rehash</application> is not needed in such case. The directive
takes the following form:
+ </para>
+ <synopsis><option>TLS_CACERTDIR</option>
<replaceable>directory</replaceable></synopsis>
+ <para>
+ Replace <replaceable>directory</replaceable> with a path to
the directory containing CA certificate files. With Mozilla NSS,
<replaceable>directory</replaceable> stands for a path to the certificate or
key database file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>TLS_CERT</option>
+ </term>
+ <listitem>
+ <para>
+ The <option>TLS_CERT</option> specifies the file that contains
a client certificate. This directive can only be specified in a user's
<filename>~/.ldaprc</filename> file. With Mozilla NSS, this directive
specifies the name of the certificate to be chosen from the database specified with the
aforementioned <option>TLS_CACERTDIR</option> directive. The directive takes
the following form:
+ </para>
+ <synopsis><option>TLS_CERT</option>
<replaceable>path</replaceable></synopsis>
+ <para>
+ Replace <replaceable>path</replaceable> with a path to the
client certificate file, or with a name of a certificate from the NSS database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>TLS_KEY</option>
+ </term>
+ <listitem>
+ <para>
+ The <option>TLS_KEY</option> specifies the file that contains
the private key that matches the certificate stored in the file specified with the
<option>TLS_CERT</option> directive. As with
<option>olcTLSCertificateFile</option> on a server, encrypted key files are
not supported, so the file itself must be carefully protected. This option is only
configurable in a user's <filename>~/.ldaprc</filename> file.
+ </para>
+ <para>
+ When using Mozilla NSS, <option>TLS_KEY</option> specifies the
name of a file that contains the password for the private key that protects the
certificate specified with the <option>TLS_CERT</option> directive. Similarly
to the <option>olcTLSCertificateKeyFile</option> directive on a server (see
<xref linkend="ex-using_olcTLSCertificateKeyFile_with_Mozilla_NSS" />),
you can use the <command>modutil</command> command to manage this password.
+ </para>
+ <para>
+ The <option>TLS_KEY</option> directive takes the following
form:
+ </para>
+ <synopsis><option>TLS_KEY</option>
<replaceable>path</replaceable></synopsis>
+ <para>
+ Replace <replaceable>path</replaceable> with a path to the
client certificate file or with a name of the password file in the NSS database.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+ <section id="s3-setting_up_replication">
+ <title>Setting Up Replication</title>
+ <indexterm>
+ <primary>OpenLDAP</primary>
+ <secondary>configuration</secondary>
+ <tertiary>TLS</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>OpenLDAP</primary>
+ <secondary>directories</secondary>
+ <tertiary><filename
class="directory">/etc/openldap/slapd.d/</filename></tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>OpenLDAP</primary>
+ <secondary>replication</secondary>
+ </indexterm>
+ <para>
+ Replication is the process of copying updates from one LDAP server
(<emphasis>provider</emphasis>) to one or more other servers or clients
(<emphasis>consumers</emphasis>). A provider replicates directory updates to
consumers, the received updates can be further propagated by the consumer to other
servers, so a consumer can also act simultaneously as a provider. Also, a consumer does
not have to be an LDAP server, it may be just an LDAP client. In OpenLDAP, you can use
several replication modes, most notable are <emphasis>mirror</emphasis> and
<emphasis>sync</emphasis>. For more information on OpenLDAP replication modes,
see the <emphasis>OpenLDAP Software Administrator's Guide</emphasis>
installed with <package>openldap-servers</package> package (see <xref
linkend="bh-Installed_Documentation_OpenLDAP" />).
+ </para>
+ <para>
+ To enable a chosen replication mode, use one of the following directives in
<filename class="directory">/etc/openldap/slapd.d/</filename> on
both provider and consumers.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <option>olcMirrorMode</option>
+ </term>
+ <listitem>
+ <para>
+ The <option>olcMirrorMode</option> directive enables the mirror
replication mode. It takes the following form:
+ </para>
+ <synopsis><option>olcMirrorMode</option>
<option>on</option></synopsis>
+ <para>
+ This option needs to be specified both on provider and consumers. Also a
<option>serverID</option> must be specified along with
<option>syncrepl</option> options. Find a detailed example in the
<emphasis>18.3.4. MirrorMode</emphasis> section of the
<emphasis>OpenLDAP Software Administrator's Guide</emphasis> (see <xref
linkend="bh-Installed_Documentation_OpenLDAP" />).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>olcSyncrepl</option>
+ </term>
+ <listitem>
+ <para>
+ The <option>olcSyncrepl</option> directive enables the sync
replication mode. It takes the following form:
+ </para>
+ <synopsis><option>olcSyncrepl</option>
<option>on</option></synopsis>
+ <para>
+ The sync replication mode requires a specific configuration on both the
provider and the consumers. This configuration is thoroughly described in the
<emphasis>18.3.1. Syncrepl</emphasis> section of the <emphasis>OpenLDAP
Software Administrator's Guide</emphasis> (see <xref
linkend="bh-Installed_Documentation_OpenLDAP" />).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+ <section id="s3-loading_modules_or_backends">
+ <title>Loading Modules and Backends</title>
+ <indexterm>
+ <primary>OpenLDAP</primary>
+ <secondary>configuration</secondary>
+ <tertiary>TLS</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>OpenLDAP</primary>
+ <secondary>directories</secondary>
+ <tertiary><filename
class="directory">/etc/openldap/slapd.d/</filename></tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>OpenLDAP</primary>
+ <secondary>modules</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>OpenLDAP</primary>
+ <secondary>backends</secondary>
+ </indexterm>
+ <para>
+ You can enhance the <systemitem
class="daemon">slapd</systemitem> service with dynamically loaded
modules. Support for these modules must be enabled with the
<option>--enable-modules</option> option when configuring <systemitem
class="daemon">slapd</systemitem>. Modules are stored in files with the
<emphasis>.la</emphasis> extension:
+ </para>
+
<synopsis><replaceable>module_name</replaceable>.la</synopsis>
+ <para>
+ <firstterm>Backends</firstterm> store or retrieve data in response to
LDAP requests. Backends may be compiled statically into <systemitem
class="daemon">slapd</systemitem>, or when module support is enabled,
they may be dynamically loaded. In the latter case, the following naming convention is
applied:
+ </para>
+
<synopsis>back_<replaceable>backend_name</replaceable>.la</synopsis>
+ <para>
+ To load a module or a backend, use the following directive in <filename
class="directory">/etc/openldap/slapd.d/</filename>:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <option>olcModuleLoad</option>
+ </term>
+ <listitem>
+ <para>
+ The <option>olcModuleLoad</option> directive specifies a
dynamically loadable module to load. It takes the following form:
+ </para>
+ <synopsis><option>olcModuleLoad</option>:
<replaceable>module</replaceable></synopsis>
+ <para>
+ Here, <replaceable>module</replaceable> stands either for a
file containing the module, or a backend, that will be loaded.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+ </section>
+ <section id="s2-selinux-openldap">
+ <title>SELinux Policy for Applications Using LDAP</title>
+ <para>
+ SELinux is an implementation of a mandatory access control mechanism in the Linux
kernel. By default, SELinux prevents applications from accessing an OpenLDAP server. To
enable authentication through LDAP, which is required by several applications, the
<systemitem>allow_ypbind</systemitem> SELinux Boolean needs to be enabled.
Certain applications also demand an enabled
<systemitem>authlogin_nsswitch_use_ldap</systemitem> Boolean in this scenario.
Execute the following commands to enable the aforementioned Booleans:
+ </para>
+ <synopsis>~]# <command>setsebool</command>
<option>-P</option>
<option>allow_ypbind</option>=<literal>1</literal></synopsis>
+ <synopsis>~]# <command>setsebool</command>
<option>-P</option>
<option>authlogin_nsswitch_use_ldap</option>=<literal>1</literal></synopsis>
+ <para>
+ The <option>-P</option> option makes this setting persistent across
system reboots. See the <ulink
url="https://access.redhat.com/documentation/en-US/Red_Hat_Enterpris...
Enterprise Linux 7 SELinux User's and Administrator's
Guide</ulink> for more detailed information about SELinux.
+ </para>
</section>
<section id="s2-ldap-running">
<title>Running an OpenLDAP Server</title>