6. Transport Layer Security with s/qmail

s/qmail can be advised to use

• opportunistic (if available) and
• mandatory (always)

TLS encryption for a particular domain, or any mail transaction.

The following s/qmail modules support TLS:

• qmail-smtpd (STARTTLS, SMTPS)
• qmail-qmtpd (QMTPS)
• qmail-pop3d / qmail-popup (STLS, POP3S)
• qmail-remote (STARTTLS, SMTPS, QMTPS)
• qmail-smtpam (STARTTLS, SMTPS)

Quick links:

• 6.1 Prerequisits
• 6.2 TLS key material
• 6.3 s/qmail TLS server setup
• 6.4 STARTTLS and SMTPS support for qmail-remote

6.1 Prerequisits

Install ucspi-ssl (version ≥ 0.98).

Further, it is helpful to create a low privileged user and group ssl, which will be used by sslserver for SSL/TLS communication purposes. Please follow Scott Giffords' advices.

6.1.1 Naming conventions

Throughout this document, the following terms will the used:

• X.509 public certificate (in PEM format): CERTFILE, certfile, servercert.pem.
• X.509 private key file (in PEM format): KEYFILE, keyfile, serverkey.pem, clientkey.pem.
• X.509 certificate chain file (in PEM format): CERTCHAINFILE, chainfile.
• Diffie-Hellman parameter file: DHFILE, DHPARM, dhparam.

6.2 The TLS key material

In order to make TLS working, you need to provide the following key material:

• The server's X.509 certificate (public); here servercert.pem.
• The server's X.509 private key file (may be password protected; here serverkey.pem.
• A Diffie-Hellman paramater file; here dhparam.

These files need to be available in the PEM format.
For the server, it might be helpful to concatinate the root and intermediate X.509 certificates together with the server's cert as chainfile.pem.

In case, X.509 client certificates are requested from the server, the client certs need to be signed. The X.509 root cert can be different from the server's (public) root cert and can be additional provided.

For Elliptic Curve support no particular parameters are required; those are taken from internal defaults.

6.3 s/qmail TLS server setup

Apart from the 'global' environment variable UCSPITLS sslserver are fed by several environment typically included in a "profile" /var/qmail/ssl/env.

Typically, this file includes the following settings:

Note: These settings are 'global'; however, by means of sslserver and the settings in your tcp.smtpd file it is possible to use different certificates per connection.

6.3.1 Flexible STARTTLS/STLS settings per Client

Once UCSPITLS ist set and exported, qmail-smtpd accepts STARTTLS connections. However, it might be necessary to customize this behavior per sending MTA:

• Set UCSPITLS='!' to accept only STARTTLS SMTP sessions (aka 'REQUIRETLS').
• Set UCSPITLS='-' to disable STARTTLS by qmail-smtpd

While typically UCSPITLS='' is set qmail-smtpd's run file, you can redefine this variable in sslserver's tcp.smtpd control file per inbound connection.

6.3.2 qmail-smtpd/qmail-qmtpd settings for X.509 client authentication

Comment: Please read the documentation of UCSPI-SSL carefully w.r.t. the "mod-ssl" variables. It might in addition be necessary to define CAFILE, CADIR and other SSL options to your needs.

After you verified your settings, restart qmail-smtpd. Whether qmail-smtpd will present "STARTTLS" in the EHLO dialogue, depends on the presence of the UCSPITLS environment variable. These can be set i.e. per IP in the tcp.smtpd control file.

6.3.3 TLS Client verification by means of a X.509 certificate

Typically, the ESMTP client connecting to the server does not provide a X.509 certificate. In this case, the ESMTP connection is still TLS encrypted and the client might use the server's certificate for verification/validiation purpose.

However the server may request a valid X.509 certificate from the client. In this case, the sslserver needs to have the certificate of the CA (Certificate Authority) which has signed the client's certificate in the first place (in PEM format).

1. Make sslserver aware of the CA certificate by means of setting the environment variable $CACERT accordingly or include the 'hashed' certificate in a directory available via $CADIR.
2. Include the IP or the FQDN of the specific SMTP client into tcp.smptd database and define and populate the environment variable $CCACERT with the path to the specific CA X.509 certifiate (in PEM) format.
3. Call sslerver with the option '-i' and '-h' (default) to interrogate the X.509 certificate of those clients which have additionally the environment variable $CCACERT set and to lookup the FQDN in the DNS.

