docs/Samba3-HOWTO/TOSHARG-SecureLDAP.xml

   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
 112 CA certificate filename (or enter to create)
 113
 114 Making CA certificate ...
 115 Generating a 1024 bit RSA private key
 116 .......................++++++
 117 .............................++++++
 118 writing new private key to './demoCA/private/cakey.pem'
 119 Enter PEM pass phrase:
 120 Verifying - Enter PEM pass phrase:
 121 -----
 122 You are about to be asked to enter information that will be incorporated
 123 into your certificate request.
 124 What you are about to enter is what is called a Distinguished Name or a DN.
 125 There are quite a few fields but you can leave some blank
 126 For some fields there will be a default value,
 127 If you enter '.', the field will be left blank.
 128 -----
 129 Country Name (2 letter code) [AU]:AU
 130 State or Province Name (full name) [Some-State]:NSW
 131 Locality Name (eg, city) []:Sydney
 132 Organization Name (eg, company) [Internet Widgits Pty Ltd]:Abmas
 133 Organizational Unit Name (eg, section) []:IT
 134 Common Name (eg, YOUR name) []:ldap.abmas.biz
 135 Email 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
 170 Generating a 1024 bit RSA private key
 171 .............++++++
 172 ........................................................++++++
 173 writing new private key to 'newreq.pem'
 174 -----
 175 You are about to be asked to enter information that will be incorporated
 176 into your certificate request.
 177 What you are about to enter is what is called a Distinguished Name or a DN.
 178 There are quite a few fields but you can leave some blank
 179 For some fields there will be a default value,
 180 If you enter '.', the field will be left blank.
 181 -----
 182 Country Name (2 letter code) [AU]:AU
 183 State or Province Name (full name) [Some-State]:NSW
 184 Locality Name (eg, city) []:Sydney
 185 Organization Name (eg, company) [Internet Widgits Pty Ltd]:Abmas
 186 Organizational Unit Name (eg, section) []:IT
 187 Common Name (eg, YOUR name) []:ldap.abmas.biz
 188 Email Address []:support@abmas.biz
 189
 190 Please enter the following 'extra' attributes
 191 to be sent with your certificate request
 192 A challenge password []:
 193 An 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
 222 Using configuration from /etc/ssl/openssl.cnf
 223 Enter pass phrase for ./demoCA/private/cakey.pem:
 224 Check that the request matches the signature
 225 Signature ok
 226 Certificate Details:
 227 Serial Number: 1 (0x1)
 228 Validity
 229         Not Before: Mar  6 18:22:26 2005 EDT
 230         Not After : Mar  6 18:22:26 2006 EDT
 231 Subject:
 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
 239 X509v3 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
 252 Certificate is to be certified until Mar  6 18:22:26 2006 EDT (365 days)
 253 Sign the certificate? [y/n]:y
 254
 255
 256 1 out of 1 certificate requests certified, commit? [y/n]y
 257 Write out database with 1 new entries
 258 Data Base Updated
 259 Signed 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>
 294 TLSCertificateFile /etc/openldap/servercrt.pem
 295 TLSCertificateKeyFile /etc/openldap/serverkey.pem
 296 TLSCACertificateFile /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>
 306 TLS_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>
 324 This is the easy part. Restart the server:
 325 <screen width="90">
 326 <computeroutput>
 327 &rootprompt; /etc/init.d/ldap restart
 328 Stopping slapd:                                            [  OK  ]
 329 Checking configuration files for slapd: config file testing succeeded
 330 Starting 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 &lt;&gt; with scope sub
 351 # filter: (objectclass=*)
 352 # requesting: ALL
 353 #
 354
 355 # abmas.biz
 356 dn: dc=ldap,dc=abmas,dc=biz
 357 objectClass: dcObject
 358 objectClass: organization
 359 o: Abmas
 360 dc: abmas
 361
 362 # Manager, ldap.abmas.biz
 363 dn: cn=Manager,dc=ldap,dc=abmas,dc=biz
 364 objectClass: organizationalRole
 365 cn: Manager
 366
 367 # ABMAS, abmas.biz
 368 dn: sambaDomainName=ABMAS,dc=ldap,dc=abmas,dc=biz
 369 sambaDomainName: ABMAS
 370 sambaSID: S-1-5-21-238355452-1056757430-1592208922
 371 sambaAlgorithmicRidBase: 1000
 372 objectClass: sambaDomain
 373 sambaNextUserRid: 67109862
 374 sambaNextGroupRid: 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>
 387 The 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>
 393 Other errors could be that you have a typo somewhere in your <command>ldapsearch</command> command, or that
 394 your have the wrong permissions on the <filename>servercrt.pem</filename> and <filename>cacert.pem</filename>
 395 files. They should be set with <command>chmod 640</command>, as per <xref
 396 linkend="s1-config-ldap-tls-install"></xref>.
 397 </para>
 398
 399 <para>
 400 For 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>