Sendmail TLS Notes

$Id: README,v 1.1 2004/01/22 19:27:38 jmates Exp $

The certs directory is where I keep all Transport Security Layer (TLS)
related files for use with Sendmail (host keys and certificates, and
signing certificates used to verify other systems with).

The TLS protocol is the successor to the Secure Sockets Layer (SSL)
protocol; the two are identical with regard to the following
documentation.  I mention SSL primarily to catch folks doing web
searches using the old protocol name.

See the included sendmail.mc (and submit.mc) for the (disabled by
default) configuration parameters required for TLS to work (confCACERT
and so forth).  Additionally, the sendmail binary will need to be
compiled with STARTTLS support:

$ sendmail -d0 < /dev/null | grep -i tls
                PIPELINING SCANF STARTTLS TCPWRAPPERS USERDB XDEBUG


Certifying this Server with TLS

A TLS certificate should be generated for the host Sendmail runs as
(e.g. mail.example.org).  Self-signed certificates are easy to setup,
but may have security issues with clients that do not allow one to
accept/review the certificate.  Other options are to setup your own
Certificate Authority (CA) or to get your certificate from a
third-party CA:

http://directory.google.com/Top/Computers/Security/Public_Key_Infrastructure/PKIX/Tools_and_Services/Third_Party_Certificate_Authorities/

The Makefile in this directory will help in the generation of keys and
certificates; the rules are as follows.  Dependancies are handled
properly (the csr and self rules call rsa if no keyfile is found).

make csr           creates "certificate signing request" for a CA

make self          creates self-signed certificate

make rsa           generates RSA key (above rules more practical)

make fingerprint   shows checksum of certificate file (if any).

So, to create a certificate signing request to be sent to a CA, run
the following command in the /etc/mail/certs directory:

# make csr

The csr and self rules will solicit various required parameters.  Fill
out your Country and so forth properly; "Common Name" should be the
fully qualified hostname of the machine your are generating the
certificate for.  This is important for servers that get connected to
from GUI clients that compare such data to the hostname they are
connecting to.

Common Name (eg, YOUR name) []:mail.example.org

The contents of the generated host.csr need to be transfered to the CA
to processing somehow (e.g. pasted into a website form).

If renewing a certificate with a CA, use the file option to avoid
overwriting the existing key files:

# make csr file=new

Once the certificate is obtained from the CA, backup the old files,
then move the new.* files to the host.* files sendmail expects to use.

Note: Lacking a local certificate, Sendmail will complain at startup,
but generate an empty certificate to do unverified TLS with.


Verification of Other Systems

To verify the certificates that other servers are using, either
populate the confCACERT file (/etc/mail/certs/cacert.pem by default in
my setup) with certificates, or fill the confCACERT_PATH directory
with softlinks on the certificate hash to individual certificate files.

A confCACERT file can be obtained from the FreeBSD ports tree via FTP,
though obtaining it on a official CD-ROM or via SSH/TLS would be a
much better idea security wise (assuming you trust the FreeBSD ports
system to being with :).

ftp://ftp.freebsd.org/pub/FreeBSD/ports/ports-stable/security/ca-roots/files/ca-root.crt

See the Makefile in the confCACERT_PATH directory for an automated way
of enabling additional certificates.

Note: Sendmail may not enable TLS support if the confCACERT file is
undefined, missing, certificateless, or otherwise improperly setup.


Debugging

Increasing the confLOG_LEVEL in sendmail.mc to 15 (or higher) helps a
lot if you are having TLS problems.  Also check the mail headers;
sendmail places STARTTLS/SMTP AUTH information therein.

Sendmail may get picky about the ownership of the host.key file; make
sure it is readable by your confRUN_AS_USER (usually root if not
running as a proxy machine).