ucspi-ssl is William Baxter's OpenSSL-enabled analogue of Daniel J. Bernstein's ucspi-tcp package. It is intended as a drop-in replacement for ucspi-tcp, providing a quick and effective means of securing data connections for TCP services between hosts.

Everything about ucspi-ssl will be familiar terrain for the djb explorer: build is the classic make setup check; the errno.h source file requires the errno correction on GNU glibc platforms; the code "borrows" heavily from djb's own sources; the package even follows the "License Free" software copyright protocol.

So let's play. First, obtain the source distribution for the package. Right click on the link above; use ftp, wget, curl, lynx -dump; the usual. The installation procedure described below assumes the package will be available on your system in /usr/local/djb/dist-other/ucspi-ssl-0.50.tar.gz.

Verify the MD5 checksum:

# cd /usr/local/djb/dist-other
# md5 ucspi-ssl-0.50.tar.gz
MD5 (ucspi-ssl-0.50.tar.gz) = f8c0122aca1cafc5ef8d23ffdf466ccd

If the reported checksum doesn't agree, the package has been altered or corrupted. Delete the package and download it again from a trusted source.

Unpack the archive into your build directory:

# cd /usr/local/djb/build
# tar -xzvf ../dist/ucspi-ssl-0.50.tar.gz

You should now find a new directory in /usr/local/djb/build named ucspi-ssl-0.50. Change into this directory:

# cd ucspi-ssl-0.50

Here we have to fix things up a bit. For GNU glibc systems, the file error.h will need to be corrected as described in the appendix errno patches. First, save the original file:

# cp error.h error.h.orig

Now edit error.h and find the line that reads:

extern int errno;

Delete/change this line to read:

#include <errno.h>

The build can also be tuned to your host's OpenSSL installation, through entries made in a number of conf-* files. These files and their default entries are listed in the second and third columns of the table below:

The OpenSSL parameters may also be configured with environmental variables at service invocation; these variables are shown in the first column. The last column shows the settings used for the make test suite, discussed later on.

To the extent that you are familiar with the operation of OpenSSL and its configuration on your own host, edit the conf-* files to suit. For example, on our BSD systems, we set conf-cadir to /etc/ssl/certs, and conf-dhfile to /etc/ssl/dh1024.pem. To run the test suite successfully, make sure conf-dhfile points to a valid Diffie-Hellman parameter file (see make test below). Otherwise, don't worry too much about all this for now. We can always use envdir with our services, defining environmental variables as needed to override any compiled-in values.

Then continue with the build/install:

# make
# make setup check

The package includes a test suite that you can run to test your build. It is provided by the make target, make test. You can see what tests will be run by looking through the file named rts.tests.

There are a number of preconditions for these tests to run successfully. These include:

• tests not run with root priveleges (neither uid 0 or 1)
• dnscache resolves 127.0.0.1/localhost
• 127.0.0.1.cert and 127.0.0.1.key are updated
• dh1024.pem exists at the location defined in conf-dhfile
• host is connected to Internet

The test certificates included with the package have expired. To update them, download new ones from 127.0.0.1.cert and 127.0.0.1.key. These files will replace those included in the source distribution.

The tests also need to find 1024-bit Diffie-Hellman parameters in the file defined by conf-dhfile. For example, the default installation needs to find the file /usr/local/ssl/pem/dh1024.pem. If you don't have this file on your system yet, change to the directory corresponding to conf-dhfile and run this command. For example, on our BSD system:

# cd /etc/ssl
# openssl dhparam -check -text -5 1024 -out dh1024.pem

This command takes a little time to run, but only needs to be done once.

As for an Internet connection, this condition is only necessary to test failure of DNS lookups for nonexistent hosts. Without an Internet connection, the DNS lookup will time-out instead of fail. You can run the tests without an Internet-connected host; you'll just have to capture the output to see the results of other tests.

Once the preconditions are satisfied, check the build as an unpriveleged user (this user will need write permission in the source-tree directory):

$ make test

If you don't see any messages, congratulations!, ucspi-ssl is working fine. Otherwise, re-run the test, this time capturing the output for inspection:

$ ./rts > rts.out

Now you will need to compare the actual results in rts.out to the expected results in rts.exp. The log files in the subdirectory rts-tmp should also be inspected for clues. Run through the preconditions again, double check for typos in the conf-* files, then rebuild. Any difficulties are likely associated with file locations/spellings and access permissions.

Once everything is sorted out, you can inform the author of your success, using your own name in the following command:

# (echo 'Janet Jackson'; cat `cat SYSDEPS` ) | mail web-inst@superscript.com

Now you are ready for secure sockets, the djb way!