s3-docs: add new pam_winbind.conf(5) manpage.
[kai/samba.git] / docs-xml / using_samba / appa.xml
1 <appendix label="A" id="SAMBA-AP-A">
2 <title>Configuring Samba with SSL</title>
3
4
5
6
7 <para>
8 <indexterm id="appa-idx-990325-0" class="startofrange"><primary>configuring Samba</primary><secondary sortas="SSL">with SSL</secondary></indexterm>
9 <indexterm id="appa-idx-990325-1" class="startofrange"><primary>SSL (Secure Sockets Layer) protocol</primary><secondary>configuring Samba with</secondary></indexterm>This appendix describes how to set up Samba to use secure connections between the Samba server and its clients. The protocol used here is Netscape's Secure Sockets Layer (SSL). For this example, we will establish a secure connection between a Samba server and a Windows NT workstation.</para>
10
11
12 <para>Before we begin, we will assume that you are familiar with the fundamentals of public-key cryptography and X.509 certificates. If not, we highly recommend Bruce Schneier's <filename>Applied Cryptography, 2nd Edition</filename> (Wiley) as the premiere source for learning the many secret faces of cryptography.</para>
13
14
15 <tip role="ora">
16 <para>If you would like more information on Samba and SSL, be sure to look at the document <filename>SSLeay.txt</filename> in the <filename>docs/textdocs</filename> directory of the Samba distribution, which is the basis for this appendix.</para>
17
18 </tip>
19
20
21
22
23
24
25
26
27
28
29
30 <sect1 role="" label="A.1" id="appa-SECT-1">
31 <title>About Certificates</title>
32
33
34 <para>Here are a few quick questions and answers from the <filename>SSLeay.txt</filename> file in the Samba documentation, regarding the benefits of SSL and certificates. This text was written by Christian Starkjohann for the Samba projects.</para>
35
36
37 <sect2 role="" label="A.1.1" id="appa-SECT-1.1">
38 <title>What is a Certificate?</title>
39
40
41 <para>A certificate is issued by an issuer, usually a <emphasis>Certification Authority</emphasis> (CA), who confirms something by issuing the certificate. The subject of this confirmation depends on the CA's policy. CAs for secure web servers (used for shopping malls, etc.) usually attest only that the given public key belongs the given domain name. Company-wide CAs might attest that you are an employee of the company, that you have permissions to use a server, and so on.</para>
42 </sect2>
43
44
45
46
47
48 <sect2 role="" label="A.1.2" id="appa-SECT-1.2">
49 <title>What is an X.509 certificate, technically?</title>
50
51
52 <para>Technically, the certificate is a block of data signed by the certificate issuer (the CA). The relevant fields are:</para>
53
54
55 <itemizedlist>
56
57 <listitem><para>
58 Unique identifier (name) of the certificate issuer</para></listitem>
59
60 <listitem><para>Time range during which the certificate is valid</para></listitem>
61
62 <listitem><para>Unique identifier (name) of the certified object</para></listitem>
63
64 <listitem><para>Public key of the certified object</para></listitem>
65
66 <listitem><para>The issuer's signature over all the above</para></listitem>
67
68 </itemizedlist>
69
70 <para>If this certificate is to be verified, the verifier must have a table of the names and public keys of trusted CAs. For simplicity, these tables should list certificates issued by the respective CAs for themselves (self-signed certificates).</para>
71 </sect2>
72
73
74
75
76
77 <sect2 role="" label="A.1.3" id="appa-SECT-1.3">
78 <title>What are the implications of this certificate structure?</title>
79
80
81 <para>Four implications follow:</para>
82
83
84 <itemizedlist>
85
86 <listitem><para>Because the certificate contains the subjects's public key, the certificate and the private key together are all that is needed to encrypt and decrypt.</para></listitem>
87
88 <listitem><para>To verify certificates, you need the certificates of all CAs you trust.</para></listitem>
89
90 <listitem><para>The simplest form of a dummy-certificate is one that is signed by the subject.</para></listitem>
91
92 <listitem><para>A CA is needed. The client can't simply issue local certificates for servers it trusts because the server determines which certificate it presents.</para></listitem>
93
94 </itemizedlist>
95 </sect2>
96 </sect1>
97
98
99
100
101
102
103
104
105
106 <sect1 role="" label="A.2" id="appa-SECT-2">
107 <title>Requirements</title>
108
109
110 <para>
111 <indexterm id="appa-idx-990348-0"><primary>configuring Samba</primary><secondary sortas="SSL">with SSL</secondary><tertiary>requirements for</tertiary></indexterm>
112 <indexterm id="appa-idx-990348-1"><primary>SSL (Secure Sockets Layer) protocol</primary><secondary>configuring Samba with</secondary><tertiary>requirements for</tertiary></indexterm>To set up SSL connections, you will need to download two programs in addition to Samba:</para>
113
114
115 <variablelist>
116 <varlistentry><term>
117 <indexterm id="appa-idx-990613-0" class="startofrange"><primary>SSL (Secure Sockets Layer) protocol</primary><secondary>SSLeay</secondary></indexterm>SSLeay</term>
118 <listitem><para>Eric <indexterm id="appa-idx-990362-0"><primary>Young, Eric</primary></indexterm>Young's implementation of the Secure Socket's Layer (SSL) protocol as a series of Unix programming libraries</para></listitem>
119 </varlistentry>
120
121
122 <varlistentry><term>
123 <indexterm id="appa-idx-990357-0"><primary>SSL (Secure Sockets Layer) protocol</primary><secondary>SS Proxy</secondary></indexterm>SSL Proxy</term>
124 <listitem><para>A freeware SSL application from Objective Development, which can be used to proxy a secure link on Unix or Windows NT platforms</para></listitem>
125 </varlistentry>
126 </variablelist>
127
128
129 <para>These two products assist with the server and client side of the encrypted SSL connection. The SSLeay libraries are compiled and installed directly on the Unix system. SSL Proxy, on the other hand, can be downloaded and compiled (or downloaded in binary format) and located on the client side. If you intend to have a Windows NT client or a Samba client on the other end of the SSL connection, you will not require a special setup.</para>
130
131
132 <para>SSL Proxy, however, does not work on Windows 95/98 machines. Therefore, if you want to have a secure connection between a Samba server and Windows 95/98 client, you will need to place either a Unix server or a Windows NT machine on the same subnet with the Windows 9<emphasis>x</emphasis> clients and route all network connections through the SSL-Proxy-enabled machine. See <link linkend="appa-89929">Figure 1.1</link>.</para>
133
134
135 <figure label="A.1" id="appa-89929">
136 <title>Two possible ways of proxying Windows 95/98 clients</title>
137
138 <graphic width="502" depth="317" fileref="figs/sam.aa01.gif"></graphic>
139 </figure>
140
141 <para>For the purposes of this chapter, we will create a simple SSL connection between the Samba server and a Windows NT client. This configuration can be used to set up more complex networks at the administrator's discretion.</para>
142 </sect1>
143
144
145
146
147
148
149
150
151
152 <sect1 role="" label="A.3" id="appa-SECT-3">
153 <title>Installing SSLeay</title>
154
155
156 <para>Samba uses the SSLeay package, written by Eric Young, to provide Secure Sockets Layer support on the server side. Because of U.S. export law, however, the SSLeay package cannot be shipped with Samba distributions that are based in the United States. For that reason, the Samba creators decided to leave it as a separate package entirely. You can download the SSLeay distribution from any of the following sites:</para>
157
158
159 <itemizedlist>
160
161 <listitem><para><systemitem role="ftpurl">ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL/</systemitem></para></listitem>
162
163 <listitem><para><systemitem role="ftpurl">ftp://ftp.uni-mainz.de/pub/internet/security/ssl</systemitem></para></listitem>
164
165 <listitem><para><systemitem role="ftpurl">ftp://ftp.cert.dfn.de/pub/tools/crypt/sslapps</systemitem></para></listitem>
166
167 <listitem><para><systemitem role="ftpurl">ftp://ftp.funet.fi/pub/crypt/mirrors/ftp.psy.uq.oz.au</systemitem></para></listitem>
168
169 <listitem><para><systemitem role="ftpurl">ftp://ftp.sunet.se/ftp/pub/security/tools/crypt/ssleay</systemitem></para></listitem>
170
171 </itemizedlist>
172
173 <para>The latest version as of this printing is 0.9.0b. Download it to the same server as the Samba distribution, then uncompress and untar it. You should be left with a directory entitled <filename>SSLeay-0.9.0b</filename>. After changing to that directory, you will need to configure and build the SSL encryption package in the same way that you did with Samba.</para>
174
175
176 <para>SSLeay uses a Perl-based <filename>configure</filename> script. This script modifies the Makefile that constructs the utilities and libraries of the SSLeay package. However, the default script is hardcoded to find Perl at <filename>/usr/local/bin/perl</filename>. You may need to change the <filename>configure</filename> script to point to the location of the Perl executable file on your Unix system. For example, you can type the following to locate the Perl executable:</para>
177
178
179 <programlisting># <userinput>which perl</userinput>
180 /usr/bin/perl</programlisting>
181
182
183 <para>Then modify the first line of the <filename>configure</filename> script to force it to use the correct Perl executable. For example, on our Red Hat Linux system:</para>
184
185
186 <programlisting>#!/usr/bin/perl
187 #
188 # see PROBLEMS for instructions on what sort of things to do
189 # when tracking a bug -tjh
190 ...</programlisting>
191
192
193 <para>After that, you need to run the <filename>configure</filename> script by specifying a target platform for the distribution. This target platform can be any of the following:</para>
194
195
196 <programlisting>BC-16              BC-32              FreeBSD            NetBSD-m86
197 NetBSD-sparc       NetBSD-x86         SINIX-N            VC-MSDOS
198 VC-NT              VC-W31-16          VC-W31-32          VC-WIN16
199 VC-WIN32           aix-cc             aix-gcc            alpha-cc
200 alpha-gcc          alpha400-cc        cc                 cray-t90-cc
201 debug              debug-irix-cc      debug-linux-elf    dgux-R3-gcc
202 dgux-R4-gcc        dgux-R4-x86-gcc    dist               gcc
203 hpux-cc            hpux-gcc           hpux-kr-cc         irix-cc
204 irix-gcc           linux-aout         linux-elf          ncr-scde
205 nextstep           purify             sco5-cc            solaris-sparc-cc
206 solaris-sparc-gcc  solaris-sparc-sc4  solaris-usparc-sc4 solaris-x86-gcc
207 sunos-cc           sunos-gcc          unixware-2.0       unixware</programlisting>
208
209
210 <para>For our system, we would enter the following:</para>
211
212
213 <programlisting># <userinput>./Configure linux-elf</userinput>
214 CC            =gcc
215 CFLAG         =-DL_ENDIAN -DTERMIO -DBN_ASM -O3 -fomit-frame-pointer
216 EX_LIBS       =
217 BN_MULW       =asm/bn86-elf.o
218 DES_ENC       =asm/dx86-elf.o asm/yx86-elf.o
219 BF_ENC        =asm/bx86-elf.o
220 CAST_ENC      =asm/cx86-elf.o
221 RC4_ENC       =asm/rx86-elf.o
222 RC5_ENC       =asm/r586-elf.o
223 MD5_OBJ_ASM   =asm/mx86-elf.o
224 SHA1_OBJ_ASM  =asm/sx86-elf.o
225 RMD160_OBJ_ASM=asm/rm86-elf.o
226 THIRTY_TWO_BIT mode
227 DES_PTR used
228 DES_RISC1 used
229 DES_UNROLL used
230 BN_LLONG mode
231 RC4_INDEX mode</programlisting>
232
233
234 <para>After the package has been configured, you can build it by typing <literal>make</literal>. If the build did not successfully complete, consult the documentation that comes with the distribution or the FAQ at <systemitem role="url">http://www.cryptsoft.com/ssleay/</systemitem> for more information on what may have happened. If the build did complete, type <literal>make</literal> <literal>install</literal> to install the libraries on the system. Note that the makefile installs the package in <filename>/usr/local/ssl</filename> by default. If you decide to install it in another directory, remember the directory when configuring Samba to use SSL.</para>
235
236
237 <sect2 role="" label="A.3.1" id="appa-SECT-3.1">
238 <title>Configuring SSLeay for Your System</title>
239
240
241 <para>The first thing you need to do is to set the <literal>PATH</literal> environment variable on your system to include the <filename>/bin</filename> directory of the SSL distribution. This can be done with the following statement:</para>
242
243
244 <programlisting>PATH=$PATH:/usr/local/ssl/bin</programlisting>
245
246
247 <para>That's the easy part. Following that, you will need to create a random series of characters that will be used to prime SSLeay's random number generator. The random number generator will be used to create key pairs for both the clients and the server. You can create this random series by filling a text file of a long series of random characters. For example, you can use your favorite editor to create a text file with random characters, or use this command and enter arbitrary characters at the standard input:</para>
248
249
250 <programlisting>cat &gt;/tmp/private.txt</programlisting>
251
252
253 <para>The Samba documentation recommends that you type characters for longer than a minute before interrupting the input stream by hitting Control-D. Try not to type only the characters that are under your fingers on the keyboard; throw in some symbols and numbers as well. Once you've completed the random file, you can prime the random number generator with the following command:</para>
254
255
256 <programlisting># ssleay genrsa -rand /tmp/private.txt &gt;/dev/null
257 2451 semi-random bytes loaded
258 Generating RSA private key, 512 bit long modulus
259 ..+++++
260 .................................+++++
261 e is 65537 (0x10001)</programlisting>
262
263
264 <para>You can safely ignore the output of this command. After it has completed, remove the series of characters used to create the key because this could be used to recreate any private keys that were generated from this random number generator:</para>
265
266
267 <programlisting>rm -f /tmp/private.txt</programlisting>
268
269
270 <para>The result of this command is the hidden file .<emphasis>rnd</emphasis>, which is stored in your home directory. SSLeay will use this file when creating key pairs in the future.</para>
271 </sect2>
272
273
274
275
276
277 <sect2 role="" label="A.3.2" id="appa-SECT-3.2">
278 <title>Configuring Samba to use SSL</title>
279
280
281 <para>
282 <indexterm id="appa-idx-990398-0"><primary>SSL (Secure Sockets Layer) protocol</primary><secondary>configuring Samba to use</secondary></indexterm>At this point, you can compile Samba to use SSL. Recall that in <link linkend="SAMBA-CH-2">Chapter 2</link>, we said you have to first run the configure script, which initializes the makefile, before you compile Samba. In order to use SSL with Samba, you will need to reconfigure the makefile:</para>
283
284
285 <programlisting>./configure --with-ssl</programlisting>
286
287
288 <para>After that, you can compile Samba with the following commands:</para>
289
290
291 <programlisting># <userinput>make clean</userinput>
292 # <userinput>make all</userinput></programlisting>
293
294
295 <para>If you encounter an error that says the <filename>smbd</filename> executable is missing the file <filename>ssl.h</filename>, you probably didn't install SSLeay in the default directory. Use the configure option <literal>--with-sslinc</literal> to point to the base directory of the SSL distribution&mdash;in this case, the directory that contains <emphasis>include/ssl.h</emphasis>.</para>
296
297
298 <para>On the other hand, if you have a clean compile, you're ready to move on to the next step: creating certificates.</para>
299 </sect2>
300
301
302
303
304
305 <sect2 role="" label="A.3.3" id="appa-62097">
306 <title>Becoming a Certificate Authority</title>
307
308
309 <para><firstterm></firstterm>
310 <indexterm id="appa-idx-990405-0" class="startofrange"><primary>certificate authority</primary></indexterm>The SSL protocol requires the use of X.509 certificates in the protocol handshake to ensure that either one or both parties involved in the communication are indeed who they say they are. Certificates in real life, such as those use for SSL connections on public web sites, can cost in the arena of $300 a year. This is because the certificate must have a digital signature placed on it by a <firstterm>certificate authority</firstterm>. A certificate authority is an entity that vouches for the authenticity of a digital certificate by signing it with its own private key. This way, anyone who wishes to check the authenticity of the certificate can simply use the certificate authority's public key to check the signature.</para>
311
312
313 <para>You are allowed to use a public certificate authority with SSLeay. However, you don't have to. Instead, SSLeay will allow you to declare yourself a trusted certificate authority&mdash;specifying which clients you choose to trust and which clients you do not. In order to do this, you will need to perform several tasks with the SSLeay distribution.</para>
314
315
316 <para>The first thing you need to do is specify a secure location where the certificates of the clients and potentially the server will be stored. We have chosen <filename>/etc/certificates</filename> as our default. Execute the following commands as <literal>root</literal>:</para>
317
318
319 <programlisting># <userinput>cd /etc</userinput>
320 # <userinput>mkdir certificates</userinput>
321 # <userinput>chmod 700 certificates</userinput></programlisting>
322
323
324 <para>Note that we shut out all access to users other than <literal>root</literal> for this directory. This is very important.</para>
325
326
327 <para>Next, you need to set up the SSLeay scripts and configuration files to use the certificates stored in this directory. In order to do this, first modify the <filename>CA.sh</filename> script located at <emphasis>/usr/local/ssl/bin/CA.sh</emphasis> to specify the location of the directory you just created. Find the line that contains the following entry:</para>
328
329
330 <programlisting>CATOP=./demoCA</programlisting>
331
332
333 <para>Then change it to:</para>
334
335
336 <programlisting>CATOP=/etc/certificates</programlisting>
337
338
339 <para>Next, you need to modify the <emphasis>/usr/local/ssl/lib/ssleay.cnf</emphasis> file to specify the same directory. Find the entry:</para>
340
341
342 <programlisting>[ CA_default ]
343 dir     = ./demoCA             # Where everything is kept</programlisting>
344
345
346 <para>Then change it to:</para>
347
348
349 <programlisting>[ CA_default ]
350 dir     =  /etc/certificates   # Where everything is kept</programlisting>
351
352
353 <para>Next, run the certificate authority setup script, <filename>CA.sh</filename>, in order to create the certificates. Be sure to do this as the same user that you used to prime the random number generator above:</para>
354
355
356 <programlisting>/usr/local/ssl/bin/CA.sh -newca
357 mkdir: cannot make directory '/etc/certificates': File exists
358 CA certificate filename (or enter to create)</programlisting>
359
360
361 <para>Press the Enter key to create a certificate for the CA. You should then see:</para>
362
363
364 <programlisting>Making CA certificate ...
365 Using configuration from /usr/local/ssl/lib/ssleay.cnf
366 Generating a 1024 bit RSA private key
367 .............................+++++
368 .....................+++++
369 writing new private key to /etc/certificates/private/cakey.pem
370 Enter PEM pass phrase:</programlisting>
371
372
373 <para>Enter a new pass phrase for your certificate. You will need to enter it twice correctly before SSLeay will accept it:</para>
374
375
376 <programlisting>Enter PEM pass phrase:
377 Verifying password - Enter PEM pass phrase:</programlisting>
378
379
380 <para>Be sure to remember this pass phrase. You will need it to sign the client certificates in the future. Once SSLeay has accepted the pass phrase, it will continue on with a series of questions for each of the fields in the X509 certificate:</para>
381
382
383 <programlisting>You are about to be asked to enter information that will be
384 incorporated into your certificate request.
385 What you are about to enter is what is called a Distinguished
386 Name or a DN.
387 There are quite a few fields but you can leave some blank
388 For some fields there will be a default value,
389 If you enter '.', the field will be left blank.</programlisting>
390
391
392 <para>Fill out the remainder of the fields with information about your organization. For example, our certificate looks like this:</para>
393
394
395 <programlisting>Country Name (2 letter code) [AU]:<userinput>US</userinput>
396 State or Province Name (full name) [Some-State]:<userinput>California</userinput>
397 Locality Name (eg, city) []:<userinput>Sebastopol</userinput>
398 Organization Name (eg, company) []:<userinput>O'Reilly</userinput>
399 Organizational Unit Name (eg, section) []:<userinput>Books</userinput>
400 Common Name (eg, YOUR name) []:<userinput>John Doe</userinput>
401 Email Address []:<userinput>doe@ora.com</userinput></programlisting>
402
403
404 <para>After that, SSLeay will be configured as a certificate authority and can be used to sign certificates for client machines that will be connecting to the Samba server.</para>
405 </sect2>
406
407
408
409
410
411 <sect2 role="" label="A.3.4" id="appa-SECT-3.4">
412 <title>Creating Certificates for Clients</title>
413
414
415 <para>It's simple to create a certificate for a client machine. First, you need to generate a public/private key pair for each entity, create a certificate request file, and then use <emphasis>SSLeay</emphasis> to sign the file as a trusted authority.</para>
416
417
418 <para>For our example client <literal>phoenix</literal>, this boils down to three SSLeay commands. The first generates a key pair for the client and places it in the file <filename>phoenix.key</filename>. The private key will be encrypted, in this case using triple DES. Enter a pass phrase when requested below&mdash;you'll need it for the next step:</para>
419
420
421 <programlisting># ssleay genrsa -des3 1024 &gt;phoenix.key
422 1112 semi-random bytes loaded
423 Generating RSA private key, 1024 bit long modulus
424 ........................................+++++
425 .............+++++
426 e is 65537 (0x10001)
427 Enter PEM pass phrase:
428 Verifying password - Enter PEM pass phrase:</programlisting>
429
430
431 <para>After that command has completed, type in the following command:</para>
432
433
434 <programlisting># <userinput>ssleay req -new -key phoenix.key -out phoenix-csr</userinput>
435 Enter PEM pass phrase:</programlisting>
436
437
438 <para>Enter the pass phrase for the client certificate you just created (not the certificate authority). At this point, you will need to answer the questionnaire again, this time for the client machine. In addition, you must type in a challenge password and an optional company name&mdash;those do not matter here. When the command completes, you will have a certificate request in the file <emphasis>phoenix-csr.</emphasis></para>
439
440
441 <para>Then, you must sign the certificate request as the trusted certificate authority. Type in the following command:</para>
442
443
444 <programlisting># <userinput>ssleay ca -days 1000 -inflies phoenix-csr &gt;phoenix.pem</userinput></programlisting>
445
446
447 <para>This command will prompt you to enter the PEM pass phrase of the <emphasis>certificate authority</emphasis>. Be sure that you do not enter the PEM pass phrase of the client certificate that you just created. After entering the correct pass phrase, you should see the following:</para>
448
449
450 <programlisting>Check that the request matches the signature
451 Signature ok
452 The Subjects Distinguished Name is as follows:
453 ...</programlisting>
454
455
456 <para>This will be followed by the information that you just entered for the client certificate. If there is an error in the fields, the program will notify you. On the other hand, if everything is fine, SSLeay will confirm that it should sign the certificate and commit it to the database. This adds a record of the certificate to the <filename>/etc/certificates/newcerts</filename> directory.</para>
457
458
459 <para>The operative files at the end of this exercise are the <emphasis>phoenix.key</emphasis> and <emphasis>phoenix.pem</emphasis> files, which reside in the current directory. These files will be passed off to the client with whom the SSL-enabled Samba server will interact, and will be used by SSL Proxy.<firstterm></firstterm>
460 <indexterm id="appa-idx-990421-0" class="endofrange" startref="appa-idx-990405-0"/></para>
461 </sect2>
462
463
464
465
466
467 <sect2 role="" label="A.3.5" id="appa-SECT-3.5">
468 <title>Configuring the Samba Server</title>
469
470
471 <para>The next step is to modify the Samba configuration file to include the following setup options. These options assume that you created the certificates directory for the certificate authority at <filename>/etc/certificates </filename>:</para>
472
473
474 <programlisting>[global]
475         ssl = yes
476         ssl server cert = /etc/certificates/cacert.pem
477         ssl server key = /etc/certificates/private/cakey.pem
478         ssl CA certDir = /etc/certificates</programlisting>
479
480
481 <para>At this point, you will need to kill the Samba daemons and restart them manually:</para>
482
483
484 <programlisting># <userinput>nmbd -D</userinput>
485 # <userinput>smbd -D</userinput>
486 Enter PEM pass phrase:</programlisting>
487
488
489 <para>You will need to enter the PEM pass phrase of the certificate authority to start up the Samba daemons. Note that this may present a problem in terms of starting the program using ordinary means. However, you can get around this using advanced scripting languages, such as Expect or Python.</para>
490 </sect2>
491
492
493
494
495
496 <sect2 role="" label="A.3.6" id="appa-SECT-3.6">
497 <title>Testing with smbclient</title>
498
499
500 <para>A good way to test whether Samba is working properly is to use the <emphasis>smbclient</emphasis> program. On the Samba server, enter the following command, substituting the appropriate share and user for a connection:</para>
501
502
503 <programlisting># <userinput>smbclient //hydra/data -U tom</userinput></programlisting>
504
505
506 <para>You should see several debugging statements followed by a line indicating the negotiated cipher, such as:</para>
507
508
509 <programlisting>SSL: negotiated cipher: DES-CBC3-SHA</programlisting>
510
511
512 <para>After that, you can enter your password and connect to the share normally. If this works, you can be sure that Samba is correctly supporting SSL connections. Now, on to the client setup. <indexterm id="appa-idx-990386-0" class="endofrange" startref="appa-idx-990613-0"/></para>
513 </sect2>
514 </sect1>
515
516
517
518
519
520
521
522
523
524 <sect1 role="" label="A.4" id="appa-SECT-4">
525 <title>Setting Up SSL Proxy</title>
526
527
528 <para>The <indexterm id="appa-idx-990393-0"><primary>SSL (Secure Sockets Layer) protocol</primary><secondary>SS Proxy</secondary><tertiary>setting up</tertiary></indexterm>SSL Proxy program is available as a standalone binary or as source code. You can download it from <systemitem role="url">http://obdev.at/Products/sslproxy.html</systemitem>.</para>
529
530
531 <para>Once it is downloaded, you can configure and compile it like Samba. We will configure it on a Windows NT system. However, setting it up for a Unix system involves a nearly identical series of steps. Be sure that you are the superuser (administrator) for the next series of steps.</para>
532
533
534 <para>If you downloaded the binary for Windows NT, you should have the following files in a directory:</para>
535
536
537 <itemizedlist>
538
539 <listitem><para><filename>cygwinb19.dll</filename></para></listitem>
540
541 <listitem><para><filename>README.TXT</filename></para></listitem>
542
543 <listitem><para><filename>sslproxy.exe</filename></para></listitem>
544
545 <listitem><para><filename>dummyCert.pem</filename></para></listitem>
546
547 </itemizedlist>
548
549 <para>The only one that you will be interested in is the SSL Proxy executable. Copy over the <emphasis>phoenix.pem</emphasis> and <emphasis>phoenix.key</emphasis> files that you generated earlier for the client to the same directory as the SSL proxy executable. Make sure that the directory is secure from the prying eyes of other users.</para>
550
551
552 <para>The next step is to ensure that the Windows NT machine can resolve the NetBIOS name of the Samba server. This means that you should either have a WINS server up and running (the Samba server can perform this task with the <literal>wins</literal> <literal>support</literal> <literal>=</literal> <literal>yes</literal> option) or have it listed in the appropriate <emphasis>hosts</emphasis> file of the system. See <link linkend="SAMBA-CH-7">Chapter 7</link>, for more information on WINS server.<footnote label="1" id="appa-pgfId-986801">
553
554
555 <para>If you are running SSL Proxy on a Unix server, you should ensure that the DNS name of the Samba server can be resolved.</para>
556
557
558 </footnote></para>
559
560
561 <para>Finally, start up SSL Proxy with the following command. Here, we assume that <literal>hydra</literal> is the name of the Samba server:</para>
562
563
564 <programlisting>#<userinput> C:\SSLProxy&gt;sslproxy -l 139 -R hydra -r 139 -n -c phoenix.pem -k phoenix.key</userinput></programlisting>
565
566
567 <para>This tells SSL Proxy to listen for connections to port 139 and relay those requests to port 139 on the NetBIOS machine <literal>hydra</literal>. It also instructs SSL Proxy to use the <filename>phoenix.pem</filename> and <filename>phoenix.key</filename> files to generate the certificate and keys necessary to initiate the SSL connection. SSL Proxy responds with:</para>
568
569
570 <programlisting>Enter PEM pass phrase:</programlisting>
571
572
573 <para>Enter the PEM pass phrase of the client keypair that you generated, <emphasis>not</emphasis> the certificate authority. You should then see the following output:</para>
574
575
576 <programlisting>SSL: No verify locations, trying default
577 proxy ready, listening for connections</programlisting>
578
579
580 <para>That should take care of the client. You can place this command in a startup sequence on either Unix or Windows NT if you want this functionality available at all times. Be sure to set any clients you have connecting to the NT server (including the NT server itself) to point to this server instead of the Samba server.</para>
581
582
583 <para>After you've completed setting this up, try to connect using clients that proxy through the NT server. You should find that it works almost transparently.</para>
584 </sect1>
585
586
587
588
589
590
591
592
593
594 <sect1 role="" label="A.5" id="appa-SECT-5">
595 <title>SSL Configuration Options</title>
596
597
598 <para>
599 <indexterm id="appa-idx-990427-0" class="startofrange"><primary>SSL (Secure Sockets Layer) protocol</primary><secondary>configuration options for</secondary></indexterm><link linkend="appa-61150">Table 1.1</link> summarizes the configuration options introduced in the previous section for using SSL. Note that all of these options are global in scope; in other words, they must appear in the <literal>[global]</literal> section of the configuration file.</para>
600
601
602 <table label="A.1" id="appa-61150">
603 <title>SSL Configuration Options </title>
604
605 <tgroup cols="5">
606 <colspec colnum="1" colname="col1"/>
607 <colspec colnum="2" colname="col2"/>
608 <colspec colnum="3" colname="col3"/>
609 <colspec colnum="4" colname="col4"/>
610 <colspec colnum="5" colname="col5"/>
611 <thead>
612 <row>
613
614 <entry colname="col1"><para>Option</para></entry>
615
616 <entry colname="col2"><para>Parameters</para></entry>
617
618 <entry colname="col3"><para>Function</para></entry>
619
620 <entry colname="col4"><para>Default</para></entry>
621
622 <entry colname="col5"><para>Scope</para></entry>
623
624 </row>
625
626 </thead>
627
628 <tbody>
629 <row>
630
631 <entry colname="col1"><para><literal>ssl</literal></para></entry>
632
633 <entry colname="col2"><para>boolean</para></entry>
634
635 <entry colname="col3"><para>Indicates whether SSL mode is enabled with Samba.</para></entry>
636
637 <entry colname="col4"><para><literal>no</literal></para></entry>
638
639 <entry colname="col5"><para>Global</para></entry>
640
641 </row>
642
643 <row>
644
645 <entry colname="col1"><para><literal>ssl hosts</literal></para></entry>
646
647 <entry colname="col2"><para>string (list of addresses)</para></entry>
648
649 <entry colname="col3"><para>Specifies a list of hosts that must always connect using SSL.</para></entry>
650
651 <entry colname="col4"><para>None</para></entry>
652
653 <entry colname="col5"><para>Global</para></entry>
654
655 </row>
656
657 <row>
658
659 <entry colname="col1"><para><literal>ssl hosts resign</literal></para></entry>
660
661 <entry colname="col2"><para>string (list of addresses)</para></entry>
662
663 <entry colname="col3"><para>Specifies a list of hosts that never connect using SS.</para></entry>
664
665 <entry colname="col4"><para>None</para></entry>
666
667 <entry colname="col5"><para>Global</para></entry>
668
669 </row>
670
671 <row>
672
673 <entry colname="col1"><para><literal>ssl CA certDir</literal></para></entry>
674
675 <entry colname="col2"><para>string (fully-qualified pathname)</para></entry>
676
677 <entry colname="col3"><para>Specifies the directory where the certificates are stored.</para></entry>
678
679 <entry colname="col4"><para>None</para></entry>
680
681 <entry colname="col5"><para>Global</para></entry>
682
683 </row>
684
685 <row>
686
687 <entry colname="col1"><para><literal>ssl CA certFile</literal></para></entry>
688
689 <entry colname="col2"><para>string (fully-qualified pathname)</para></entry>
690
691 <entry colname="col3"><para>Specifies a file that contains all of the certificates for Samba.</para></entry>
692
693 <entry colname="col4"><para>None</para></entry>
694
695 <entry colname="col5"><para>Global</para></entry>
696
697 </row>
698
699 <row>
700
701 <entry colname="col1"><para><literal>ssl server cert</literal></para></entry>
702
703 <entry colname="col2"><para>string (fully-qualified pathname)</para></entry>
704
705 <entry colname="col3"><para>Specifies the location of the server's certificate.</para></entry>
706
707 <entry colname="col4"><para>None</para></entry>
708
709 <entry colname="col5"><para>Global</para></entry>
710
711 </row>
712
713 <row>
714
715 <entry colname="col1"><para><literal>ssl server key</literal></para></entry>
716
717 <entry colname="col2"><para>string (fully-qualified pathname)</para></entry>
718
719 <entry colname="col3"><para>Specifies the location of the server's private key.</para></entry>
720
721 <entry colname="col4"><para>None</para></entry>
722
723 <entry colname="col5"><para>Global</para></entry>
724
725 </row>
726
727 <row>
728
729 <entry colname="col1"><para><literal>ssl client cert</literal></para></entry>
730
731 <entry colname="col2"><para>string (fully-qualified pathname)</para></entry>
732
733 <entry colname="col3"><para>Specifies the location of the client's certificate.</para></entry>
734
735 <entry colname="col4"><para>None</para></entry>
736
737 <entry colname="col5"><para>Global</para></entry>
738
739 </row>
740
741 <row>
742
743 <entry colname="col1"><para><literal>ssl client key</literal></para></entry>
744
745 <entry colname="col2"><para>string (fully-qualified pathname)</para></entry>
746
747 <entry colname="col3"><para>Specifies the location of the client's private key.</para></entry>
748
749 <entry colname="col4"><para>None</para></entry>
750
751 <entry colname="col5"><para>Global</para></entry>
752
753 </row>
754
755 <row>
756
757 <entry colname="col1"><para><literal>ssl require clientcert</literal></para></entry>
758
759 <entry colname="col2"><para>boolean</para></entry>
760
761 <entry colname="col3"><para>Indicates whether Samba should require each client to have a certificate.</para></entry>
762
763 <entry colname="col4"><para><literal>no</literal></para></entry>
764
765 <entry colname="col5"><para>Global</para></entry>
766
767 </row>
768
769 <row>
770
771 <entry colname="col1"><para><literal>ssl require servercert</literal></para></entry>
772
773 <entry colname="col2"><para>boolean</para></entry>
774
775 <entry colname="col3"><para>Indicates whether the server itself should have a certificate.</para></entry>
776
777 <entry colname="col4"><para><literal>no</literal></para></entry>
778
779 <entry colname="col5"><para>Global</para></entry>
780
781 </row>
782
783 <row>
784
785 <entry colname="col1"><para><literal>ssl ciphers</literal></para></entry>
786
787 <entry colname="col2"><para>String</para></entry>
788
789 <entry colname="col3"><para>Specifies the cipher suite to use during protocol negotiation.</para></entry>
790
791 <entry colname="col4"><para>None</para></entry>
792
793 <entry colname="col5"><para>Global</para></entry>
794
795 </row>
796
797 <row>
798
799 <entry colname="col1"><para><literal>ssl version</literal></para></entry>
800
801 <entry colname="col2"><para><literal>ssl2or3</literal>, <literal>ssl3</literal>, or <literal>tls1</literal></para></entry>
802
803 <entry colname="col3"><para>Specifies the version of SSL to use.</para></entry>
804
805 <entry colname="col4"><para><literal>ssl2or3</literal></para></entry>
806
807 <entry colname="col5"><para>Global</para></entry>
808
809 </row>
810
811 <row>
812
813 <entry colname="col1"><para><literal>ssl compatibility</literal></para></entry>
814
815 <entry colname="col2"><para>boolean</para></entry>
816
817 <entry colname="col3"><para>Indicates whether compatibility with other implementations of SSL should be activated.</para></entry>
818
819 <entry colname="col4"><para><literal>no</literal></para></entry>
820
821 <entry colname="col5"><para>Global</para></entry>
822
823 </row>
824
825 </tbody>
826 </tgroup>
827 </table>
828
829
830 <sect2 role="" label="A.5.1" id="appa-SECT-5.0.1">
831 <indexterm id="appa-idx-990620-0"><primary>ssl option</primary></indexterm>
832 <title>
833 ssl</title>
834
835
836 <para>This global option configures Samba to use SSL for communication between itself and clients. The default value of this option is <literal>no</literal>. You can reset it as follows:</para>
837
838
839 <programlisting>[global]
840         ssl = yes</programlisting>
841
842
843 <para>Note that in order to use this option, you must have a proxy for Windows 95/98 clients, such as in the model presented earlier in this chapter.</para>
844 </sect2>
845
846
847
848
849
850 <sect2 role="" label="A.5.2" id="appa-SECT-5.0.2">
851 <indexterm id="appa-idx-990625-0"><primary>ssl hosts option</primary></indexterm>
852 <title>
853 ssl hosts</title>
854
855
856 <para>This option specifies the hosts that will be forced into using SSL. The syntax for specifying hosts and addresses is the same as the <literal>hosts</literal> <literal>allow</literal> and the <literal>hosts</literal> <literal>deny</literal> configuration options. For example:</para>
857
858
859 <programlisting>[global]
860         ssl = yes
861         ssl hosts = 192.168.220.</programlisting>
862
863
864 <para>This example specifies that all hosts that fall into the 192.168.220 subnet must use SSL connections with the client. This type of structure is useful if you know that various connections will be made by a subnet that lies across an untrusted network, such as the Internet. If neither this option nor the <literal>ssl</literal> <literal>hosts</literal> <literal>resign</literal> option has been specified, and <literal>ssl</literal> is set to <literal>yes</literal>, Samba will allow only SSL connections from all clients.</para>
865 </sect2>
866
867
868
869
870
871 <sect2 role="" label="A.5.3" id="appa-SECT-5.0.3">
872 <indexterm id="appa-idx-990628-0"><primary>ssl hosts resign option</primary></indexterm>
873 <title>
874 ssl hosts resign</title>
875
876
877 <para>This option specifies the hosts that will <emphasis>not</emphasis> be forced into SSL mode. The syntax for specifying hosts and addresses is the same as the <literal>hosts</literal> <literal>allow</literal> and the <literal>hosts</literal> <literal>deny</literal> configuration options. For example:</para>
878
879
880 <programlisting>[global]
881         ssl = yes
882         ssl hosts resign = 160.2.310. 160.2.320.</programlisting>
883
884
885 <para>This example specifies that all hosts that fall into the 160.2.310 or 160.2.320 subnets will not use SSL connections with the client. If neither this option nor the <literal>ssl</literal> <literal>hosts</literal> option has been specified, and <literal>ssl</literal> is set to <literal>yes</literal>, Samba will allow only SSL connections from all clients.</para>
886 </sect2>
887
888
889
890
891
892 <sect2 role="" label="A.5.4" id="appa-SECT-5.0.4">
893 <indexterm id="appa-idx-990631-0"><primary>ssl CA certDir option</primary></indexterm>
894 <title>
895 ssl CA certDir</title>
896
897
898 <para>This option specifies the directory containing the certificate authority's certificates that Samba will use to authenticate clients. There must be one file in this directory for each certificate authority, named as specified earlier in this chapter. Any other files in this directory are ignored. For example:</para>
899
900
901 <programlisting>[global]
902         ssl = yes
903         ssl hosts = 192.168.220.
904         ssl CA certDir = /usr/local/samba/cert</programlisting>
905
906
907 <para>There is no default for this option. You can alternatively use the option <literal>ssl</literal> <literal>CA</literal> <literal>certFile</literal> if you wish to place all the certificate authority information in the same file.</para>
908 </sect2>
909
910
911
912
913
914 <sect2 role="" label="A.5.5" id="appa-SECT-5.0.5">
915 <indexterm id="appa-idx-990634-0"><primary>ssl CA certFile option</primary></indexterm>
916 <title>
917 ssl CA certFile</title>
918
919
920 <para>This option specifies a file that contains the certificate authority's certificates that Samba will use to authenticate clients. This option differs from <literal>ssl</literal> <literal>CA</literal> <literal>certDir</literal> in that there is only one file used for all the certificate authorities. An example of its usage follows:</para>
921
922
923 <programlisting>[global]
924         ssl = yes
925         ssl hosts = 192.168.220.
926         ssl CA certFile = /usr/local/samba/cert/certFile</programlisting>
927
928
929 <para>There is no default for this option. You can also use the option <literal>ssl</literal> <literal>CA</literal> <literal>certDir</literal> if you wish to have a separate file for each certificate authority that Samba trusts.</para>
930 </sect2>
931
932
933
934
935
936 <sect2 role="" label="A.5.6" id="appa-SECT-5.0.6">
937 <indexterm id="appa-idx-990637-0"><primary>ssl server cert option</primary></indexterm>
938 <title>
939 ssl server cert</title>
940
941
942 <para>This option specifies the location of the server's certificate. This option is mandatory; the server must have a certificate in order to use SSL. For example:</para>
943
944
945 <programlisting>[global]
946         ssl = yes
947         ssl hosts = 192.168.220.
948         ssl CA certFile = /usr/local/samba/cert/certFile
949         ssl server cert = /usr/local/samba/private/server.pem</programlisting>
950
951
952 <para>There is no default for this option. Note that the certificate may contain the private key for the server.</para>
953 </sect2>
954
955
956
957
958
959 <sect2 role="" label="A.5.7" id="appa-SECT-5.0.7">
960 <indexterm id="appa-idx-990640-0"><primary>ssl server key option</primary></indexterm>
961 <title>
962 ssl server key</title>
963
964
965 <para>This option specifies the location of the server's private key. You should ensure that the location of the file cannot be accessed by anyone other than <literal>root</literal>. For example:</para>
966
967
968 <programlisting>[global]
969         ssl = yes
970         ssl hosts = 192.168.220.
971         ssl CA certFile = /usr/local/samba/cert/certFile
972         ssl server key = /usr/local/samba/private/samba.pem</programlisting>
973
974
975 <para>There is no default for this option. Note that the private key may be contained in the certificate for the server.</para>
976 </sect2>
977
978
979
980
981
982 <sect2 role="" label="A.5.8" id="appa-SECT-5.0.8">
983 <indexterm id="appa-idx-990643-0"><primary>ssl client cert option</primary></indexterm>
984 <title>
985 ssl client cert</title>
986
987
988 <para>This option specifies the location of the client's certificate. The certificate may be requested by the Samba server with the <literal>ssl</literal> <literal>require</literal> <literal>clientcert</literal> option; the certificate is also used by <filename>smbclient</filename>. For example:</para>
989
990
991 <programlisting>[global]
992     ssl = yes
993     ssl hosts = 192.168.220.
994     ssl CA certFile = /usr/local/samba/cert/certFile
995     ssl server cert = /usr/local/ssl/private/server.pem
996     ssl client cert= /usr/local/ssl/private/clientcert.pem</programlisting>
997
998
999 <para>There is no default for this option.</para>
1000 </sect2>
1001
1002
1003
1004
1005
1006 <sect2 role="" label="A.5.9" id="appa-SECT-5.0.9">
1007 <indexterm id="appa-idx-990646-0"><primary>ssl client key option</primary></indexterm>
1008 <title>
1009 ssl client key</title>
1010
1011
1012 <para>This option specifies the location of the client's private key. You should ensure that the location of the file cannot be accessed by anyone other than <literal>root</literal>. For example:</para>
1013
1014
1015 <programlisting>[global]
1016         ssl = yes
1017         ssl hosts = 192.168.220.
1018         ssl CA certDir = /usr/local/samba/cert/
1019         ssl server key = /usr/local/ssl/private/samba.pem
1020         ssl client key = /usr/local/ssl/private/clients.pem</programlisting>
1021
1022
1023 <para>There is no default for this option. This option is only needed if the client has a certificate.</para>
1024 </sect2>
1025
1026
1027
1028
1029
1030 <sect2 role="" label="A.5.10" id="appa-SECT-5.0.10">
1031 <indexterm id="appa-idx-990649-0"><primary>ssl require clientcert option</primary></indexterm>
1032 <title>
1033 ssl require clientcert</title>
1034
1035
1036 <para>This option specifies whether the client is required to have a certificate. The certificates listed with either the <literal>ssl</literal> <literal>CA</literal> <literal>certDir</literal> or the <literal>ssl</literal> <literal>CA</literal> <literal>certFile</literal> will be searched to confirm that the client has a valid certificate and is authorized to connect to the Samba server. The value of this option is a simple boolean. For example:</para>
1037
1038
1039 <programlisting>[global]
1040         ssl = yes
1041         ssl hosts = 192.168.220.
1042         ssl CA certFile = /usr/local/samba/cert/certFile
1043         ssl require clientcert = yes</programlisting>
1044
1045
1046 <para>We recommend that you require certificates from all clients that could be connecting to the Samba server. The default value for this option is <literal>no</literal>.</para>
1047 </sect2>
1048
1049
1050
1051
1052
1053 <sect2 role="" label="A.5.11" id="appa-SECT-5.0.11">
1054 <indexterm id="appa-idx-990652-0"><primary>ssl require servercert option</primary></indexterm>
1055 <title>
1056 ssl require servercert</title>
1057
1058
1059 <para>This option specifies whether the server is required to have a certificate. Again, this will be used by the <filename>smbclient</filename> program. The value of this option is a simple boolean. For example:</para>
1060
1061
1062 <programlisting>[global]
1063         ssl = yes
1064         ssl hosts = 192.168.220.
1065         ssl CA certFile = /usr/local/samba/cert/certFile
1066         ssl require clientcert = yes
1067         ssl require servercert = yes</programlisting>
1068
1069
1070 <para>Although we recommend that you require certificates from all clients that could be connecting to the Samba server, a server certificate is not required. It is, however,  recommended. The default value for this option is <literal>no</literal>.</para>
1071 </sect2>
1072
1073
1074
1075
1076
1077 <sect2 role="" label="A.5.12" id="appa-SECT-5.0.12">
1078 <indexterm id="appa-idx-990655-0"><primary>ssl ciphers option</primary></indexterm>
1079 <title>
1080 ssl ciphers</title>
1081
1082
1083 <para>This option sets the ciphers on which SSL will decide during the negotiation phase of the SSL connection. Samba can use any of the following ciphers:</para>
1084
1085
1086 <programlisting>DEFAULT
1087 DES-CFB-M1
1088 NULL-MD5
1089 RC4-MD5
1090 EXP-RC4-MD5
1091 RC2-CBC-MD5
1092 EXP-RC2-CBC-MD5
1093 IDEA-CBC-MD5
1094 DES-CBC-MD5
1095 DES-CBC-SHA
1096 DES-CBC3-MD5
1097 DES-CBC3-SHA
1098 RC4-64-MD5
1099 NULL</programlisting>
1100
1101
1102 <para>It is best not to set this option unless you are familiar with the SSL protocol and want to mandate a specific cipher suite.</para>
1103 </sect2>
1104
1105
1106
1107
1108
1109 <sect2 role="" label="A.5.13" id="appa-SECT-5.0.13">
1110 <indexterm id="appa-idx-990658-0"><primary>ssl version option</primary></indexterm>
1111 <title>
1112 ssl version</title>
1113
1114
1115 <para>This global option specifies the version of SSL that Samba will use when handling encrypted connections. The default value is <literal>ssl2or3</literal>, which specifies that either version 2 or 3 of the SSL protocol can be used, depending on which version is negotiated in the handshake between the server and the client. However, if you want Samba to use only a specific version of the protocol, you can specify the following:</para>
1116
1117
1118 <programlisting>[global]
1119         ssl version = ssl3</programlisting>
1120
1121
1122 <para>Again, it is best not to set this option unless you are familiar with the SSL protocol and want to mandate a specific version.</para>
1123 </sect2>
1124
1125
1126
1127
1128
1129 <sect2 role="" label="A.5.14" id="appa-SECT-5.0.14">
1130 <indexterm id="appa-idx-990661-0"><primary>ssl compatibility option</primary></indexterm>
1131 <title>
1132 ssl compatibility</title>
1133
1134
1135 <para>This global option specifies whether Samba should be configured to use other versions of SSL. However, because no other versions exist at this writing, the issue is  moot and the variable should always be left at the<indexterm id="appa-idx-990431-0" class="endofrange" startref="appa-idx-990427-0"/> default.<indexterm id="appa-idx-990339-0" class="endofrange" startref="appa-idx-990325-0"/>
1136 <indexterm id="appa-idx-990339-1" class="endofrange" startref="appa-idx-990325-1"/></para>
1137 </sect2>
1138 </sect1>
1139
1140
1141
1142
1143
1144
1145
1146
1147 </appendix>