TLS Encryption for SMTP

Table of Contents
Receiving Mail Through SMTP Using TLS
Sending Email Using TLS

Receiving Mail Through SMTP Using TLS

Common Prerequisites for TLS Service

Create Temporary Key Tiles (Optional)

The following was already done for you if your GreenArrow server was first installed after February 16, 2018.

Create the following files:

/var/hvmail/control/tls.rsa512.pem
/var/hvmail/control/tls.dh512.pem
/var/hvmail/control/tls.dh1024.pem

These files can be created using this command:

/var/hvmail/qmail-ram/bin/update_tmprsadh

These files are not required, but they speed up providing TLS service.

Setup SSL Private Key and Certificate

Both the private key and certificate go together into the /var/hvmail/control/tls.servercert.pem file.

This command will copy the key and certificate used for HTTPS to TLS for SMTP:

cat /var/hvmail/control/httpd.ssl.{key,crt} > /var/hvmail/control/tls.servercert.pem
if [ -e /var/hvmail/control/httpd.ssl.ca ]; then
  cat /var/hvmail/control/httpd.ssl.ca >> /var/hvmail/control/tls.servercert.pem
fi

Providing an SMTPS Service

SMTPS is where the entire SMTP conversation is encrypted. This is normally provided on port 465.

To setup an SMTPS service:

Ensure that the “Common prerequisites for TLS service” are setup.
In the /var/hvmail/control/smtp2 or /var/hvmail/control/smtp3 configuration file set:
```
PORT=465
```
And add the following to the end of the file:
```
SMTPS=1
export SMTPS
```
Restart the service, and verify that it stays up for at least 5 seconds. For example, to restart the smtp3 service, run:
```
svc -tu /service/hvmail-qmail-smtpd3 && sleep 7 && svstat /service/hvmail-qmail-smtpd3
```

Providing a STARTTLS service

STARTTLS is an extension to SMTP that enables an SMTP conversation to start out as unencrypted, then enables encryption after a STARTTLS command is issued by the client.

GreenArrow provides the STARTTLS extension by default on port 587 on installations performed after February 16, 2018. It does not provide the STARTTLS by default on older installations. They can enable STARTTLS by following the instructions below:

Ensure that the “Common prerequisites for TLS service” are setup.
Add the following to the end of the /var/hvmail/control/smtp2 or /var/hvmail/control/smtp3 configuration file, depending on which server you wish to enable the STARTTLS extension on:
```
GREENARROW_STARTTLS=1
export GREENARROW_STARTTLS
```
Restart the service that you just enabled STARTTLS on, and verify that it stays up for at least 5 seconds. For example, to restart the smtp2 service, run:
```
svc -tu /service/hvmail-qmail-smtpd2 && sleep 7 && svstat /service/hvmail-qmail-smtpd2
```

Configuration Files

/var/hvmail/control/tls.dh1024.pem - If these 1024 bit DH parameters are provided, qmail-smtpd will use them for TLS sessions instead of generating one on-the-fly (which is very time-consuming).

This can be automatically created by running /var/hvmail/qmail-ram/bin/update_tmprsadh.
/var/hvmail/control/tls.dh512.pem - 512 bit counterpart for /var/hvmail/control/tls.dh1024.pem.

This can be automatically created by running /var/hvmail/qmail-ram/bin/update_tmprsadh.
/var/hvmail/control/tls.rsa512.pem - If this 512 bit RSA key is provided, qmail-smtpd will use it for TLS sessions instead of generating one on-the-fly.

This can be automatically created by running /var/hvmail/qmail-ram/bin/update_tmprsadh.
/var/hvmail/control/tls.servercert.pem - SSL certificate to be presented to clients in TLS-encrypted sessions. Should contain both the certificate and the private key. Certifying Authority (CA) and intermediate certificates can be added at the end of the file.
/var/hvmail/control/tls.tlsserverciphers - A set of OpenSSL cipher strings. Multiple ciphers contained in a string should be separated by a colon. If the environment variable TLSCIPHERS is set to such a string, it takes precedence.

Unsupported Configuration Files

The following configuration files are unsupported and the features provided by them may be removed in a future version of GreenArrow:

/var/hvmail/control/tls.clientca.pem - A list of Certifying Authority (CA) certificates that are used to verify the client-presented certificates during a TLS-encrypted session.
/var/hvmail/control/tls.clientcrl.pem - A list of Certificate Revocation Lists (CRLs). If present it should contain the CRLs of the CAs in /var/hvmail/control/tls.clientca.pem and client certs will be checked for revocation.
/var/hvmail/control/tls.tlsclients - A list of email addresses. When relay rules would reject an incoming message, qmail-smtpd can allow it if the client presents a certificate that can be verified against the CA list in /var/hvmail/control/tls.clientca.pem and the certificate email address is in /var/hvmail/control/tls.tlsclients.

Sending Email Using TLS

There are two ways to send mail through a TLS encrypted session:

Any SMTP delivery to port 465 will automatically use SMTPS, encrypting the entire connection with TLS (no additional configuration is required to enable this).
GreenArrow can issue the STARTTLS command when making any SMTP connections (to any port). See the starttls_use configuration directive for information on enabling this feature. GreenArrow can be configured to refuse to deliver without a successful TLS connection using starttls_require.