[Appendix A] A.3 Installing SSLeay

A.3 Installing SSLeay

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:

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 SSLeay-0.9.0b. 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.

SSLeay uses a Perl-based configure 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 /usr/local/bin/perl. You may need to change the configure 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:

# 

which perl
/usr/bin/perl

Then modify the first line of the configure script to force it to use the correct Perl executable. For example, on our Red Hat Linux system:

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

After that, you need to run the configure script by specifying a target platform for the distribution. This target platform can be any of the following:

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

For our system, we would enter the following:

# 

./Configure linux-elf
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

After the package has been configured, you can build it by typing make. If the build did not successfully complete, consult the documentation that comes with the distribution or the FAQ at http://www.cryptsoft.com/ssleay/ for more information on what may have happened. If the build did complete, type make install to install the libraries on the system. Note that the makefile installs the package in /usr/local/ssl by default. If you decide to install it in another directory, remember the directory when configuring Samba to use SSL.

A.3.1 Configuring SSLeay for Your System

The first thing you need to do is to set the PATH environment variable on your system to include the /bin directory of the SSL distribution. This can be done with the following statement:

PATH=$PATH:/usr/local/ssl/bin

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:

cat >/tmp/private.txt

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:

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

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:

rm -f /tmp/private.txt

The result of this command is the hidden file . rnd, which is stored in your home directory. SSLeay will use this file when creating key pairs in the future.

A.3.2 Configuring Samba to use SSL

At this point, you can compile Samba to use SSL. Recall that in Chapter 2, Installing Samba on a Unix System, 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:

./configure --with-ssl

After that, you can compile Samba with the following commands:

# 

make clean
# 

make all

If you encounter an error that says the smbd executable is missing the file ssl.h, you probably didn't install SSLeay in the default directory. Use the configure option --with-sslinc to point to the base directory of the SSL distribution - in this case, the directory that contains include/ssl.h.

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

A.3.3 Becoming a Certificate Authority

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 certificate authority. 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.

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

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 /etc/certificates as our default. Execute the following commands as root:

# 

cd /etc
# 

mkdir certificates
# 

chmod 700 certificates

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

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 CA.sh script located at /usr/local/ssl/bin/CA.sh to specify the location of the directory you just created. Find the line that contains the following entry:

CATOP=./demoCA

Then change it to:

CATOP=/etc/certificates

Next, you need to modify the /usr/local/ssl/lib/ssleay.cnf file to specify the same directory. Find the entry:

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

Then change it to:

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

Next, run the certificate authority setup script, CA.sh, 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:

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

Press the Enter key to create a certificate for the CA. You should then see:

Making CA certificate ...
Using configuration from /usr/local/ssl/lib/ssleay.cnf
Generating a 1024 bit RSA private key
.............................+++++
.....................+++++
writing new private key to /etc/certificates/private/cakey.pem
Enter PEM pass phrase:

Enter a new pass phrase for your certificate. You will need to enter it twice correctly before SSLeay will accept it:

Enter PEM pass phrase:
Verifying password - Enter PEM pass phrase:

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:

You are about to be asked to enter information that will be
incorporated into your certificate request.
What you are about to enter is what is called a Distinguished
Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.

Fill out the remainder of the fields with information about your organization. For example, our certificate looks like this:

Country Name (2 letter code) [AU]:

US
State or Province Name (full name) [Some-State]:

California
Locality Name (eg, city) []:

Sebastopol
Organization Name (eg, company) []:

O'Reilly
Organizational Unit Name (eg, section) []:

Books
Common Name (eg, YOUR name) []:

John Doe
Email Address []:

doe@ora.com

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.

A.3.4 Creating Certificates for Clients

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 SSLeay to sign the file as a trusted authority.

For our example client phoenix, this boils down to three SSLeay commands. The first generates a key pair for the client and places it in the file phoenix.key. The private key will be encrypted, in this case using triple DES. Enter a pass phrase when requested below - you'll need it for the next step:

# ssleay genrsa -des3 1024 >phoenix.key
1112 semi-random bytes loaded
Generating RSA private key, 1024 bit long modulus
........................................+++++
.............+++++
e is 65537 (0x10001)
Enter PEM pass phrase:
Verifying password - Enter PEM pass phrase:

After that command has completed, type in the following command:

# 

ssleay req -new -key phoenix.key -out phoenix-csr
Enter PEM pass phrase:

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 - those do not matter here. When the command completes, you will have a certificate request in the file phoenix-csr.

Then, you must sign the certificate request as the trusted certificate authority. Type in the following command:

# 

ssleay ca -days 1000 -inflies phoenix-csr >phoenix.pem

This command will prompt you to enter the PEM pass phrase of the certificate authority. 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:

Check that the request matches the signature
Signature ok
The Subjects Distinguished Name is as follows:
...

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 /etc/certificates/newcerts directory.

The operative files at the end of this exercise are the phoenix.key and phoenix.pem 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.

A.3.5 Configuring the Samba Server

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 /etc/certificates :

[global]
	ssl = yes
	ssl server cert = /etc/certificates/cacert.pem
	ssl server key = /etc/certificates/private/cakey.pem
	ssl CA certDir = /etc/certificates

At this point, you will need to kill the Samba daemons and restart them manually:

# 

nmbd -D
# 

smbd -D
Enter PEM pass phrase:

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.

A.3.6 Testing with smbclient

A good way to test whether Samba is working properly is to use the smbclient program. On the Samba server, enter the following command, substituting the appropriate share and user for a connection:

# 

smbclient //hydra/data -U tom

You should see several debugging statements followed by a line indicating the negotiated cipher, such as:

SSL: negotiated cipher: DES-CBC3-SHA

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.