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)

GreenArrow automatically generates these files on all installs performed after February 16, 2018:

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

If you’re on an older installation that has not generated them yet, you can generate them by running:

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

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

Providing an SMTPS Service

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

To set up an SMTPS service:

Ensure that the “Common prerequisites for TLS service” are set up.
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 its status is “UP”. For example, to restart the smtp3 service and verify its status, run:
```
svc -tu /service/hvmail-qmail-smtpd3 && sleep 7
hvmail_init status | grep hvmail-qmail-smtpd3
```

Providing the STARTTLS Extension on Port 25

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

GreenArrow provides the STARTTLS extension by default on port 25. No extra configuration is necessary, but if you wish to disable it, run the following commands:

echo 0 > /var/hvmail/control/smtp.starttls
svc -tu /service/hvmail-qmail-smtpd && sleep 7
hvmail_init status | grep "hvmail-qmail-smtpd "

To re-enable the STARTLS extension on servers where it was previously disabled, run:

echo 1 > /var/hvmail/control/smtp.starttls
svc -tu /service/hvmail-qmail-smtpd && sleep 7
hvmail_init status | grep "hvmail-qmail-smtpd "

Providing the STARTTLS Extension on Other Ports

GreenArrow provides the STARTTLS extension by default on port 587. To disable STARTTLS, follow the instructions below:

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 disable the STARTTLS extension on:
```
GREENARROW_STARTTLS=0
```
Restart the service that you just disabled STARTTLS on, and verify that its status is “UP”. For example, to restart the smtp2 service, run:
```
svc -tu /service/hvmail-qmail-smtpd2 && sleep 7
hvmail_init status | grep hvmail-qmail-smtpd2
```

Configuration Files

The following can be automatically created by running /var/hvmail/qmail-ram/bin/update_tmprsadh:

/var/hvmail/control/tls.dh2048.pem - If this 2048 bit DH key is provided, qmail-smtpd will use it for TLS sessions instead of generating one on-the-fly (which is very time-consuming).
/var/hvmail/control/tls.dh1024.pem - 1024 bit counterpart for /var/hvmail/control/tls.dh2048.pem.
/var/hvmail/control/tls.dh512.pem - 512 bit counterpart for /var/hvmail/control/tls.dh2048.pem.
/var/hvmail/control/tls.rsa1024.pem - If this 1024 bit RSA key is provided, qmail-smtpd will use it for TLS sessions instead of generating one on-the-fly.
/var/hvmail/control/tls.rsa512.pem - 512 bit counterpart for /var/hvmail/control/tls.rsa1024.pem.

The following are configured manually:

/var/hvmail/control/greenarrow.conf - controls the TLS certificate presented to clients as described in the Default TLS Certificate document.
/var/hvmail/control/tls.tlsserverciphers - A colon-delimited set of OpenSSL cipher strings. If the environment variable TLSCIPHERS is set to such a string, it takes precedence. To view a list of valid ciphers, run the openssl ciphers command. Your server’s man page for openssl may show additional invocations, such as openssl ciphers TLSv1.2 to list only TLS 1.2 compatible ciphers.

Unsupported Configuration Files

The following configuration files are unsupported and we may remove support for them 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.