1<?xml version="1.0" encoding="iso-8859-1"?> 2<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> 3<chapter id="ch-ldap-tls"> 4<chapterinfo> 5 &author.ghenry; 6 <pubdate>July 8, 2005</pubdate> 7</chapterinfo> 8<title>LDAP and Transport Layer Security</title> 9 10<sect1 id="s1-intro-ldap-tls"> 11<title>Introduction</title> 12 13 <para> 14 <indexterm><primary>Transport Layer Seccurity, TLS</primary><secondary>Introduction</secondary></indexterm> 15<indexterm><primary>ACL</primary></indexterm> 16 Up until now, we have discussed the straightforward configuration of <trademark>OpenLDAP</trademark>, 17 with some advanced features such as ACLs. This does not however, deal with the fact that the network 18 transmissions are still in plain text. This is where <firstterm>Transport Layer Security (TLS)</firstterm> 19 comes in. 20 </para> 21 22 <para> 23<indexterm><primary>RFC 2830</primary></indexterm> 24 <trademark>OpenLDAP</trademark> clients and servers are capable of using the Transport Layer Security (TLS) 25 framework to provide integrity and confidentiality protections in accordance with <ulink 26 url="http://rfc.net/rfc2830.html">RFC 2830</ulink>; <emphasis>Lightweight Directory Access Protocol (v3): 27 Extension for Transport Layer Security.</emphasis> 28 </para> 29 30 <para> 31<indexterm><primary>X.509 certificates</primary></indexterm> 32 TLS uses X.509 certificates. All servers are required to have valid certificates, whereas client certificates 33 are optional. We will only be discussing server certificates. 34 </para> 35 36 <tip><para> 37<indexterm><primary>DN</primary></indexterm> 38<indexterm><primary>CN</primary></indexterm> 39<indexterm><primary>FQDN</primary></indexterm> 40 The DN of a server certificate must use the CN attribute to name the server, and the CN must carry the 41 server's fully qualified domain name (FQDN). Additional alias names and wildcards may be present in the 42 <option>subjectAltName</option> certificate extension. More details on server certificate names are in <ulink 43 url="http://rfc.net/rfc2830.html">RFC2830</ulink>. 44 </para></tip> 45 46 <para> 47 We will discuss this more in the next sections. 48 </para> 49 50 </sect1> 51 52 <sect1 id="s1-config-ldap-tls"> 53 <title>Configuring</title> 54 55 <para> 56 <indexterm><primary>Transport Layer Seccurity, TLS</primary><secondary>Configuring</secondary></indexterm> 57 Now on to the good bit. 58 </para> 59 60 <sect2 id="s1-config-ldap-tls-certs"> 61 <title>Generating the Certificate Authority</title> 62 63 <para> 64<indexterm><primary>Certificate Authority</primary><see>CA</see></indexterm> 65 In order to create the relevant certificates, we need to become our own Certificate Authority (CA). 66 <footnote><para>We could however, get our generated server certificate signed by proper CAs, like <ulink 67 url="http://www.thawte.com/">Thawte</ulink> and <ulink url="http://www.verisign.com/">VeriSign</ulink>, which 68 you pay for, or the free ones, via <ulink url="http://www.cacert.org/">CAcert</ulink> 69 </para></footnote> This is necessary, so we can sign the server certificate. 70 </para> 71 72 <para> 73<indexterm><primary>OpenSSL</primary></indexterm> 74 We will be using the <ulink url="http://www.openssl.org">OpenSSL</ulink> <footnote><para>The downside to 75 making our own CA, is that the certificate is not automatically recognized by clients, like the commercial 76 ones are.</para></footnote> software for this, which is included with every great <trademark 77 class="registered">Linux</trademark> distribution. 78 </para> 79 80 <para> 81 TLS is used for many types of servers, but the instructions<footnote><para>For information straight from the 82 horse's mouth, please visit <ulink 83 url="http://www.openssl.org/docs/HOWTO/">http://www.openssl.org/docs/HOWTO/</ulink>; the main OpenSSL 84 site.</para></footnote> presented here, are tailored for &OL;. 85 </para> 86 87 <note><para> 88 The <emphasis>Common Name (CN)</emphasis>, in the following example, <emphasis>MUST</emphasis> be 89 the fully qualified domain name (FQDN) of your ldap server. 90 </para></note> 91 92 <para> 93 First we need to generate the CA: 94<screen width="90"> 95<computeroutput> 96&rootprompt; mkdir myCA 97</computeroutput> 98</screen> 99 Move into that directory: 100<screen width="90"> 101<computeroutput> 102&rootprompt; cd myCA 103</computeroutput> 104</screen> 105 Now generate the CA:<footnote><para>Your <filename>CA.pl</filename> or <filename>CA.sh</filename> might not be 106 in the same location as mine is, you can find it by using the <command>locate</command> command, i.e., 107 <command>locate CA.pl</command>. If the command complains about the database being too old, run 108 <command>updatedb</command> as <emphasis>root</emphasis> to update it.</para></footnote> 109<screen width="90"> 110<computeroutput> 111&rootprompt; /usr/share/ssl/misc/CA.pl -newca 112CA certificate filename (or enter to create) 113 114Making CA certificate ... 115Generating a 1024 bit RSA private key 116.......................++++++ 117.............................++++++ 118writing new private key to './demoCA/private/cakey.pem' 119Enter PEM pass phrase: 120Verifying - Enter PEM pass phrase: 121----- 122You are about to be asked to enter information that will be incorporated 123into your certificate request. 124What you are about to enter is what is called a Distinguished Name or a DN. 125There are quite a few fields but you can leave some blank 126For some fields there will be a default value, 127If you enter '.', the field will be left blank. 128----- 129Country Name (2 letter code) [AU]:AU 130State or Province Name (full name) [Some-State]:NSW 131Locality Name (eg, city) []:Sydney 132Organization Name (eg, company) [Internet Widgits Pty Ltd]:Abmas 133Organizational Unit Name (eg, section) []:IT 134Common Name (eg, YOUR name) []:ldap.abmas.biz 135Email Address []:support@abmas.biz 136</computeroutput> 137</screen> 138 </para> 139 140 <para> 141 There are some things to note here. 142 </para> 143 144 <orderedlist> 145 <listitem> 146 <para> 147 You <emphasis>MUST</emphasis> remember the password, as we will need 148 it to sign the server certificate.. 149 </para> 150 </listitem> 151 152 <listitem> 153 <para> 154 The <emphasis>Common Name (CN)</emphasis>, <emphasis>MUST</emphasis> be the 155 fully qualified domain name (FQDN) of your ldap server. 156 </para> 157 </listitem> 158 </orderedlist> 159 160 </sect2> 161 162 <sect2 id="s1-config-ldap-tls-server"> 163 <title>Generating the Server Certificate</title> 164 165 <para> 166 Now we need to generate the server certificate: 167<screen width="90"> 168<computeroutput> 169&rootprompt; openssl req -new -nodes -keyout newreq.pem -out newreq.pem 170Generating a 1024 bit RSA private key 171.............++++++ 172........................................................++++++ 173writing new private key to 'newreq.pem' 174----- 175You are about to be asked to enter information that will be incorporated 176into your certificate request. 177What you are about to enter is what is called a Distinguished Name or a DN. 178There are quite a few fields but you can leave some blank 179For some fields there will be a default value, 180If you enter '.', the field will be left blank. 181----- 182Country Name (2 letter code) [AU]:AU 183State or Province Name (full name) [Some-State]:NSW 184Locality Name (eg, city) []:Sydney 185Organization Name (eg, company) [Internet Widgits Pty Ltd]:Abmas 186Organizational Unit Name (eg, section) []:IT 187Common Name (eg, YOUR name) []:ldap.abmas.biz 188Email Address []:support@abmas.biz 189 190Please enter the following 'extra' attributes 191to be sent with your certificate request 192A challenge password []: 193An optional company name []: 194</computeroutput> 195</screen> 196 </para> 197 198 <para> 199 Again, there are some things to note here. 200 </para> 201 202 <orderedlist> 203 <listitem> 204 <para> 205 You should <emphasis>NOT</emphasis> enter a password. 206 </para> 207 </listitem> 208 209 <listitem> 210 <para> 211 The <emphasis>Common Name (CN)</emphasis>, <emphasis>MUST</emphasis> be 212 the fully qualified domain name (FQDN) of your ldap server. 213 </para> 214 </listitem> 215 </orderedlist> 216 217 <para> 218 Now we sign the certificate with the new CA: 219<screen width="90"> 220<computeroutput> 221&rootprompt; /usr/share/ssl/misc/CA.pl -sign 222Using configuration from /etc/ssl/openssl.cnf 223Enter pass phrase for ./demoCA/private/cakey.pem: 224Check that the request matches the signature 225Signature ok 226Certificate Details: 227Serial Number: 1 (0x1) 228Validity 229 Not Before: Mar 6 18:22:26 2005 EDT 230 Not After : Mar 6 18:22:26 2006 EDT 231Subject: 232 countryName = AU 233 stateOrProvinceName = NSW 234 localityName = Sydney 235 organizationName = Abmas 236 organizationalUnitName = IT 237 commonName = ldap.abmas.biz 238 emailAddress = support@abmas.biz 239X509v3 extensions: 240 X509v3 Basic Constraints: 241 CA:FALSE 242 Netscape Comment: 243 OpenSSL Generated Certificate 244 X509v3 Subject Key Identifier: 245 F7:84:87:25:C4:E8:46:6D:0F:47:27:91:F0:16:E0:86:6A:EE:A3:CE 246 X509v3 Authority Key Identifier: 247 keyid:27:44:63:3A:CB:09:DC:B1:FF:32:CC:93:23:A4:F1:B4:D5:F0:7E:CC 248 DirName:/C=AU/ST=NSW/L=Sydney/O=Abmas/OU=IT/ 249 CN=ldap.abmas.biz/emailAddress=support@abmas.biz 250 serial:00 251 252Certificate is to be certified until Mar 6 18:22:26 2006 EDT (365 days) 253Sign the certificate? [y/n]:y 254 255 2561 out of 1 certificate requests certified, commit? [y/n]y 257Write out database with 1 new entries 258Data Base Updated 259Signed certificate is in newcert.pem 260</computeroutput> 261</screen> 262 </para> 263 264 <para> 265 That completes the server certificate generation. 266 </para> 267 268 </sect2> 269 270 <sect2 id="s1-config-ldap-tls-install"> 271 <title>Installing the Certificates</title> 272 273 <para> 274 Now we need to copy the certificates to the right configuration directories, 275 rename them at the same time (for convenience), change the ownership and 276 finally the permissions: 277<screen width="90"> 278<computeroutput> 279&rootprompt; cp demoCA/cacert.pem /etc/openldap/ 280&rootprompt; cp newcert.pem /etc/openldap/servercrt.pem 281&rootprompt; cp newreq.pem /etc/openldap/serverkey.pem 282&rootprompt; chown ldap.ldap /etc/openldap/*.pem 283&rootprompt; chmod 640 /etc/openldap/cacert.pem; 284&rootprompt; chmod 600 /etc/openldap/serverkey.pem 285</computeroutput> 286</screen> 287 </para> 288 289 <para> 290 Now we just need to add these locations to <filename>slapd.conf</filename>, 291 anywhere before the <option>database</option> declaration as shown here: 292<screen width="90"> 293<computeroutput> 294TLSCertificateFile /etc/openldap/servercrt.pem 295TLSCertificateKeyFile /etc/openldap/serverkey.pem 296TLSCACertificateFile /etc/openldap/cacert.pem 297</computeroutput> 298</screen> 299 </para> 300 301 <para> 302 Here is the declaration and <filename>ldap.conf</filename>: 303<filename>ldap.conf</filename> 304<screen width="90"> 305<computeroutput> 306TLS_CACERT /etc/openldap/cacert.pem 307</computeroutput> 308</screen> 309 </para> 310 311 <para> 312 That's all there is to it. Now on to <xref linkend="s1-test-ldap-tls"></xref> 313 </para> 314 315 </sect2> 316 317</sect1> 318 319<sect1 id="s1-test-ldap-tls"> 320<title>Testing</title> 321 322<para> 323<indexterm><primary>Transport Layer Security, TLS</primary><secondary>Testing</secondary></indexterm> 324This is the easy part. Restart the server: 325<screen width="90"> 326<computeroutput> 327&rootprompt; /etc/init.d/ldap restart 328Stopping slapd: [ OK ] 329Checking configuration files for slapd: config file testing succeeded 330Starting slapd: [ OK ] 331</computeroutput> 332</screen> 333 Then, using <command>ldapsearch</command>, test an anonymous search with the 334 <option>-ZZ</option><footnote><para>See <command>man ldapsearch</command></para></footnote> option: 335<screen width="90"> 336<computeroutput> 337&rootprompt; ldapsearch -x -b "dc=ldap,dc=abmas,dc=biz" \ 338 -H 'ldap://ldap.abmas.biz:389' -ZZ 339</computeroutput> 340</screen> 341 Your results should be the same as before you restarted the server, for example: 342<screen width="90"> 343<computeroutput> 344&rootprompt; ldapsearch -x -b "dc=ldap,dc=abmas,dc=biz" \ 345 -H 'ldap://ldap.abmas.biz:389' -ZZ 346 347# extended LDIF 348# 349# LDAPv3 350# base <> with scope sub 351# filter: (objectclass=*) 352# requesting: ALL 353# 354 355# abmas.biz 356dn: dc=ldap,dc=abmas,dc=biz 357objectClass: dcObject 358objectClass: organization 359o: Abmas 360dc: abmas 361 362# Manager, ldap.abmas.biz 363dn: cn=Manager,dc=ldap,dc=abmas,dc=biz 364objectClass: organizationalRole 365cn: Manager 366 367# ABMAS, abmas.biz 368dn: sambaDomainName=ABMAS,dc=ldap,dc=abmas,dc=biz 369sambaDomainName: ABMAS 370sambaSID: S-1-5-21-238355452-1056757430-1592208922 371sambaAlgorithmicRidBase: 1000 372objectClass: sambaDomain 373sambaNextUserRid: 67109862 374sambaNextGroupRid: 67109863 375</computeroutput> 376</screen> 377 If you have any problems, please read <xref linkend="s1-int-ldap-tls"></xref> 378</para> 379 380</sect1> 381 382<sect1 id="s1-int-ldap-tls"> 383<title>Troubleshooting</title> 384 385<para> 386<indexterm><primary>Transport Layer Security, TLS</primary><secondary>Troubleshooting</secondary></indexterm> 387The most common error when configuring TLS, as I have already mentioned numerous times, is that the 388<emphasis>Common Name (CN)</emphasis> you entered in <xref linkend="s1-config-ldap-tls-server"></xref> is 389<emphasis>NOT</emphasis> the Fully Qualified Domain Name (FQDN) of your ldap server. 390</para> 391 392<para> 393Other errors could be that you have a typo somewhere in your <command>ldapsearch</command> command, or that 394your have the wrong permissions on the <filename>servercrt.pem</filename> and <filename>cacert.pem</filename> 395files. They should be set with <command>chmod 640</command>, as per <xref 396linkend="s1-config-ldap-tls-install"></xref>. 397</para> 398 399<para> 400For anything else, it's best to read through your ldap logfile or join the &OL; mailing list. 401</para> 402 403</sect1> 404 405</chapter> 406