s3-server_id change pid to hyper
[Samba.git] / docs-xml / Samba3-HOWTO / TOSHARG-SecureLDAP.xml
blob4d79895985fce9ceff475060dca74725447800ee
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)
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>
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
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> 
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
349 # LDAPv3
350 # base &lt;&gt; with scope sub
351 # filter: (objectclass=*)
352 # requesting: ALL
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>