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