sslserver will not only ask for the client certificate but will verify it by means of the CA certificate and validate its content matching the received FQDN with the presented 'SubjectNameAltName' and perhaps the 'Distinguished Name' in the client certificate.

In case, any of the checks fail, the connection attempt will be refused.

6.3.4 (START)TLS and SMTPAUTH

In case qmail-smtpd is instructed to use STARTTLS and SMTPAUTH, SMTP Authentication always takes place after the TLS session is active, but never reverse. Thus, all SMTP parameters like username and password are already encrypted. Of course, SMTP Authentication is still available for unencrypted SMTP connections, and STARTTLS does not require per se SMTP Authentication. However, STARTTLS and SMTP Authentication is a strong and powerful couple to secure the SMTP communication.

6.3.5 (START)TLS Received Header Extensions

The TLS information is displayed in the Received header (according to RFC 3207). The following information is added:

• The TLS protocol in use.
• The Cipher in use.
• The presented encryption key length and key length in place.
• The client's "Subject" Distinguished Name (DN).

Here's a sample using Thunderbird als email client:

Note: The received DN ist typically 'unknown' because the client doesn't provide a certificate.

In the above case the keyword ESMTPSA tells that the connection was established via SMTPS and additionally was authenticated A: (E)SMTPS(A).

6.3.6 Client Certificates and Relaying

qmail-smtpd supports SMTP client authentication by means of X.509 client certificates. How to achieve this?

1. Each SMTP client needs to be provisioned with a valid X.509 certificate. This certificate typically is a user certificate and includes the email address as part of the Distinguished Name (DN) or as part of the 'Subject Alternative Name' (SAN).
2. The client certificates need be be signed by a CA (called the Client CA, CCA), for which the root certificate needs to be present and deployed to the SMTP server (in our case: sslserver).
3. Both, the SMTP server and the SMTP client need to be aware to request/respond to client certificate requests. In case of sslserver, the option -z> is dedicated for this operation.
4. For sslserver this means to provide the root certificate by providing CCAFILE=path_to_certificate. For the client this requieres usually the setting 'Authentication=TLS Certifiate'.

SMTP client authentication is a private mean; thus does not require an 'official X.509' certificate. Self-signed are good enough. Practically, one may use 'official' certificates provded by means of $CERTFILE, while the path to $CCAFILE may include serveral concatinated X.509 root certs against those the clients are checked.

In case, serveral authentication domains are required -- which have their own CA -- those CAs can be 'stacked' into one PEM file presented by means of $CCAFILE. If the client cert matches one, the client is authenticated.

Since the SSL environment variables are fed from sslserver to qmail-smtpd by means of MOD_SSL, qmail-smtpd has only knowledge of the Distinguished Name and its component, i.e. the email-address. Unfortunately, their is no way in inquire the SAN component of a X.509 V3 certificate. Thus, in oder to verify the provided email address in the SMTP envelope (the Return-Path) against the address in the X.509 cert, only the DN can be evaluated.

It is important to understand the roles of CA and CCA certs:

• CCA certs are used to indicate the client which cert it should present.
• CA certs are used to verify the presented cert.

Thus, for practical reasons, CA and CCA certs could be identical, where CCA certs are a subset of CA certs (which may be taken from a CADIR).

In order to support X.509 user certificates by sslserver it needs to be called with the option '-m'. Thus, sslserver posses three different understandings about client certificate:

1. -Z (Default): Don't request a client certificate.
2. -z: Request for client certificates and check the provided hostname in the cert against the FQDN (if given).
3. -m: Request a client certificate but don't check the hostname.

sslserver has two means to control the client certificate request:

• The (global) options -z and -m.
• The presence of the environment variable CCA including the path the the client CAs. Typically, sslserver would refuse to run, if the option -z or -m is provided, but no CCA file is available. However, setting CCA="-" disables the global options.

6.3.7 Client Certificate Authentication

Setting up qmail-smtpd for Client Certificate Authentication inflicts with standard SMTP Authentication. Thus, once qmail-smtpd recognizes a valid client certificate (either using SMTPS or STARTTLS), it disables SMTP Auth by default.

As a consequence, the MUA does not need to posses a valid userid/password. In case the client cert is accepted, it reacts as RELAYCLIENT. The DN in the cert is considered as TCPREMOTEINFO.

However, the provided Return-Path address in the 'Mail From:' may be checked against the email address in the client's DN. Use LOCALMFCHECK='?' to enforce a mapping of both.

