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">
7 <pubdate>July 8, 2005</pubdate>
9 <title>LDAP and Transport Layer Security</title>
11 <sect1 id="s1-intro-ldap-tls">
12 <title>Introduction</title>
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>
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>
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.
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>.
48 We will discuss this more in the next sections.
53 <sect1 id="s1-config-ldap-tls">
54 <title>Configuring</title>
57 <indexterm><primary>Transport Layer Seccurity, TLS</primary><secondary>Configuring</secondary></indexterm>
58 Now on to the good bit.
61 <sect2 id="s1-config-ldap-tls-certs">
62 <title>Generating the Certificate Authority</title>
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.
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.
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;.
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.
94 First we need to generate the CA:
97 &rootprompt; mkdir myCA
100 Move into that directory:
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>
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:
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.
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
142 There are some things to note here.
148 You <emphasis>MUST</emphasis> remember the password, as we will need
149 it to sign the server certificate..
155 The <emphasis>Common Name (CN)</emphasis>, <emphasis>MUST</emphasis> be the
156 fully qualified domain name (FQDN) of your ldap server.
163 <sect2 id="s1-config-ldap-tls-server">
164 <title>Generating the Server Certificate</title>
167 Now we need to generate the server certificate:
170 &rootprompt; openssl req -new -nodes -keyout newreq.pem -out newreq.pem
171 Generating a 1024 bit RSA private key
173 ........................................................++++++
174 writing new private key to 'newreq.pem'
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.
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 []:
200 Again, there are some things to note here.
206 You should <emphasis>NOT</emphasis> enter a password.
212 The <emphasis>Common Name (CN)</emphasis>, <emphasis>MUST</emphasis> be
213 the fully qualified domain name (FQDN) of your ldap server.
219 Now we sign the certificate with the new CA:
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
228 Serial Number: 1 (0x1)
230 Not Before: Mar 6 18:22:26 2005 EDT
231 Not After : Mar 6 18:22:26 2006 EDT
234 stateOrProvinceName = NSW
235 localityName = Sydney
236 organizationName = Abmas
237 organizationalUnitName = IT
238 commonName = ldap.abmas.biz
239 emailAddress = support@abmas.biz
241 X509v3 Basic Constraints:
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
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
260 Signed certificate is in newcert.pem
266 That completes the server certificate generation.
271 <sect2 id="s1-config-ldap-tls-install">
272 <title>Installing the Certificates</title>
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:
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
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:
295 TLSCertificateFile /etc/openldap/servercrt.pem
296 TLSCertificateKeyFile /etc/openldap/serverkey.pem
297 TLSCACertificateFile /etc/openldap/cacert.pem
303 Here is the declaration and <filename>ldap.conf</filename>:
304 <filename>ldap.conf</filename>
307 TLS_CACERT /etc/openldap/cacert.pem
313 That's all there is to it. Now on to <xref linkend="s1-test-ldap-tls"></xref>
320 <sect1 id="s1-test-ldap-tls">
321 <title>Testing</title>
324 <indexterm><primary>Transport Layer Security, TLS</primary><secondary>Testing</secondary></indexterm>
325 This is the easy part. Restart the server:
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 ]
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:
338 &rootprompt; ldapsearch -x -b "dc=ldap,dc=abmas,dc=biz" \
339 -H 'ldap://ldap.abmas.biz:389' -ZZ
342 Your results should be the same as before you restarted the server, for example:
345 &rootprompt; ldapsearch -x -b "dc=ldap,dc=abmas,dc=biz" \
346 -H 'ldap://ldap.abmas.biz:389' -ZZ
351 # base <> with scope sub
352 # filter: (objectclass=*)
357 dn: dc=ldap,dc=abmas,dc=biz
358 objectClass: dcObject
359 objectClass: organization
363 # Manager, ldap.abmas.biz
364 dn: cn=Manager,dc=ldap,dc=abmas,dc=biz
365 objectClass: organizationalRole
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
378 If you have any problems, please read <xref linkend="s1-int-ldap-tls"></xref>
383 <sect1 id="s1-int-ldap-tls">
384 <title>Troubleshooting</title>
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.
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>.
401 For anything else, it's best to read through your ldap logfile or join the &OL; mailing list.