GreenArrow Documentation

TLS Encryption for SMTP

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 set up an SMTPS service:

  1. Ensure that the “Common prerequisites for TLS service” are setup.
  2. In the /var/hvmail/control/smtp2 or /var/hvmail/control/smtp3 configuration file set:

    PORT=465
    

  3. And add the following to the end of the file:

    SMTPS=1
    export SMTPS
    

  4. 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 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 && svstat /service/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 && svstat /service/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:

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

  2. Restart the service that you just disabled 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. 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 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:

  1. Any SMTP delivery to port 465 will automatically use SMTPS, encrypting the entire connection with TLS (no additional configuration is required to enable this).

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