6.4 STARTTLS and SMTPS support for qmail-remote

qmail-remote uses the SSL routines provided by UCSPI-SSL and can be advised to set up a TLS session with the ESMTP peer in the following ways:

1. A usual STARTTLS session only makes use of the encryption available by means of the OpenSSL libraries.
2. A legimated STARTTLS / SMTPS session allows you to verify the server's X.509 certificate against a known CA.
3. A particular STARTTLS / SMTPS session allows you to verify the server's X.509 certificate and to validate the provided 'Subject' in the SAN/DN against the hostname retrieved from the DNS. This can be used for server authentication.
4. A client-authenticated STARTTLS / SMTPS session requires to have a valid client X.509 certificate to be requested by the ESMTP server application and presented on a peer-2-peer base. In consequence, the CA certificate is (mutually) used (1) for signing the client certificate and (2) to verify the client certificate at the server side.
5. qmail-remote will automatically perform a DANE/TLSA lookup and comparision against the received X.509 cert. Detail are given in chapter 9.
6. qmail-remote and qmail-smtpam can be adviced per port to swith to TLS mode instead of offering (a delayed) StartTLS session.

6.4.1 qmail-remote's trust and key store

qmail-remote does not use a particulary separated

• trust store where root and intermediate root certificats are stored, and
are kept.

Thus, those files can be places anywhere in the file hierarchy, however those files are read every time as qmail-remote is invoked. Since qmail-remote runs as qmailr take care to restrict access rights to this user.

It is suggested to use the directory /var/qmail/ssl (or equivalent) to store the respective TLS files. The X.509 certificate file might include the private key. If it is read separately, it might be protected with a passphrase; but this has to be provided to qmail-remote as clear text.

6.4.2 qmail-remote TLS control files

You can control the TLS connectivity behavior of qmail-remote by means of

• control/tlsdestinations

STARTTLS support for qmail-remote becomes effective, simply populating this file with

meaning 'use TLS encryption for any peer offering STARTTLS support, or in case of connecting to port 465 use SMTPS'.

Alternatively, 'Anonymous Diffie-Hellman' is requested and no X.509 certificate is evaluated by means of:

This control file is separated into a 'destination domain' the left side of the colon and a (structured) informational part right from the colon employing '|' the bar character for separation and perhaps a colon for the port in the last position. Two usages of control/tlsdestinations do exist:

The first form tells qmail-remote to perform a 'regular' PKI validation and verification of the received certificate, the second form is used solely for 'peering'. Now, the certificate is only accepted, if it posses the provided fingerpint. The last form is used to disable TLS and certificate checking for a particular host/domain (as last resort).

Destination

• may be an '*' asterisk symbol meaning 'any host', or
• may start with a dash '-' which disables the verification of a X.509 certificate (all: '-*'), or
• may start with a equal sign '=' telling qmail-remote to additionally verify the cert's Subject Alternative Name against the FQDN.
• Wildcard certificates need special care and are accepted by the domain check if labeled as '~' prepending the given domain name (or '*').

cafile is the full-qualified path name to the CA certificate file in PEM format. This certificate file can be build of several X.509 certs. If however, cafile ends with a slash "/", a CADIR is assumed hosting the certificates in a "hashed" format.

The expression for the accepted cipher can be constructed individually. Check the OpenSSL information for the syntax and the accepted values.

The verifydepth parameter defaults 1 and should be adjusted to the nesting of the certificates in the chain.

In case port equals 465 the SMTPS port, STARTTLS is not tried but rather a standard TLS connection is required.

Finally, an entry in control/tlsdestinations can be bound against the the senddomain in case several outgoing domains are used. Thus, an entry is only valid, if it matches the senddomain.

The file control/tlsdestinations is evaluated in the following order (for the same domain, the more specific information is taken) with additional customization samples included:

Thus, you can specify particular hosts/domain to set up a STARTTLS connection to, - or - exclude particular hosts by means of an prepended exclamation mark (!) following the hostname.

6.4.3 Legitimated STARTTLS / SMTPS sessions

Since the ESMTP server always presents a X.509 certificate, this can used for additional interrogation:

• A verification of the ESMTP server's X.509 certificate can be accomplished against a (set of) CA' certificates available in a PEM file or in a particular directory (with 'hashed' PEM file names).
• The request for particular TLS Ciphers.
• The acceptable VERIFYDEPTH for the server's certificate (Default: 1).
• A particular port to connect to (ie. 465 for SMTPS) following a (last) colon.

