path: root/docs-xml/using_samba/appa.xml

<appendix label="A" id="SAMBA-AP-A">
<title>Configuring Samba with SSL</title>




<para>
<indexterm id="appa-idx-990325-0" class="startofrange"><primary>configuring Samba</primary><secondary sortas="SSL">with SSL</secondary></indexterm>
<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>


<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>


<tip role="ora">
<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>

</tip>











<sect1 role="" label="A.1" id="appa-SECT-1">
<title>About Certificates</title>


<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>


<sect2 role="" label="A.1.1" id="appa-SECT-1.1">
<title>What is a Certificate?</title>


<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>
</sect2>





<sect2 role="" label="A.1.2" id="appa-SECT-1.2">
<title>What is an X.509 certificate, technically?</title>


<para>Technically, the certificate is a block of data signed by the certificate issuer (the CA). The relevant fields are:</para>


<itemizedlist>

<listitem><para>
Unique identifier (name) of the certificate issuer</para></listitem>

<listitem><para>Time range during which the certificate is valid</para></listitem>

<listitem><para>Unique identifier (name) of the certified object</para></listitem>

<listitem><para>Public key of the certified object</para></listitem>

<listitem><para>The issuer's signature over all the above</para></listitem>

</itemizedlist>

<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>
</sect2>





<sect2 role="" label="A.1.3" id="appa-SECT-1.3">
<title>What are the implications of this certificate structure?</title>


<para>Four implications follow:</para>


<itemizedlist>

<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>

<listitem><para>To verify certificates, you need the certificates of all CAs you trust.</para></listitem>

<listitem><para>The simplest form of a dummy-certificate is one that is signed by the subject.</para></listitem>

<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>

</itemizedlist>
</sect2>
</sect1>









<sect1 role="" label="A.2" id="appa-SECT-2">
<title>Requirements</title>


<para>
<indexterm id="appa-idx-990348-0"><primary>configuring Samba</primary><secondary sortas="SSL">with SSL</secondary><tertiary>requirements for</tertiary></indexterm>
<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>


<variablelist>
<varlistentry><term>
<indexterm id="appa-idx-990613-0" class="startofrange"><primary>SSL (Secure Sockets Layer) protocol</primary><secondary>SSLeay</secondary></indexterm>SSLeay</term>
<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>
</varlistentry>


<varlistentry><term>
<indexterm id="appa-idx-990357-0"><primary>SSL (Secure Sockets Layer) protocol</primary><secondary>SS Proxy</secondary></indexterm>SSL Proxy</term>
<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>
</varlistentry>
</variablelist>


<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>


<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>


<figure label="A.1" id="appa-89929">
<title>Two possible ways of proxying Windows 95/98 clients</title>

<graphic width="502" depth="317" fileref="figs/sam.aa01.gif"></graphic>
</figure>

<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>
</sect1>









<sect1 role="" label="A.3" id="appa-SECT-3">
<title>Installing SSLeay</title>


<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>


<itemizedlist>

<listitem><para><systemitem role="ftpurl">ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL/</systemitem></para></listitem>

<listitem><para><systemitem role="ftpurl">ftp://ftp.uni-mainz.de/pub/internet/security/ssl</systemitem></para></listitem>

<listitem><para><systemitem role="ftpurl">ftp://ftp.cert.dfn.de/pub/tools/crypt/sslapps</systemitem></para></listitem>

<listitem><para><systemitem role="ftpurl">ftp://ftp.funet.fi/pub/crypt/mirrors/ftp.psy.uq.oz.au</systemitem></para></listitem>

<listitem><para><systemitem role="ftpurl">ftp://ftp.sunet.se/ftp/pub/security/tools/crypt/ssleay</systemitem></para></listitem>

</itemizedlist>

<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>


<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>


<programlisting># <userinput>which perl</userinput>
/usr/bin/perl</programlisting>


<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>


<programlisting>#!/usr/bin/perl
#
# see PROBLEMS for instructions on what sort of things to do
# when tracking a bug -tjh
...</programlisting>


<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>


