[system-administrators-guide/21] Establishing a Secure Connection
stephenw
stephenw at fedoraproject.org
Wed Mar 4 08:27:51 UTC 2015
commit 5a06ff2d27e84769d3fab69c729ddedecbb5ff7d
Author: Stephen Wadeley <swadeley at 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"><citetitle 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_Enterprise_Linux/7/html/SELinux_Users_and_Administrators_Guide/">Red Hat 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>
More information about the docs-commits
mailing list