PKIX Legitimation:

Public Key Infrastructure PKIX legitimation can be enabled for qmail-remote by means of control/tlsdestinations using the following default:

However, this has severe caveats:

1. The Trust Store needs to cover all X.509 root and intermediate certificates, if the connecting server does not provide intermedisate certs.
2. A lot MTAs using self-signed certificates: protonmail.ch, mailbox.org and many others. Those have to be explicitely mentioned in control/tlsdestionations otherwise the connection would fail, since not verifiable given the missing trust.

Like most other MTAs, s/qmail does not depend on certificate chains. It is the duty of the email administrator to enfore extended legitimation here.

6.4.4 Particular STARTTLS / SMTPS sessions

Here, the server's X.509 certificate can be checked:

• A hostname prepended with a '=' (equal) sign will validate the presented 'SubjectName' / 'SubjectAlternativeName (SAN)' against the received FQDN of the ESMTP server.
• Occasionally, the certificate's hostname is 'wildcarded'. This can be coped with a '~' (tilde) sign prepending the domain or hostname.
• A verification of the ESMTP server's X.509 certificate can be accomplished against a (set of) CA' certificates available in a PEM file or in a particular directory (with 'hashed' PEM file names).
• The request for particular TLS Ciphers.
• The acceptable VERIFYDEPTH for the server's certificate (Default: 1).
• A particular port to connect to (ie. 465 for SMTPS) following a (last) semi-colon.

6.4.5 Peering STARTTLS / SMTPS sessions

Ultimatively, qmail-remote can be advised to accept only certificate by the peer as included with their fingerprint. In this case, the X.509 certificate has to be exchanged peer-to-peer or its fingerprint has to be known.

s/qmail includes some OpenSSL commands to generate the fingerprint of a given certificate to be included for this purpose. With this option, you can guarantee the security of a connection irrespectively of any PKI.

6.4.6 Authenticated STARTTLS / SMTPS qmail-remote sessions

On the ESMTP's server request, qmail-remote will provide (if available) a X.509 client certificate. The server may evaluate this certificate and set credentials (ie. relaying), accordingly.

• The ESMTP server needs to have access to the CA certificate which was used to sign the client X.509 certificate.
• qmail-remote needs to have the signed X.509 client certificate and (of course) the private keyfile. The keyfile may be password protected.

This information can be provided per senddomain (see domainips) by means of the control file

• control/domaincerts

which is structured comparable to control/tlsdestinations. Thus the part left from the colon tells the sending domain; in case this equals "*" all outgoing connections use the same certificate/keyfile. The right parts provides the location and the certfile (in PEM format), the keyfile (if any) and perhaps the password to decrypt the keyfile; all separated by a '|':

6.4.7 'Implicit TLS' support

As defined in RFC 8314, 'Implict TLS' means, that TLS is automatically provided on any port, avoiding StartTLS since it is considered 'insecure'. What are the consequences given this new 'declaration' of the TLS use?

1. Most important: Current Mail User Agents (MUAs, like Thunderbird or Evolution) should use the SMTPS port 465 upon submission and not port 587 anymore. Which means, the SMTPS port 456 is now acting solely for authenticated mails. This is good news.
2. Second important: Omitting StartTLS on standard ports requires not only the server to use TLS instead of StartTLS but also needs to enable the SMTP client to switch from StartTLS to TLS mode.

The clients qmail-remote and qmail-smtpam are partially enabled to do so:

• Traditionally qmail-remote can be instructed my means ./control/smtproutes and/or ./control/authsender to use TLS instead of the default StartTLS in case a 'secure' remote port is given as s587 instead of 587 in the usual case. Thus 's' means: Go to TLS directly.
• While this mechanism works as well for qmail-smtpam additionally, the command line port parameter can also be prepended with an 's' resulting in the same behavior of 'implicit TLS'.

RFC 8413 also defines a 'new' DNS record while "adding a new SRV service label _submissions._tcp to refer to Message Submission with Implicit TLS." Potentially, this will be supported in the forthcoming releases. However, this is only useful for personal MUAs and not MTAs, possessing of cause SMTP sending capabilities. In case a 'trust' relationship is established with an upstream SMTP server, the (security) conditions need to be agreed upon, now already supported with the given mechanisms.

• [FEHCom]
• [Impressum]
• [News]
• [top]