<programlisting>BC-16              BC-32              FreeBSD            NetBSD-m86
NetBSD-sparc       NetBSD-x86         SINIX-N            VC-MSDOS
VC-NT              VC-W31-16          VC-W31-32          VC-WIN16
VC-WIN32           aix-cc             aix-gcc            alpha-cc
alpha-gcc          alpha400-cc        cc                 cray-t90-cc
debug              debug-irix-cc      debug-linux-elf    dgux-R3-gcc
dgux-R4-gcc        dgux-R4-x86-gcc    dist               gcc
hpux-cc            hpux-gcc           hpux-kr-cc         irix-cc
irix-gcc           linux-aout         linux-elf          ncr-scde
nextstep           purify             sco5-cc            solaris-sparc-cc
solaris-sparc-gcc  solaris-sparc-sc4  solaris-usparc-sc4 solaris-x86-gcc
sunos-cc           sunos-gcc          unixware-2.0       unixware</programlisting>


<para>For our system, we would enter the following:</para>


<programlisting># <userinput>./Configure linux-elf</userinput>
CC            =gcc
CFLAG         =-DL_ENDIAN -DTERMIO -DBN_ASM -O3 -fomit-frame-pointer
EX_LIBS       =
BN_MULW       =asm/bn86-elf.o
DES_ENC       =asm/dx86-elf.o asm/yx86-elf.o
BF_ENC        =asm/bx86-elf.o
CAST_ENC      =asm/cx86-elf.o
RC4_ENC       =asm/rx86-elf.o
RC5_ENC       =asm/r586-elf.o
MD5_OBJ_ASM   =asm/mx86-elf.o
SHA1_OBJ_ASM  =asm/sx86-elf.o
RMD160_OBJ_ASM=asm/rm86-elf.o
THIRTY_TWO_BIT mode
DES_PTR used
DES_RISC1 used
DES_UNROLL used
BN_LLONG mode
RC4_INDEX mode</programlisting>


<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>


<sect2 role="" label="A.3.1" id="appa-SECT-3.1">
<title>Configuring SSLeay for Your System</title>


<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>


<programlisting>PATH=$PATH:/usr/local/ssl/bin</programlisting>


<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>


<programlisting>cat &gt;/tmp/private.txt</programlisting>


<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>


<programlisting># ssleay genrsa -rand /tmp/private.txt &gt;/dev/null
2451 semi-random bytes loaded
Generating RSA private key, 512 bit long modulus
..+++++
.................................+++++
e is 65537 (0x10001)</programlisting>


<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>


<programlisting>rm -f /tmp/private.txt</programlisting>


<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>
</sect2>





<sect2 role="" label="A.3.2" id="appa-SECT-3.2">
<title>Configuring Samba to use SSL</title>


<para>
<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>


<programlisting>./configure --with-ssl</programlisting>


<para>After that, you can compile Samba with the following commands:</para>


<programlisting># <userinput>make clean</userinput>
# <userinput>make all</userinput></programlisting>


<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>


<para>On the other hand, if you have a clean compile, you're ready to move on to the next step: creating certificates.</para>
</sect2>





<sect2 role="" label="A.3.3" id="appa-62097">
<title>Becoming a Certificate Authority</title>


<para><firstterm></firstterm>
<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>


<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>


<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>


<programlisting># <userinput>cd /etc</userinput>
# <userinput>mkdir certificates</userinput>
# <userinput>chmod 700 certificates</userinput></programlisting>


<para>Note that we shut out all access to users other than <literal>root</literal> for this directory. This is very important.</para>


<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>


<programlisting>CATOP=./demoCA</programlisting>


<para>Then change it to:</para>


<programlisting>CATOP=/etc/certificates</programlisting>


<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>


<programlisting>[ CA_default ]
dir     = ./demoCA             # Where everything is kept</programlisting>


<para>Then change it to:</para>


<programlisting>[ CA_default ]
dir     =  /etc/certificates   # Where everything is kept</programlisting>


<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>


<programlisting>/usr/local/ssl/bin/CA.sh -newca
mkdir: cannot make directory '/etc/certificates': File exists
CA certificate filename (or enter to create)</programlisting>


<para>Press the Ent