| blob | 4d79895985fce9ceff475060dca74725447800ee |
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>
10 <sect1 id="s1-intro-ldap-tls">
11 <title>Introduction</title>
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>
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>
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>
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>
46 <para>
47 We will discuss this more in the next sections.
48 </para>
50 </sect1>
52 <sect1 id="s1-config-ldap-tls">
53 <title>Configuring</title>
55 <para>
56 <indexterm><primary>Transport Layer Seccurity, TLS</primary><secondary>Configuring</secondary></indexterm>
57 Now on to the good bit.
58 </para>
60 <sect2 id="s1-config-ldap-tls-certs">
61 <title>Generating the Certificate Authority</title>
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>
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>
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>
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>
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)
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>
140 <para>
141 There are some things to note here.
142 </para>
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>
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>
160 </sect2>
162 <sect2 id="s1-config-ldap-tls-server">
163 <title>Generating the Server Certificate</title>
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
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>
198 <para>
199 Again, there are some things to note here.
200 </para>
202 <orderedlist>
203 <listitem>
204 <para>
205 You should <emphasis>NOT</emphasis> enter a password.
206 </para>
207 </listitem>
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>
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
252 Certificate is to be certified until Mar 6 18:22:26 2006 EDT (365 days)
253 Sign the certificate? [y/n]:y
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>
264 <para>
265 That completes the server certificate generation.
266 </para>
268 </sect2>
270 <sect2 id="s1-config-ldap-tls-install">
271 <title>Installing the Certificates</title>
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>
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>
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>
311 <para>
312 That's all there is to it. Now on to <xref linkend="s1-test-ldap-tls"></xref>
313 </para>
315 </sect2>
317 </sect1>
319 <sect1 id="s1-test-ldap-tls">
320 <title>Testing</title>
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
347 # extended LDIF
348 #
349 # LDAPv3
350 # base <> with scope sub
351 # filter: (objectclass=*)
352 # requesting: ALL
353 #
355 # abmas.biz
356 dn: dc=ldap,dc=abmas,dc=biz
357 objectClass: dcObject
358 objectClass: organization
359 o: Abmas
360 dc: abmas
362 # Manager, ldap.abmas.biz
363 dn: cn=Manager,dc=ldap,dc=abmas,dc=biz
364 objectClass: organizationalRole
365 cn: Manager
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>
380 </sect1>
382 <sect1 id="s1-int-ldap-tls">
383 <title>Troubleshooting</title>
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>
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>
399 <para>
400 For anything else, it's best to read through your ldap logfile or join the &OL; mailing list.
401 </para>
403 </sect1>
405 </chapter>