diff options
Diffstat (limited to 'docs-xml/Samba3-HOWTO/TOSHARG-SecureLDAP.xml')
| -rw-r--r-- | docs-xml/Samba3-HOWTO/TOSHARG-SecureLDAP.xml | 405 |
1 files changed, 405 insertions, 0 deletions
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-SecureLDAP.xml b/docs-xml/Samba3-HOWTO/TOSHARG-SecureLDAP.xml new file mode 100644 index 00000000000..4d79895985f --- /dev/null +++ b/docs-xml/Samba3-HOWTO/TOSHARG-SecureLDAP.xml @@ -0,0 +1,405 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="ch-ldap-tls"> +<chapterinfo> + &author.ghenry; + <pubdate>July 8, 2005</pubdate> +</chapterinfo> +<title>LDAP and Transport Layer Security</title> + +<sect1 id="s1-intro-ldap-tls"> +<title>Introduction</title> + + <para> + <indexterm><primary>Transport Layer Seccurity, TLS</primary><secondary>Introduction</secondary></indexterm> +<indexterm><primary>ACL</primary></indexterm> + Up until now, we have discussed the straightforward configuration of <trademark>OpenLDAP</trademark>, + with some advanced features such as ACLs. This does not however, deal with the fact that the network + transmissions are still in plain text. This is where <firstterm>Transport Layer Security (TLS)</firstterm> + comes in. + </para> + + <para> +<indexterm><primary>RFC 2830</primary></indexterm> + <trademark>OpenLDAP</trademark> clients and servers are capable of using the Transport Layer Security (TLS) + framework to provide integrity and confidentiality protections in accordance with <ulink + url="http://rfc.net/rfc2830.html">RFC 2830</ulink>; <emphasis>Lightweight Directory Access Protocol (v3): + Extension for Transport Layer Security.</emphasis> + </para> + + <para> +<indexterm><primary>X.509 certificates</primary></indexterm> + TLS uses X.509 certificates. All servers are required to have valid certificates, whereas client certificates + are optional. We will only be discussing server certificates. + </para> + + <tip><para> +<indexterm><primary>DN</primary></indexterm> +<indexterm><primary>CN</primary></indexterm> +<indexterm><primary>FQDN</primary></indexterm> + The DN of a server certificate must use the CN attribute to name the server, and the CN must carry the + server's fully qualified domain name (FQDN). Additional alias names and wildcards may be present in the + <option>subjectAltName</option> certificate extension. More details on server certificate names are in <ulink + url="http://rfc.net/rfc2830.html">RFC2830</ulink>. + </para></tip> + + <para> + We will discuss this more in the next sections. + </para> + + </sect1> + + <sect1 id="s1-config-ldap-tls"> + <title>Configuring</title> + + <para> + <indexterm><primary>Transport Layer Seccurity, TLS</primary><secondary>Configuring</secondary></indexterm> + Now on to the good bit. + </para> + + <sect2 id="s1-config-ldap-tls-certs"> + <title>Generating the Certificate Authority</title> + + <para> +<indexterm><primary>Certificate Authority</primary><see>CA</see></indexterm> + In order to create the relevant certificates, we need to become our own Certificate Authority (CA). + <footnote><para>We could however, get our generated server certificate signed by proper CAs, like <ulink + url="http://www.thawte.com/">Thawte</ulink> and <ulink url="http://www.verisign.com/">VeriSign</ulink>, which + you pay for, or the free ones, via <ulink url="http://www.cacert.org/">CAcert</ulink> + </para></footnote> This is necessary, so we can sign the server certificate. + </para> + + <para> +<indexterm><primary>OpenSSL</primary></indexterm> + We will be using the <ulink url="http://www.openssl.org">OpenSSL</ulink> <footnote><para>The downside to + making our own CA, is that the certificate is not automatically recognized by clients, like the commercial + ones are.</para></footnote> software for this, which is included with every great <trademark + class="registered">Linux</trademark> distribution. + </para> + + <para> + TLS is used for many types of servers, but the instructions<footnote><para>For information straight from the + horse's mouth, please visit <ulink + url="http://www.openssl.org/docs/HOWTO/">http://www.openssl.org/docs/HOWTO/</ulink>; the main OpenSSL + site.</para></footnote> presented here, are tailored for &OL;. + </para> + + <note><para> + The <emphasis>Common Name (CN)</emphasis>, in the following example, <emphasis>MUST</emphasis> be + the fully qualified domain name (FQDN) of your ldap server. + </para></note> + + <para> + First we need to generate the CA: +<screen width="90"> +<computeroutput> +&rootprompt; mkdir myCA +</computeroutput> +</screen> + Move into that directory: +<screen width="90"> +<computeroutput> +&rootprompt; cd myCA +</computeroutput> +</screen> + Now generate the CA:<footnote><para>Your <filename>CA.pl</filename> or <filename>CA.sh</filename> might not be + in the same location as mine is, you can find it by using the <command>locate</command> command, i.e., + <command>locate CA.pl</command>. If the command complains about the database being too old, run + <command>updatedb</command> as <emphasis>root</emphasis> to update it.</para></footnote> +<screen width="90"> +<computeroutput> +&rootprompt; /usr/share/ssl/misc/CA.pl -newca +CA certificate filename (or enter to create) + +Making CA certificate ... +Generating a 1024 bit RSA private key +.......................++++++ +.............................++++++ +writing new private key to './demoCA/private/cakey.pem' +Enter PEM pass phrase: +Verifying - Enter PEM pass phrase: +----- +You are about to be asked to enter information that will be incorporated +into your certificate request. +What you are about to enter is what is called a Distinguished Name or a DN. +There are quite a few fields but you can leave some blank +For some fields there will be a default value, +If you enter '.', the field will be left blank. +----- +Country Name (2 letter code) [AU]:AU +State or Province Name (full name) [Some-State]:NSW +Locality Name (eg, city) []:Sydney +Organization Name (eg, company) [Internet Widgits Pty Ltd]:Abmas +Organizational Unit Name (eg, section) []:IT +Common Name (eg, YOUR name) []:ldap.abmas.biz +Email Address []:support@abmas.biz +</computeroutput> +</screen> + </para> + + <para> + There are some things to note here. + </para> + + <orderedlist> + <listitem> + <para> + You <emphasis>MUST</emphasis> remember the password, as we will need + it to sign the server certificate.. + </para> + </listitem> + + <listitem> + <para> + The <emphasis>Common Name (CN)</emphasis>, <emphasis>MUST</emphasis> be the + fully qualified domain name (FQDN) of your ldap server. + </para> + </listitem> + </orderedlist> + + </sect2> + + <sect2 id="s1-config-ldap-tls-server"> + <title>Generating the Server Certificate</title> + + <para> + Now we need to generate the server certificate: +<screen width="90"> +<computeroutput> +&rootprompt; openssl req -new -nodes -keyout newreq.pem -out newreq.pem +Generating a 1024 bit RSA private key +.............++++++ +........................................................++++++ +writing new private key to 'newreq.pem' +----- +You are about to be asked to enter information that will be incorporated +into your certificate request. +What you are about to enter is what is called a Distinguished Name or a DN. +There are quite a few fields but you can leave some blank +For some fields there will be a default value, +If you enter '.', the field will be left blank. +----- +Country Name (2 letter code) [AU]:AU +State or Province Name (full name) [Some-State]:NSW +Locality Name (eg, city) []:Sydney +Organization Name (eg, company) [Internet Widgits Pty Ltd]:Abmas +Organizational Unit Name (eg, section) []:IT +Common Name (eg, YOUR name) []:ldap.abmas.biz +Email Address []:support@abmas.biz + +Please enter the following 'extra' attributes +to be sent with your certificate request +A challenge password []: +An optional company name []: +</computeroutput> +</screen> + </para> + + <para> + Again, there are some things to note here. + </para> + + <orderedlist> + <listitem> + <para> + You should <emphasis>NOT</emphasis> enter a password. + </para> + </listitem> + + <listitem> + <para> + The <emphasis>Common Name (CN)</emphasis>, <emphasis>MUST</emphasis> be + the fully qualified domain name (FQDN) of your ldap server. + </para> + </listitem> + </orderedlist> + + <para> + Now we sign the certificate with the new CA: +<screen width="90"> +<computeroutput> +&rootprompt; /usr/share/ssl/misc/CA.pl -sign +Using configuration from /etc/ssl/openssl.cnf +Enter pass phrase for ./demoCA/private/cakey.pem: +Check that the request matches the signature +Signature ok +Certificate Details: +Serial Number: 1 (0x1) +Validity + Not Before: Mar 6 18:22:26 2005 EDT + Not After : Mar 6 18:22:26 2006 EDT +Subject: + countryName = AU + stateOrProvinceName = NSW + localityName = Sydney + organizationName = Abmas + organizationalUnitName = IT + commonName = ldap.abmas.biz + emailAddress = support@abmas.biz +X509v3 extensions: + X509v3 Basic Constraints: + CA:FALSE + Netscape Comment: + OpenSSL Generated Certificate + X509v3 Subject Key Identifier: + F7:84:87:25:C4:E8:46:6D:0F:47:27:91:F0:16:E0:86:6A:EE:A3:CE + X509v3 Authority Key Identifier: + keyid:27:44:63:3A:CB:09:DC:B1:FF:32:CC:93:23:A4:F1:B4:D5:F0:7E:CC + DirName:/C=AU/ST=NSW/L=Sydney/O=Abmas/OU=IT/ + CN=ldap.abmas.biz/emailAddress=support@abmas.biz + serial:00 + +Certificate is to be certified until Mar 6 18:22:26 2006 EDT (365 days) +Sign the certificate? [y/n]:y + + +1 out of 1 certificate requests certified, commit? [y/n]y +Write out database with 1 new entries +Data Base Updated +Signed certificate is in newcert.pem +</computeroutput> +</screen> + </para> + + <para> + That completes the server certificate generation. + </para> + + </sect2> + + <sect2 id="s1-config-ldap-tls-install"> + <title>Installing the Certificates</title> + + <para> + Now we need to copy the certificates to the right configuration directories, + rename them at the same time (for convenience), change the ownership and + finally the permissions: +<screen width="90"> +<computeroutput> +&rootprompt; cp demoCA/cacert.pem /etc/openldap/ +&rootprompt; cp newcert.pem /etc/openldap/servercrt.pem +&rootprompt; cp newreq.pem /etc/openldap/serverkey.pem +&rootprompt; chown ldap.ldap /etc/openldap/*.pem +&rootprompt; chmod 640 /etc/openldap/cacert.pem; +&rootprompt; chmod 600 /etc/openldap/serverkey.pem +</computeroutput> +</screen> + </para> + + <para> + Now we just need to add these locations to <filename>slapd.conf</filename>, + anywhere before the <option>database</option> declaration as shown here: +<screen width="90"> +<computeroutput> +TLSCertificateFile /etc/openldap/servercrt.pem +TLSCertificateKeyFile /etc/openldap/serverkey.pem +TLSCACertificateFile /etc/openldap/cacert.pem +</computeroutput> +</screen> + </para> + + <para> + Here is the declaration and <filename>ldap.conf</filename>: +<filename>ldap.conf</filename> +<screen width="90"> +<computeroutput> +TLS_CACERT /etc/openldap/cacert.pem +</computeroutput> +</screen> + </para> + + <para> + That's all there is to it. Now on to <xref linkend="s1-test-ldap-tls"></xref> + </para> + + </sect2> + +</sect1> + +<sect1 id="s1-test-ldap-tls"> +<title>Testing</title> + +<para> +<indexterm><primary>Transport Layer Security, TLS</primary><secondary>Testing</secondary></indexterm> +This is the easy part. Restart the server: +<screen width="90"> +<computeroutput> +&rootprompt; /etc/init.d/ldap restart +Stopping slapd: [ OK ] +Checking configuration files for slapd: config file testing succeeded +Starting slapd: [ OK ] +</computeroutput> +</screen> + Then, using <command>ldapsearch</command>, test an anonymous search with the + <option>-ZZ</option><footnote><para>See <command>man ldapsearch</command></para></footnote> option: +<screen width="90"> +<computeroutput> +&rootprompt; ldapsearch -x -b "dc=ldap,dc=abmas,dc=biz" \ + -H 'ldap://ldap.abmas.biz:389' -ZZ +</computeroutput> +</screen> + Your results should be the same as before you restarted the server, for example: +<screen width="90"> +<computeroutput> +&rootprompt; ldapsearch -x -b "dc=ldap,dc=abmas,dc=biz" \ + -H 'ldap://ldap.abmas.biz:389' -ZZ + +# extended LDIF +# +# LDAPv3 +# base <> with scope sub +# filter: (objectclass=*) +# requesting: ALL +# + +# abmas.biz +dn: dc=ldap,dc=abmas,dc=biz +objectClass: dcObject +objectClass: organization +o: Abmas +dc: abmas + +# Manager, ldap.abmas.biz +dn: cn=Manager,dc=ldap,dc=abmas,dc=biz +objectClass: organizationalRole +cn: Manager + +# ABMAS, abmas.biz +dn: sambaDomainName=ABMAS,dc=ldap,dc=abmas,dc=biz +sambaDomainName: ABMAS +sambaSID: S-1-5-21-238355452-1056757430-1592208922 +sambaAlgorithmicRidBase: 1000 +objectClass: sambaDomain +sambaNextUserRid: 67109862 +sambaNextGroupRid: 67109863 +</computeroutput> +</screen> + If you have any problems, please read <xref linkend="s1-int-ldap-tls"></xref> +</para> + +</sect1> + +<sect1 id="s1-int-ldap-tls"> +<title>Troubleshooting</title> + +<para> +<indexterm><primary>Transport Layer Security, TLS</primary><secondary>Troubleshooting</secondary></indexterm> +The most common error when configuring TLS, as I have already mentioned numerous times, is that the +<emphasis>Common Name (CN)</emphasis> you entered in <xref linkend="s1-config-ldap-tls-server"></xref> is +<emphasis>NOT</emphasis> the Fully Qualified Domain Name (FQDN) of your ldap server. +</para> + +<para> +Other errors could be that you have a typo somewhere in your <command>ldapsearch</command> command, or that +your have the wrong permissions on the <filename>servercrt.pem</filename> and <filename>cacert.pem</filename> +files. They should be set with <command>chmod 640</command>, as per <xref +linkend="s1-config-ldap-tls-install"></xref>. +</para> + +<para> +For anything else, it's best to read through your ldap logfile or join the &OL; mailing list. +</para> + +</sect1> + +</chapter> |