diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-06 01:46:30 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-06 01:46:30 +0000 |
| commit | b5896ba9f6047e7031e2bdee0622d543e11a6734 (patch) | |
| tree | fd7b460593a2fee1be579bec5697e6d887ea3421 /README_FILES/TLS_README | |
| parent | Initial commit. (diff) | |
| download | postfix-upstream.tar.xz postfix-upstream.zip | |
Adding upstream version 3.4.23.upstream/3.4.23upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'README_FILES/TLS_README')
| -rw-r--r-- | README_FILES/TLS_README | 2495 |
1 files changed, 2495 insertions, 0 deletions
diff --git a/README_FILES/TLS_README b/README_FILES/TLS_README new file mode 100644 index 0000000..f0cddeb --- /dev/null +++ b/README_FILES/TLS_README @@ -0,0 +1,2495 @@ +PPoossttffiixx TTLLSS SSuuppppoorrtt + +------------------------------------------------------------------------------- + +WWhhaatt PPoossttffiixx TTLLSS ssuuppppoorrtt ddooeess ffoorr yyoouu + +Transport Layer Security (TLS, formerly called SSL) provides certificate-based +authentication and encrypted sessions. An encrypted session protects the +information that is transmitted with SMTP mail or with SASL authentication. + +NOTE: By turning on TLS support in Postfix, you not only get the ability to +encrypt mail and to authenticate remote SMTP clients or servers. You also turn +on hundreds of thousands of lines of OpenSSL library code. Assuming that +OpenSSL is written as carefully as Wietse's own code, every 1000 lines +introduce one additional bug into Postfix. + +Topics covered in this document: + + * How Postfix TLS support works + * SMTP Server specific settings + * SMTP Client specific settings + * TLS manager specific settings + * Building Postfix with TLS support + * Reporting problems + * Credits + +And last but not least, for the impatient: + + * Getting started, quick and dirty + +HHooww PPoossttffiixx TTLLSS ssuuppppoorrtt wwoorrkkss + +The diagram below shows the main elements of the Postfix TLS architecture and +their relationships. Colored boxes with numbered names represent Postfix daemon +programs. Other colored boxes represent storage elements. + + * The smtpd(8) server implements the SMTP over TLS server side. + + * The smtp(8) client implements the SMTP (and LMTP) over TLS client side. + + * The tlsmgr(8) server maintains the pseudo-random number generator (PRNG) + that seeds the TLS engines in the smtpd(8) server and smtp(8) client + processes, and maintains the TLS session key cache files. + +Not shown in the figure are the tlsproxy(8) server and the postscreen(8) +server. These use TLS in the same manner as smtpd(8). + + <---seed---- ----seed---> +Network-> smtpd(8) tlsmgr(8) smtp(8) ->Network + <-key/cert-> <-key/cert-> + + / | \ + | + / \ + + smtpd PRNG smtp + session state session + key cache file key cache + +SSMMTTPP SSeerrvveerr ssppeecciiffiicc sseettttiinnggss + +Topics covered in this section: + + * Server-side certificate and private key configuration + * Server-side forward-secrecy configuration + * Server-side TLS activity logging + * Enabling TLS in the Postfix SMTP server + * Client certificate verification + * Supporting AUTH over TLS only + * Server-side TLS session cache + * Server access control + * Server-side cipher controls + * Miscellaneous server controls + +SSeerrvveerr--ssiiddee cceerrttiiffiiccaattee aanndd pprriivvaattee kkeeyy ccoonnffiigguurraattiioonn + +In order to use TLS, the Postfix SMTP server generally needs a certificate and +a private key. Both must be in "PEM" format. The private key must not be +encrypted, meaning: the key must be accessible without a password. The +certificate and private key may be in the same file, in which case the +certificate file should be owned by "root" and not be readable by any other +user. If the key is stored separately, this access restriction applies to the +key file only, and the certificate file may be "world-readable". + +Public Internet MX hosts without certificates signed by a well-known public CA +must still generate, and be prepared to present to most clients, a self-signed +or private-CA signed certificate. The remote SMTP client will generally not be +able to verify the self-signed certificate, but unless the client is running +Postfix or similar software, it will only negotiate TLS ciphersuites that +require a server certificate. + +For servers that are nnoott public Internet MX hosts, Postfix supports +configurations with no certificates. This entails the use of just the anonymous +TLS ciphers, which are not supported by typical SMTP clients. Since some +clients may not fall back to plain text after a TLS handshake failure, a +certificate-less Postfix SMTP server will be unable to receive email from some +TLS-enabled clients. To avoid accidental configurations with no certificates, +Postfix enables certificate-less operation only when the administrator +explicitly sets "smtpd_tls_cert_file = none". This ensures that new Postfix +SMTP server configurations will not accidentally enable TLS without +certificates. + +Note that server certificates are nnoott optional in TLS 1.3. To run without +certificates you'd have to disable the TLS 1.3 protocol by including '!TLSv1.3' +in "smtpd_tls_protocols" and perhaps also "smtpd_tls_mandatory_protocols". It +is simpler instead to just configure a certificate chain. Certificate-less +operation is not recommended. + +RSA, DSA and ECDSA (Postfix >= 2.6) certificates are supported. Most sites only +have RSA certificates. You can configure all three at the same time, in which +case the ciphersuite negotiated with the remote SMTP client determines which +certificate is used. If your DNS zone is signed, and you want to publish DANE +TLSA (RFC 6698, RFC 7671, RFC 7672) records, these must match all of the +configured certificate chains. Since the best practice is to publish "3 1 1" +certificate associations, create a separate TLSA record to match each public- +key certificate digest. + +CCrreeaattiinngg tthhee sseerrvveerr cceerrttiiffiiccaattee ffiillee + +To verify the Postfix SMTP server certificate, the remote SMTP client must +receive the issuing CA certificates via the TLS handshake or via public-key +infrastructure. This means that the Postfix server public-key certificate file +must include the server certificate first, then the issuing CA(s) (bottom-up +order). The Postfix SMTP server certificate must be usable as SSL server +certificate and hence pass the "openssl verify -purpose sslserver ..." test. + +The examples that follow show how to create a server certificate file. We +assume that the certificate for "server.example.com" was issued by +"intermediate CA" which itself has a certificate issued by "root CA". + + * With legacy public CA trust verification, you can omit the root certificate + from the "server.pem" certificate file. If the client trusts the root CA, + it will already have a local copy of the root CA certificate. Omitting the + root CA certificate reduces the size of the server TLS handshake. + + % ccaatt sseerrvveerr__cceerrtt..ppeemm iinntteerrmmeeddiiaattee__CCAA..ppeemm >> sseerrvveerr..ppeemm + + * If you publish DANE TLSA (RFC 6698, RFC 7671, RFC 7672) "2 0 1" or "2 1 1" + records to specify root CA certificate digests, you must include the + corresponding root CA certificates in the "server.pem" certificate file. + + % ccaatt sseerrvveerr__cceerrtt..ppeemm iinntteerrmmeeddiiaattee__CCAA..ppeemm rroooott..ppeemm >> sseerrvveerr..ppeemm + + Remote SMTP clients will be able to use the TLSA record you publish (which + only contains the certificate digest) only if they have access to the + corresponding certificate. Failure to verify certificates per the server's + published TLSA records will typically cause the SMTP client to defer mail + delivery. The foregoing also applies to "2 0 2" and "2 1 2" TLSA records or + any other digest of a CA certificate, but it is expected that SHA256 will + be by far the most common digest for TLSA. + + As a best practice, publish "3 1 1" TLSA associations that specify the + SHA256 digest of the server's public key. These continue to work unmodified + when a certificate is renewed with the same public/private key pair. + +For instructions on how to compute the digest of a certificate or its public +key for use in TLSA records, see the documentation of the +smtpd_tls_fingerprint_digest main.cf parameter. + +When a new key or certificate is generated, an additional TLSA record with the +new digest must be published in advance of the actual deployment of the new key +or certificate on the server. You must allow sufficient time for any TLSA +RRsets with only the old digest to expire from DNS caches. The safest practice +is to wait until the DNSSEC signature on the previous TLSA RRset expires, and +only then switch the server to use new keys published in the updated TLSA +RRset. Once the new certificate trust chain and private key are in effect, the +DNS should be updated once again to remove the old digest from the TLSA RRset. + +If you want the Postfix SMTP server to accept remote SMTP client certificates +issued by one or more root CAs, append the root certificate to +$smtpd_tls_CAfile or install it in the $smtpd_tls_CApath directory. + +CCoonnffiigguurriinngg tthhee sseerrvveerr cceerrttiiffiiccaattee aanndd kkeeyy ffiilleess + +Example: Postfix >= 3.4 all-in-one chain file(s). One or more chain files that +start with a key that is immediately followed by the corresponding certificate +and any additional issuer certificates. A single file can hold multiple (key, +cert, [chain]) sequences, one per algorithm. It is typically simpler to keep +the chain for each algorithm in its own file. Most users are likely to deploy +just a single RSA chain, but with OpenSSL 1.1.1, it is possible to deploy up to +five chains, one each for RSA, ECDSA, ED25519, ED448 and even the obsolete DSA. + + # Postfix >= 3.4. Preferred configuration interface. Each file + # starts with the private key, followed by the corresponding + # certificate, and any intermediate issuer certificates. The root CA + # cert may also be needed when published as a DANE trust anchor. + # + smtpd_tls_chain_files = + /etc/postfix/rsa.pem, + /etc/postfix/ecdsa.pem, + /etc/postfix/ed25519.pem, + /etc/postfix/ed448.pem + +You can also store the keys separately from their certificates, again provided +each is listed before the corresponding certificate chain. Storing a key and +its associated certificate chain in separate files is not recommended, because +this is prone to race conditions during key rollover, as there is no way to +update multiple files atomically. + + # Postfix >= 3.4. + # Storing keys separately from the associated certificates is not + # recommended. + smtpd_tls_chain_files = + /etc/postfix/rsakey.pem, + /etc/postfix/rsacerts.pem, + /etc/postfix/ecdsakey.pem, + /etc/postfix/ecdsacerts.pem + +The below examples show the legacy algorithm-specific configurations for +Postfix 3.3 and older. With Postfix <= 3.3, even if the key is stored in the +same file as the certificate, the file is read twice and a (brief) race +condition still exists during key rollover. While Postfix >= 3.4 avoids the +race when the key and certificate are in the same file, you should use the new +"smtpd_tls_chain_files" interface shown above. + +RSA key and certificate examples: + + /etc/postfix/main.cf: + smtpd_tls_cert_file = /etc/postfix/server.pem + smtpd_tls_key_file = $smtpd_tls_cert_file + +Their DSA counterparts: + + /etc/postfix/main.cf: + smtpd_tls_dcert_file = /etc/postfix/server-dsa.pem + smtpd_tls_dkey_file = $smtpd_tls_dcert_file + +Their ECDSA counterparts (Postfix >= 2.6 + OpenSSL >= 1.0.0): + + /etc/postfix/main.cf: + # Some clients will not be ECDSA capable, so you will likely still need + # an RSA certificate and private key. + # + smtpd_tls_eccert_file = /etc/postfix/server-ecdsa.pem + smtpd_tls_eckey_file = $smtpd_tls_eccert_file + +TLS without certificates for servers serving exclusively anonymous-cipher +capable clients: + + /etc/postfix/main.cf: + # Not recommended: breaks TLS 1.3 and clients that don't support + # anonymous cipher suites. + smtpd_tls_cert_file = none + +To verify a remote SMTP client certificate, the Postfix SMTP server needs to +trust the certificates of the issuing Certification Authorities. These +certificates in "PEM" format can be stored in a single $smtpd_tls_CAfile or in +multiple files, one CA per file in the $smtpd_tls_CApath directory. If you use +a directory, don't forget to create the necessary "hash" links with: + + # $$OOPPEENNSSSSLL__HHOOMMEE//bbiinn//cc__rreehhaasshh //ppaatthh//ttoo//ddiirreeccttoorryy + +The $smtpd_tls_CAfile contains the CA certificates of one or more trusted CAs. +The file is opened (with root privileges) before Postfix enters the optional +chroot jail and so need not be accessible from inside the chroot jail. + +Additional trusted CAs can be specified via the $smtpd_tls_CApath directory, in +which case the certificates are read (with $mail_owner privileges) from the +files in the directory when the information is needed. Thus, the +$smtpd_tls_CApath directory needs to be accessible inside the optional chroot +jail. + +When you configure the Postfix SMTP server to request client certificates, the +DNs of Certification Authorities in $smtpd_tls_CAfile are sent to the client, +in order to allow it to choose an identity signed by a CA you trust. If no +$smtpd_tls_CAfile is specified, no preferred CA list is sent, and the client is +free to choose an identity signed by any CA. Many clients use a fixed identity +regardless of the preferred CA list and you may be able to reduce TLS +negotiation overhead by installing client CA certificates mostly or only in +$smtpd_tls_CApath. In the latter case you need not specify a $smtpd_tls_CAfile. + +Note, that unless client certificates are used to allow greater access to TLS +authenticated clients, it is best to not ask for client certificates at all, as +in addition to increased overhead some clients (notably in some cases qmail) +are unable to complete the TLS handshake when client certificates are +requested. + +Example: + + /etc/postfix/main.cf: + smtpd_tls_CAfile = /etc/postfix/CAcert.pem + smtpd_tls_CApath = /etc/postfix/certs + +SSeerrvveerr--ssiiddee ffoorrwwaarrdd--sseeccrreeccyy ccoonnffiigguurraattiioonn + +If you want to take maximal advantage of ciphers that offer forward secrecy see +the Getting started section of FORWARD_SECRECY_README. The full document +conveniently presents all information about Postfix forward secrecy support in +one place: what forward secrecy is, how to tweak settings, and what you can +expect to see when Postfix uses ciphers with forward secrecy. + +SSeerrvveerr--ssiiddee TTLLSS aaccttiivviittyy llooggggiinngg + +To get additional information about Postfix SMTP server TLS activity you can +increase the log level from 0..4. Each logging level also includes the +information that is logged at a lower logging level. + + _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ + |LLeevveell|PPoossttffiixx 22..99 aanndd llaatteerr |EEaarrlliieerr rreelleeaasseess.. | + |_ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |0 |Disable logging of TLS activity. | + |_ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |1 |Log only a summary message on TLS |Log the summary message, peer | + | |handshake completion -- no logging|certificate summary information| + | |of client certificate trust-chain |and unconditionally log trust- | + | |verification errors if client |chain verification errors. | + | |certificate verification is not | | + | |required. | | + |_ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |2 |Also log levels during TLS negotiation. | + |_ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |3 |Also log hexadecimal and ASCII dump of TLS negotiation process. | + |_ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |4 |Also log hexadecimal and ASCII dump of complete transmission after| + | |STARTTLS. | + |_ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + +Use log level 3 only in case of problems. Use of log level 4 is strongly +discouraged. + +Example: + + /etc/postfix/main.cf: + smtpd_tls_loglevel = 0 + +To include information about the protocol and cipher used as well as the client +and issuer CommonName into the "Received:" message header, set the +smtpd_tls_received_header variable to true. The default is no, as the +information is not necessarily authentic. Only information recorded at the +final destination is reliable, since the headers may be changed by intermediate +servers. + +Example: + + /etc/postfix/main.cf: + smtpd_tls_received_header = yes + +EEnnaabblliinngg TTLLSS iinn tthhee PPoossttffiixx SSMMTTPP sseerrvveerr + +By default, TLS is disabled in the Postfix SMTP server, so no difference to +plain Postfix is visible. Explicitly switch it on with +"smtpd_tls_security_level = may". + +Example: + + /etc/postfix/main.cf: + smtpd_tls_security_level = may + +With this, the Postfix SMTP server announces STARTTLS support to remote SMTP +clients, but does not require that clients use TLS encryption. + +Note: when an unprivileged user invokes "sendmail -bs", STARTTLS is never +offered due to insufficient privileges to access the Postfix SMTP server +private key. This is intended behavior. + +You can ENFORCE the use of TLS, so that the Postfix SMTP server announces +STARTTLS and accepts no mail without TLS encryption, by setting +"smtpd_tls_security_level = encrypt". According to RFC 2487 this MUST NOT be +applied in case of a publicly-referenced Postfix SMTP server. This option is +off by default and should only seldom be used. + +Example: + + /etc/postfix/main.cf: + smtpd_tls_security_level = encrypt + +TLS is sometimes used in the non-standard "wrapper" mode where a server always +uses TLS, instead of announcing STARTTLS support and waiting for remote SMTP +clients to request TLS service. Some clients, namely Outlook [Express] prefer +the "wrapper" mode. This is true for OE (Win32 < 5.0 and Win32 >=5.0 when run +on a port<>25 and OE (5.01 Mac on all ports). + +It is strictly discouraged to use this mode from main.cf. If you want to +support this service, enable a special port in master.cf and specify "- +o smtpd_tls_wrappermode=yes" (note: no space around the "=") as an smtpd(8) +command line option. Port 465 (smtps) was once chosen for this feature. + +Example: + + /etc/postfix/master.cf: + smtps inet n - n - - smtpd + -o smtpd_tls_wrappermode=yes -o smtpd_sasl_auth_enable=yes + +CClliieenntt cceerrttiiffiiccaattee vveerriiffiiccaattiioonn + +To receive a remote SMTP client certificate, the Postfix SMTP server must +explicitly ask for one (any contents of $smtpd_tls_CAfile are also sent to the +client as a hint for choosing a certificate from a suitable CA). Unfortunately, +Netscape clients will either complain if no matching client certificate is +available or will offer the user client a list of certificates to choose from. +Additionally some MTAs (notably some versions of qmail) are unable to complete +TLS negotiation when client certificates are requested, and abort the SMTP +session. So this option is "off" by default. You will however need the +certificate if you want to use certificate based relaying with, for example, +the permit_tls_clientcerts feature. A server that wants client certificates +must first present its own certificate. While Postfix by default offers +anonymous ciphers to remote SMTP clients, these are automatically suppressed +when the Postfix SMTP server is configured to ask for client certificates. + +Example: + + /etc/postfix/main.cf: + smtpd_tls_ask_ccert = yes + smtpd_tls_security_level = may + +When TLS is enforced you may also decide to REQUIRE a remote SMTP client +certificate for all TLS connections, by setting "smtpd_tls_req_ccert = yes". +This feature implies "smtpd_tls_ask_ccert = yes". When TLS is not enforced, +"smtpd_tls_req_ccert = yes" is ignored and a warning is logged. + +Example: + + /etc/postfix/main.cf: + smtpd_tls_req_ccert = yes + smtpd_tls_security_level = encrypt + +The client certificate verification depth is specified with the main.cf +smtpd_tls_ccert_verifydepth parameter. The default verification depth is 9 (the +OpenSSL default), for compatibility with Postfix versions before 2.5 where +smtpd_tls_ccert_verifydepth was ignored. When you configure trust in a root CA, +it is not necessary to explicitly trust intermediary CAs signed by the root CA, +unless $smtpd_tls_ccert_verifydepth is less than the number of CAs in the +certificate chain for the clients of interest. With a verify depth of 1 you can +only verify certificates directly signed by a trusted CA, and all trusted +intermediary CAs need to be configured explicitly. With a verify depth of 2 you +can verify clients signed by a root CA or a direct intermediary CA (so long as +the client is correctly configured to supply its intermediate CA certificate). + +Example: + + /etc/postfix/main.cf: + smtpd_tls_ccert_verifydepth = 2 + +SSuuppppoorrttiinngg AAUUTTHH oovveerr TTLLSS oonnllyy + +Sending AUTH data over an unencrypted channel poses a security risk. When TLS +layer encryption is required ("smtpd_tls_security_level = encrypt"), the +Postfix SMTP server will announce and accept AUTH only after the TLS layer has +been activated with STARTTLS. When TLS layer encryption is optional +("smtpd_tls_security_level = may"), it may however still be useful to only +offer AUTH when TLS is active. To maintain compatibility with non-TLS clients, +the default is to accept AUTH without encryption. In order to change this +behavior, set "smtpd_tls_auth_only = yes". + +Example: + + /etc/postfix/main.cf: + smtpd_tls_auth_only = no + +SSeerrvveerr--ssiiddee TTLLSS sseessssiioonn ccaacchhee + +The Postfix SMTP server and the remote SMTP client negotiate a session, which +takes some computer time and network bandwidth. SSL protocol versions other +than SSLv2 support resumption of cached sessions. Not only is this more CPU and +bandwidth efficient, it also reduces latency as only one network round-trip is +used to resume a session while it takes two round-trips to create a session +from scratch. + +Since Postfix uses multiple smtpd(8) service processes, an in-memory cache is +not sufficient for session re-use. Clients store at most one cached session per +server and are very unlikely to repeatedly connect to the same server process. +Thus session caching in the Postfix SMTP server generally requires a shared +cache (an alternative available with Postfix >= 2.11 is described below). + +To share the session information between multiple smtpd(8) processes, a session +cache database is used. You can specify any database type that can store +objects of several kbytes and that supports the sequence operator. DBM +databases are not suitable because they can only store small objects. The cache +is maintained by the tlsmgr(8) process, so there is no problem with concurrent +access. Session caching is highly recommended, because the cost of repeatedly +negotiating TLS session keys is high. + +Starting with Postfix 2.11, linked with a compatible OpenSSL library (at least +0.9.8h, preferably 1.0.0 or later) the Postfix SMTP server supports RFC 5077 +TLS session resumption without server-side state when the remote SMTP client +also supports RFC 5077. The session is encrypted by the server in a session +ticket returned to client for storage. When a client sends a valid session +ticket, the server decrypts it and resumes the session, provided neither the +ticket nor the session have expired. This makes it possible to resume cached +sessions without allocating space for a shared database on the server. +Consequently, for Postfix >= 2.11 the smtpd_tls_session_cache_database +parameter should generally be left empty. Session caching can be disabled by +setting the session cache timeout to zero, otherwise the timeout must be at +least 2 minutes and at most 100 days. + +Note, session tickets can only be negotiated if the client disables SSLv2 and +does not use the legacy SSLv2 compatible HELLO message. This is true by default +with the Postfix >= 2.6 SMTP client. + +Example: + + /etc/postfix/main.cf: + smtpd_tls_session_cache_database = btree:/var/lib/postfix/smtpd_scache + +Note: as of version 2.5, Postfix no longer uses root privileges when opening +this file. The file should now be stored under the Postfix-owned +data_directory. As a migration aid, an attempt to open the file under a non- +Postfix directory is redirected to the Postfix-owned data_directory, and a +warning is logged. + +Cached Postfix SMTP server session information expires after a certain amount +of time. Postfix/TLS does not use the OpenSSL default of 300s, but a longer +time of 3600sec (=1 hour). RFC 2246 recommends a maximum of 24 hours. + +Example: + + /etc/postfix/main.cf: + smtpd_tls_session_cache_timeout = 3600s + +As of Postfix 2.11 this setting cannot exceed 100 days. If set <= 0, session +caching is disabled. If set to a positive value less than 2 minutes, the +minimum value of 2 minutes is used instead. + +When the Postfix SMTP server does not save TLS sessions to an external cache +database, client-side session caching is unlikely to be useful. To reduce waste +of client resources, the Postfix SMTP server can be configured to not issue TLS +session ids. By default the Postfix SMTP server always issues TLS session ids. +This works around known interoperability issues with some MUAs, and prevents +possible interoperability issues with other MTAs. + +Example: + + smtpd_tls_always_issue_session_ids = no + +SSeerrvveerr aacccceessss ccoonnttrrooll + +Postfix TLS support introduces three additional features for Postfix SMTP +server access control: + + permit_tls_clientcerts + Allow the remote SMTP client request if the client certificate + fingerprint or certificate public key fingerprint (Postfix 2.9 and + later) is listed in the client certificate table (see relay_clientcerts + discussion below). + + permit_tls_all_clientcerts + Allow the remote SMTP client request if the client certificate passes + trust chain verification. Useful with private-label CAs that only issue + certificates to trusted clients (and not otherwise). + + check_ccert_access type:table + Use the remote SMTP client certificate fingerprint or public key + fingerprint (Postfix 2.9 and later) as the lookup key for the specified + access(5) table. + +The digest algorithm used to compute the client certificate fingerprints is +specified with the main.cf smtpd_tls_fingerprint_digest parameter. The default +is "md5", for compatibility with Postfix versions < 2.5. + +The permit_tls_all_clientcerts feature must be used with caution, because it +can result in too many access permissions. Use this feature only if a special +CA issues the client certificates, and only if this CA is listed as trusted CA. +If other CAs are trusted, any owner of a valid client certificate would be +authorized. The permit_tls_all_clientcerts feature can be practical for a +specially created email relay server. + +It is however recommended to stay with the permit_tls_clientcerts feature and +list all certificates via $relay_clientcerts, as permit_tls_all_clientcerts +does not permit any control when a certificate must no longer be used (e.g. an +employee leaving). + +Example: + + # With Postfix 2.10 and later, the mail relay policy is + # preferably specified under smtpd_relay_restrictions. + /etc/postfix/main.cf: + smtpd_relay_restrictions = + permit_mynetworks + permit_tls_clientcerts + reject_unauth_destination + + # Older configurations combine relay control and spam control under + # smtpd_recipient_restrictions. To use this example with Postfix >= + # 2.10 specify "smtpd_relay_restrictions=". + /etc/postfix/main.cf: + smtpd_recipient_restrictions = + permit_mynetworks + permit_tls_clientcerts + reject_unauth_destination + ...other rules... + +Example: Postfix lookup tables are in the form of (key, value) pairs. Since we +only need the key, the value can be chosen freely, e.g. the name of the user or +host: + + /etc/postfix/main.cf: + relay_clientcerts = hash:/etc/postfix/relay_clientcerts + + /etc/postfix/relay_clientcerts: + D7:04:2F:A7:0B:8C:A5:21:FA:31:77:E1:41:8A:EE:80 lutzpc.at.home + +To extract the public key fingerprint from an X.509 certificate, you need to +extract the public key from the certificate and compute the appropriate digest +of its DER (ASN.1) encoding. With OpenSSL the "-pubkey" option of the "x509" +command extracts the public key always in "PEM" format. We pipe the result to +another OpenSSL command that converts the key to DER and then to the "dgst" +command to compute the fingerprint. + +The actual command to transform the key to DER format depends on the version of +OpenSSL used. With OpenSSL 1.0.0 and later, the "pkey" command supports all key +types. With OpenSSL 0.9.8 and earlier, the key type is always RSA (nobody uses +DSA, and EC keys are not fully supported by 0.9.8), so the "rsa" command is +used. + + # OpenSSL 1.0 with all certificates and SHA-1 fingerprints. + $ openssl x509 -in cert.pem -noout -pubkey | + openssl pkey -pubin -outform DER | + openssl dgst -sha1 -c + (stdin)= 64:3f:1f:f6:e5:1e:d4:2a:56:8b:fc:09:1a:61:98:b5:bc:7c:60:58 + + # OpenSSL 0.9.8 with RSA certificates and MD5 fingerprints. + $ openssl x509 -in cert.pem -noout -pubkey | + openssl rsa -pubin -outform DER | + openssl dgst -md5 -c + (stdin)= f4:62:60:f6:12:8f:d5:8d:28:4d:13:a7:db:b2:ff:50 + +Note: Postfix 2.9.0-2.9.5 computed the public key fingerprint incorrectly. To +use public-key fingerprints, upgrade to Postfix 2.9.6 or later. + +SSeerrvveerr--ssiiddee cciipphheerr ccoonnttrroollss + +The Postfix SMTP server supports 5 distinct cipher grades as specified by the +smtpd_tls_mandatory_ciphers configuration parameter, which determines the +minimum cipher grade with mandatory TLS encryption. The default minimum cipher +grade for mandatory TLS is "medium" which is essentially 128-bit encryption or +better. The smtpd_tls_ciphers parameter (Postfix >= 2.6) controls the minimum +cipher grade used with opportunistic TLS. Here, the default minimum cipher +grade is "medium" for Postfix releases after the middle of 2015, "export" for +older Postfix releases. With Postfix < 2.6, the minimum opportunistic TLS +cipher grade is always "export". + +By default anonymous ciphers are enabled. They are automatically disabled when +remote SMTP client certificates are requested. If clients are expected to +always verify the Postfix SMTP server certificate you may want to disable +anonymous ciphers by setting "smtpd_tls_mandatory_exclude_ciphers = aNULL" or +"smtpd_tls_exclude_ciphers = aNULL", as appropriate. One can't force a remote +SMTP client to check the server certificate, so excluding anonymous ciphers is +generally unnecessary. + +With mandatory and opportunistic TLS encryption, the Postfix SMTP server by +default disables SSLv2 and SSLv3 with Postfix releases after the middle of +2015; older releases only disable SSLv2 for mandatory TLS. The mandatory TLS +protocol list is specified via the smtpd_tls_mandatory_protocols configuration +parameter. The smtpd_tls_protocols parameter (Postfix >= 2.6) controls the SSL/ +TLS protocols used with opportunistic TLS. + +Note that the OpenSSL library only supports protocol exclusion (not inclusion). +For this reason, Postfix can exclude only protocols that are known at the time +the Postfix software is written. If new protocols are added to the OpenSSL +library, they cannot be excluded without corresponding changes to the Postfix +source code. + +For a server that is not a public Internet MX host, Postfix supports +configurations with no server certificates that use oonnllyy the anonymous ciphers. +This is enabled by explicitly setting "smtpd_tls_cert_file = none" and not +specifying an smtpd_tls_dcert_file or smtpd_tls_eccert_file. Such +configurations may not interoperate with some clients, and require that TLSv1.3 +be explicitly disabled. Therefore, they are not recommended, it is better and +simpler to just configure a suitable certificate. + +Example, MSA that requires TLSv1 or higher, not SSLv2 or SSLv3, with high grade +ciphers: + + /etc/postfix/main.cf: + smtpd_tls_cert_file = /etc/postfix/cert.pem + smtpd_tls_key_file = /etc/postfix/key.pem + smtpd_tls_mandatory_ciphers = high + smtpd_tls_mandatory_exclude_ciphers = aNULL, MD5 + smtpd_tls_security_level = encrypt + # Preferred syntax with Postfix >= 2.5: + smtpd_tls_mandatory_protocols = !SSLv2, !SSLv3 + # Legacy syntax: + smtpd_tls_mandatory_protocols = TLSv1 + +With Postfix >= 3.4, specify instead a single file that holds the key followed +by the corresponding certificate and any associated issuing certificates, +leaving the "smtpd_tls_cert_file" and "smtpd_tls_key_file" and related DSA and +ECDSA parameters empty. + + /etc/postfix/main.cf: + smtpd_tls_chain_files = /etc/postfix/rsachain.pem + smtpd_tls_cert_file = + smtpd_tls_key_file = + ... + +If you want to take maximal advantage of ciphers that offer forward secrecy see +the Getting started section of FORWARD_SECRECY_README. The full document +conveniently presents all information about Postfix forward secrecy support in +one place: what forward secrecy is, how to tweak settings, and what you can +expect to see when Postfix uses ciphers with forward secrecy. + +Postfix 2.8 and later, in combination with OpenSSL 0.9.7 and later allows TLS +servers to preempt the TLS client's cipher-suite preference list. This is +possible only with SSLv3 and later, as in SSLv2 the client chooses the cipher- +suite from a list supplied by the server. + +By default, the OpenSSL server selects the client's most preferred cipher-suite +that the server supports. With SSLv3 and later, the server may choose its own +most preferred cipher-suite that is supported (offered) by the client. Setting +"tls_preempt_cipherlist = yes" enables server cipher-suite preferences. The +default OpenSSL behavior applies with "tls_preempt_cipherlist = no". + +While server cipher-suite selection may in some cases lead to a more secure or +performant cipher-suite choice, there is some risk of interoperability issues. +In the past, some SSL clients have listed lower priority ciphers that they did +not implement correctly. If the server chooses a cipher that the client prefers +less, it may select a cipher whose client implementation is flawed. Most +notably Windows 2003 Microsoft Exchange servers have flawed implementations of +DES-CBC3-SHA, which OpenSSL considers stronger than RC4-SHA. Enabling server +cipher-suite selection may create interoperability issues with Windows 2003 +Microsoft Exchange clients. + +MMiisscceellllaanneeoouuss sseerrvveerr ccoonnttrroollss + +The smtpd_starttls_timeout parameter limits the time of Postfix SMTP server +write and read operations during TLS startup and shutdown handshake procedures. + +Example: + + /etc/postfix/main.cf: + smtpd_starttls_timeout = 300s + +With Postfix 2.8 and later, the tls_disable_workarounds parameter specifies a +list or bit-mask of default-enabled OpenSSL bug work-arounds to disable. This +may be necessary if one of the work-arounds enabled by default in OpenSSL +proves to pose a security risk, or introduces an unexpected interoperability +issue. The list of enabled bug work-arounds is OpenSSL-release-specific. See +the tls_disable_workarounds parameter documentation for the list of supported +values. + +Example: + + /etc/postfix/main.cf: + tls_disable_workarounds = 0xFFFFFFFF + tls_disable_workarounds = CVE-2010-4180 + +With Postfix >= 2.11, the tls_ssl_options parameter specifies a list or bit- +mask of OpenSSL options to enable. Specify one or more of the named options +below, or a hexadecimal bitmask of options found in the ssl.h file +corresponding to the run-time OpenSSL library. While it may be reasonable to +turn off all bug workarounds (see above), it is not a good idea to attempt to +turn on all features. See the tls_ssl_options parameter documentation for the +list of supported values. + +Example: + + /etc/postfix/main.cf: + tls_ssl_options = no_ticket, no_compression + +You should only enable features via the hexadecimal mask when the need to +control the feature is critical (to deal with a new vulnerability or a serious +interoperability problem). Postfix DOES NOT promise backwards compatible +behavior with respect to the mask bits. A feature enabled via the mask in one +release may be enabled by other means in a later release, and the mask bit will +then be ignored. Therefore, use of the hexadecimal mask is only a temporary +measure until a new Postfix or OpenSSL release provides a better solution. + +SSMMTTPP CClliieenntt ssppeecciiffiicc sseettttiinnggss + +Topics covered in this section: + + * Configuring TLS in the SMTP/LMTP client + * Client-side TLS activity logging + * Client-side certificate and private key configuration + * Client-side TLS connection reuse + * Client-side TLS session cache + * Client TLS limitations + * Per-destination TLS policy + * Discovering servers that support TLS + * Server certificate verification depth + * Client-side cipher controls + * Client-side SMTPS support + * Miscellaneous client controls + +CCoonnffiigguurriinngg TTLLSS iinn tthhee SSMMTTPP//LLMMTTPP cclliieenntt + +Similar to the Postfix SMTP server, the Postfix SMTP/LMTP client implements +multiple TLS security levels. These levels are described in more detail in the +sections that follow. + +nnoonnee + No TLS. +mmaayy + Opportunistic TLS. +eennccrryypptt + Mandatory TLS encryption. +ddaannee + Opportunistic DANE TLS. +ddaannee--oonnllyy + Mandatory DANE TLS. +ffiinnggeerrpprriinntt + Certificate fingerprint verification. +vveerriiffyy + Mandatory server certificate verification. +sseeccuurree + Secure-channel TLS. + +TTLLSS ssuuppppoorrtt iinn tthhee LLMMTTPP ddeelliivveerryy aaggeenntt + +The smtp(8) and lmtp(8) delivery agents are implemented by a single dual- +purpose program. Specifically, all the TLS features described below apply +equally to SMTP and LMTP, after replacing the "smtp_" prefix of the each +parameter name with "lmtp_". + +The Postfix LMTP delivery agent can communicate with LMTP servers listening on +UNIX-domain sockets. When server certificate verification is enabled and the +server is listening on a UNIX-domain socket, the $myhostname parameter is used +to set the TLS verification nexthop and hostname. + +NOTE: Opportunistic encryption of LMTP traffic over UNIX-domain sockets or +loopback TCP connections is futile. TLS is only useful in this context when it +is mandatory, typically to allow at least one of the server or the client to +authenticate the other. The "null" cipher grade may be appropriate in this +context, when available on both client and server. The "null" ciphers provide +authentication without encryption. + +NNoo TTLLSS eennccrryyppttiioonn + +At the "none" TLS security level, TLS encryption is disabled. This is the +default security level, and can be configured explicitly by setting +"smtp_tls_security_level = none". For LMTP, use the corresponding "lmtp_" +parameter. + +Per-destination settings may override this default setting, in which case TLS +is used selectively, only with destinations explicitly configured for TLS. + +You can disable TLS for a subset of destinations, while leaving it enabled for +the rest. With the Postfix TLS policy table, specify the "none" security level. + +OOppppoorrttuunniissttiicc TTLLSS + +At the "may" TLS security level, TLS encryption is opportunistic. The SMTP +transaction is encrypted if the STARTTLS ESMTP feature is supported by the +server. Otherwise, messages are sent in the clear. Opportunistic TLS can be +configured by setting "smtp_tls_security_level = may". For LMTP, use the +corresponding "lmtp_" parameter. + +The "smtp_tls_ciphers" and "smtp_tls_protocols" configuration parameters +(Postfix >= 2.6) provide control over the cipher grade and protocols used with +opportunistic TLS. With earlier Postfix releases, opportunistic TLS always uses +the cipher grade "export" and enables all protocols. + +With opportunistic TLS, mail delivery continues even if the server certificate +is untrusted or bears the wrong name. When the TLS handshake fails for an +opportunistic TLS session, rather than give up on mail delivery, the Postfix +SMTP client retries the transaction with TLS disabled. Trying an unencrypted +connection makes it possible to deliver mail to sites with non-interoperable +server TLS implementations. + +Opportunistic encryption is never used for LMTP over UNIX-domain sockets. The +communications channel is already confidential without TLS, so the only +potential benefit of TLS is authentication. Do not configure opportunistic TLS +for LMTP deliveries over UNIX-domain sockets. Only configure TLS for LMTP over +UNIX-domain sockets at the encrypt security level or higher. Attempts to +configure opportunistic encryption of LMTP sessions will be ignored with a +warning written to the mail logs. + +You can enable opportunistic TLS just for selected destinations. With the +Postfix TLS policy table, specify the "may" security level. + +This is the most common security level for TLS protected SMTP sessions, +stronger security is not generally available and, if needed, is typically only +configured on a per-destination basis. See the section on TLS limitations +above. + +Example: + + /etc/postfix/main.cf: + smtp_tls_security_level = may + +MMaannddaattoorryy TTLLSS eennccrryyppttiioonn + +At the "encrypt" TLS security level, messages are sent only over TLS encrypted +sessions. The SMTP transaction is aborted unless the STARTTLS ESMTP feature is +supported by the remote SMTP server. If no suitable servers are found, the +message will be deferred. Mandatory TLS encryption can be configured by setting +"smtp_tls_security_level = encrypt". Even though TLS encryption is always used, +mail delivery continues even if the server certificate is untrusted or bears +the wrong name. For LMTP, use the corresponding "lmtp_" parameter. + +At this security level and higher, the smtp_tls_mandatory_protocols and +smtp_tls_mandatory_ciphers configuration parameters determine the list of +sufficiently secure SSL protocol versions and the minimum cipher strength. If +the protocol or cipher requirements are not met, the mail transaction is +aborted. The documentation for these parameters includes useful +interoperability and security guidelines. + +Despite the potential for eliminating passive eavesdropping attacks, mandatory +TLS encryption is not viable as a default security level for mail delivery to +the public Internet. Some MX hosts do not support TLS at all, and some of those +that do have broken implementations. On a host that delivers mail to the +Internet, you should not configure mandatory TLS encryption as the default +security level. + +You can enable mandatory TLS encryption just for specific destinations. With +the Postfix TLS policy table, specify the "encrypt" security level. + +Examples: + +In the example below, traffic to example.com and its sub-domains via the +corresponding MX hosts always uses TLS. The SSLv2 protocol will be disabled +(the default setting of smtp_tls_mandatory_protocols excludes SSLv2+3). Only +high- or medium-strength (i.e. 128 bit or better) ciphers will be used by +default for all "encrypt" security level sessions. + + /etc/postfix/main.cf: + smtp_tls_policy_maps = hash:/etc/postfix/tls_policy + + /etc/postfix/tls_policy: + example.com encrypt + .example.com encrypt + +In the next example, secure message submission is configured via the MSA " +[example.net]:587". TLS sessions are encrypted without authentication, because +this MSA does not possess an acceptable certificate. This MSA is known to be +capable of "TLSv1" and "high" grade ciphers, so these are selected via the +policy table. + +NNoottee:: the policy table lookup key is the verbatim next-hop specification from +the recipient domain, transport(5) table or relayhost parameter, with any +enclosing square brackets and optional port. Take care to be consistent: the +suffixes ":smtp" or ":25" or no port suffix result in different policy table +lookup keys, even though they are functionally equivalent nexthop +specifications. Use at most one of these forms for all destinations. Below, the +policy table has multiple keys, just in case the transport table entries are +not specified consistently. + + /etc/postfix/main.cf: + smtp_tls_policy_maps = hash:/etc/postfix/tls_policy + + /etc/services: + submission 587/tcp msa # mail message + submission + + /etc/postfix/tls_policy: + [example.net]:587 encrypt protocols=TLSv1 ciphers=high + [example.net]:msa encrypt protocols=TLSv1 ciphers=high + [example.net]:submission encrypt protocols=TLSv1 ciphers=high + +DDAANNEE TTLLSS aauutthheennttiiccaattiioonn.. + +The Postfix SMTP client supports two TLS security levels based on DANE TLSA +(RFC 6698, RFC 7671, RFC 7672) records. The opportunistic "dane" level and the +mandatory "dane-only" level. + +The "dane" level is a stronger form of opportunistic TLS that is resistant to +man in the middle and downgrade attacks when the destination domain uses DNSSEC +to publish DANE TLSA records for its MX hosts. If a remote SMTP server has +"usable" (see section 3 of RFC 7672) DANE TLSA records, the server connection +will be authenticated. When DANE authentication fails, there is no fallback to +unauthenticated or plaintext delivery. + +If TLSA records are published for a given remote SMTP server (implying TLS +support), but are all "unusable" due to unsupported parameters or malformed +data, the Postfix SMTP client will use mandatory unauthenticated TLS. +Otherwise, when no TLSA records are published, the Postfix SMTP client behavior +is the same as with may. + +TLSA records must be published in DNSSEC validated DNS zones. Any TLSA records +in DNS zones not protected via DNSSEC are ignored. The Postfix SMTP client will +not look for TLSA records associated with MX hosts whose "A" or "AAAA" records +lie in an "insecure" DNS zone. Such lookups have been observed to cause +interoperability issues with poorly implemented DNS servers, and are in any +case not expected to ever yield "secure" results, since that would require a +very unlikely DLV DNS trust anchor configured between the host record and the +associated "_25._tcp" child TLSA record. + +The "dane-only" level is a form of secure-channel TLS based on the DANE PKI. If +"usable" TLSA records are present these are used to authenticate the remote +SMTP server. Otherwise, or when server certificate verification fails, delivery +via the server in question tempfails. + +At both security levels, the TLS policy for the destination is obtained via +TLSA records validated with DNSSEC. For TLSA policy to be in effect, the +destination domain's containing DNS zone must be signed and the Postfix SMTP +client's operating system must be configured to send its DNS queries to a +recursive DNS nameserver that is able to validate the signed records. Each MX +host's DNS zone needs to also be signed, and needs to publish DANE TLSA (see +section 3 of RFC 7672) records that specify how that MX host's TLS certificate +is to be verified. + +TLSA records do not preempt the normal SMTP MX host selection algorithm, if +some MX hosts support TLSA and others do not, TLS security will vary from +delivery to delivery. It is up to the domain owner to configure their MX hosts +and their DNS sensibly. To configure the Postfix SMTP client for DNSSEC lookups +see the documentation for the smtp_dns_support_level main.cf parameter. The +tls_dane_digests parameter controls the list of supported digests. + +As explained in section 3 of RFC 7672, certificate usages "0" and "1", which +are intended to "constrain" existing Web-PKI trust, are not supported with MTA- +to-MTA SMTP. Rather, TLSA records with usages "0" and "1" are treated as +"unusable". + +The Postfix SMTP client supports only certificate usages "2" and "3". +Experimental support for silently mapping certificate usage "1" to "3" has been +withdrawn starting with Postfix 3.2. + +When usable TLSA records are obtained for the remote SMTP server the Postfix +SMTP client sends the SNI TLS extension in its SSL client hello message. This +may help the remote SMTP server live up to its promise to provide a certificate +that matches its TLSA records. + +For purposes of protocol and cipher selection, the "dane" security level is +treated like a "mandatory" TLS security level, and weak ciphers and protocols +are disabled. Since DANE authenticates server certificates the "aNULL" cipher- +suites are transparently excluded at this level, no need to configure this +manually. RFC 7672 (DANE) TLS authentication is available with Postfix 2.11 and +later. + +When a DANE TLSA record specifies a trust-anchor (TA) certificate (that is an +issuing CA), the strategy used to verify the peername of the server certificate +is unconditionally "nexthop, hostname". Both the nexthop domain and the +hostname obtained from the DNSSEC-validated MX lookup are safe from forgery and +the server certificate must contain at least one of these names. + +When a DANE TLSA record specifies an end-entity (EE) certificate, (that is the +actual server certificate), as with the fingerprint security level below, no +name checks or certificate expiration checks are applied. The server +certificate (or its public key) either matches the DANE record or not. Server +administrators should publish such EE records in preference to all other types. + +The pre-requisites for DANE support in the Postfix SMTP client are: + + * A compile-time OpenSSL library that supports the TLS SNI extension and + "SHA-2" message digests. + * A compile-time DNS resolver library that supports DNSSEC. Postfix binaries + built on an older system will not support DNSSEC even if deployed on a + system with an updated resolver library. + * The "smtp_dns_support_level" must be set to "dnssec". + * The "smtp_host_lookup" parameter must include "dns". + * A DNSSEC-validating recursive resolver (see note below). + +The above client pre-requisites do not apply to the Postfix SMTP server. It +will support DANE provided it supports TLSv1 and its TLSA records are published +in a DNSSEC signed zone. To receive DANE secured mail for multiple domains, use +the same hostname to add the server to each domain's MX records. There are no +plans to implement SNI in the Postfix SMTP server. + +Note: The Postfix SMTP client's internal stub DNS resolver is DNSSEC-aware, but +it does not itself validate DNSSEC records, rather it delegates DNSSEC +validation to the operating system's configured recursive DNS nameserver. The +Postfix DNS client relies on a secure channel to the resolver's cache for +DNSSEC integrity, but does not support TSIG to protect the transmission channel +between itself and the nameserver. Therefore, it is strongly recommended (DANE +security guarantee void otherwise) that each MTA run a local DNSSEC-validating +recursive resolver ("unbound" from nlnetlabs.nl is a reasonable choice) +listening on the loopback interface, and that the system be configured to use +only this local nameserver. The local nameserver may forward queries to an +upstream recursive resolver on another host if desired. + +Note: When the operating system's recursive nameserver is not local, enabling +EDNS0 expanded DNS packet sizes and turning on the DNSSEC "DO" bit in the DNS +request and/or the new DNSSEC-specific records returned in the nameserver's +replies may cause problems with older or buggy firewall and DNS server +implementations. Therefore, Postfix does not enable DNSSEC by default. Since MX +lookups happen before the security level is determined, DANE support is +disabled for all destinations unless you set "smtp_dns_support_level = dnssec". +To enable DNSSEC lookups selectively, define a new dedicated transport with a +"-o smtp_dns_support_level=dnssec" override in master.cf and route selected +domains to that transport. If DNSSEC proves to be sufficiently reliable for +these domains, you can enable it for all destinations by changing the global +smtp_dns_support_level in main.cf. + +EExxaammppllee: "dane" security for selected destinations, with opportunistic TLS by +default. This is the recommended configuration for early adopters. + + * The "example.com" destination uses DANE, but if TLSA records are not + present or are unusable, mail is deferred. + + * The "example.org" destination uses DANE if possible, but if no TLSA records + are found opportunistic TLS is used. + + main.cf: + indexed = ${default_database_type}:${config_directory}/ + # + # default: Opportunistic TLS with no DNSSEC lookups. + # + smtp_tls_security_level = may + smtp_dns_support_level = enabled + # + # Per-destination TLS policy + # + smtp_tls_policy_maps = ${indexed}tls_policy + # + # default_transport = smtp, but some destinations are special: + # + transport_maps = ${indexed}transport + + transport: + example.com dane + example.org dane + + tls_policy: + example.com dane-only + + master.cf: + dane unix - - n - - smtp + -o smtp_dns_support_level=dnssec + -o smtp_tls_security_level=dane + +CCeerrttiiffiiccaattee ffiinnggeerrpprriinntt vveerriiffiiccaattiioonn + +At the fingerprint security level, no trusted Certification Authorities are +used or required. The certificate trust chain, expiration date, etc., are not +checked. Instead, the smtp_tls_fingerprint_cert_match parameter or the "match" +attribute in the policy table lists the remote SMTP server certificate +fingerprint or public key fingerprint. Certificate fingerprint verification is +available with Postfix 2.5 and later, public-key fingerprint support is +available with Postfix 2.9 and later. + +If certificate fingerprints are exchanged securely, this is the strongest, and +least scalable security level. The administrator needs to securely collect the +fingerprints of the X.509 certificates of each peer server, store them into a +local file, and update this local file whenever the peer server's public +certificate changes. If public key fingerprints are used in place of +fingerprints of the entire certificate, the fingerprints remain valid even +after the certificate is renewed, pprroovviiddeedd that the same public/private keys +are used to obtain the new certificate. + +Fingerprint verification may be feasible for an SMTP "VPN" connecting a small +number of branch offices over the Internet, or for secure connections to a +central mail hub. It works poorly if the remote SMTP server is managed by a +third party, and its public certificate changes periodically without prior +coordination with the verifying site. + +The digest algorithm used to calculate the fingerprint is selected by the +ssmmttpp__ttllss__ffiinnggeerrpprriinntt__ddiiggeesstt parameter. In the policy table multiple +fingerprints can be combined with a "|" delimiter in a single match attribute, +or multiple match attributes can be employed. The ":" character is not used as +a delimiter as it occurs between each pair of fingerprint (hexadecimal) digits. + +Example: fingerprint TLS security with an internal mailhub. Two matching +fingerprints are listed. The relayhost may be multiple physical hosts behind a +load-balancer, each with its own private/public key and self-signed +certificate. Alternatively, a single relayhost may be in the process of +switching from one set of private/public keys to another, and both keys are +trusted just prior to the transition. + + relayhost = [mailhub.example.com] + smtp_tls_security_level = fingerprint + smtp_tls_fingerprint_digest = md5 + smtp_tls_fingerprint_cert_match = + 3D:95:34:51:24:66:33:B9:D2:40:99:C0:C1:17:0B:D1 + EC:3B:2D:B0:5B:B1:FB:6D:20:A3:9D:72:F6:8D:12:35 + +Example: Certificate fingerprint verification with selected destinations. As in +the example above, we show two matching fingerprints: + + /etc/postfix/main.cf: + smtp_tls_policy_maps = hash:/etc/postfix/tls_policy + smtp_tls_fingerprint_digest = md5 + + /etc/postfix/tls_policy: + example.com fingerprint + match=3D:95:34:51:24:66:33:B9:D2:40:99:C0:C1:17:0B:D1 + match=EC:3B:2D:B0:5B:B1:FB:6D:20:A3:9D:72:F6:8D:12:35 + +To extract the public key fingerprint from an X.509 certificate, you need to +extract the public key from the certificate and compute the appropriate digest +of its DER (ASN.1) encoding. With OpenSSL the "-pubkey" option of the "x509" +command extracts the public key always in "PEM" format. We pipe the result to +another OpenSSL command that converts the key to DER and then to the "dgst" +command to compute the fingerprint. + +The actual command to transform the key to DER format depends on the version of +OpenSSL used. With OpenSSL 1.0.0 and later, the "pkey" command supports all key +types. With OpenSSL 0.9.8 and earlier, the key type is always RSA (nobody uses +DSA, and EC keys are not fully supported by 0.9.8), so the "rsa" command is +used. + + # OpenSSL 1.0 with all certificates and SHA-1 fingerprints. + $ openssl x509 -in cert.pem -noout -pubkey | + openssl pkey -pubin -outform DER | + openssl dgst -sha1 -c + (stdin)= 64:3f:1f:f6:e5:1e:d4:2a:56:8b:fc:09:1a:61:98:b5:bc:7c:60:58 + + # OpenSSL 0.9.8 with RSA certificates and MD5 fingerprints. + $ openssl x509 -in cert.pem -noout -pubkey | + openssl rsa -pubin -outform DER | + openssl dgst -md5 -c + (stdin)= f4:62:60:f6:12:8f:d5:8d:28:4d:13:a7:db:b2:ff:50 + +Note: Postfix 2.9.0-2.9.5 computed the public key fingerprint incorrectly. To +use public-key fingerprints, upgrade to Postfix 2.9.6 or later. + +MMaannddaattoorryy sseerrvveerr cceerrttiiffiiccaattee vveerriiffiiccaattiioonn + +At the verify TLS security level, messages are sent only over TLS encrypted +sessions if the remote SMTP server certificate is valid (not expired or +revoked, and signed by a trusted Certification Authority) and where the server +certificate name matches a known pattern. Mandatory server certificate +verification can be configured by setting "smtp_tls_security_level = verify". +The smtp_tls_verify_cert_match parameter can override the default "hostname" +certificate name matching strategy. Fine-tuning the matching strategy is +generally only appropriate for secure-channel destinations. For LMTP use the +corresponding "lmtp_" parameters. + +If the server certificate chain is trusted (see smtp_tls_CAfile and +smtp_tls_CApath), any DNS names in the SubjectAlternativeName certificate +extension are used to verify the remote SMTP server name. If no DNS names are +specified, the certificate CommonName is checked. If you want mandatory +encryption without server certificate verification, see above. + +With Postfix >= 2.11 the "smtp_tls_trust_anchor_file" parameter or more +typically the corresponding per-destination "tafile" attribute optionally +modifies trust chain verification. If the parameter is not empty the root CAs +in CAfile and CApath are no longer trusted. Rather, the Postfix SMTP client +will only trust certificate-chains signed by one of the trust-anchors contained +in the chosen files. The specified trust-anchor certificates and public keys +are not subject to expiration, and need not be (self-signed) root CAs. They +may, if desired, be intermediate certificates. Therefore, these certificates +also may be found "in the middle" of the trust chain presented by the remote +SMTP server, and any untrusted issuing parent certificates will be ignored. + +Despite the potential for eliminating "man-in-the-middle" and other attacks, +mandatory certificate trust chain and subject name verification is not viable +as a default Internet mail delivery policy. Some MX hosts do not support TLS at +all, and a significant portion of TLS-enabled MTAs use self-signed +certificates, or certificates that are signed by a private Certification +Authority. On a machine that delivers mail to the Internet, you should not +configure mandatory server certificate verification as a default policy. + +Mandatory server certificate verification as a default security level may be +appropriate if you know that you will only connect to servers that support RFC +2487 and that present verifiable server certificates. An example would be a +client that sends all email to a central mailhub that offers the necessary +STARTTLS support. In such cases, you can often use a secure-channel +configuration instead. + +You can enable mandatory server certificate verification just for specific +destinations. With the Postfix TLS policy table, specify the "verify" security +level. + +Example: + +In this example, the Postfix SMTP client encrypts all traffic to the +example.com domain. The peer hostname is verified, but verification is +vulnerable to DNS response forgery. Mail transmission to example.com recipients +uses "high" grade ciphers. + + /etc/postfix/main.cf: + indexed = ${default_database_type}:${config_directory}/ + smtp_tls_CAfile = ${config_directory}/CAfile.pem + smtp_tls_policy_maps = ${indexed}tls_policy + + /etc/postfix/tls_policy: + example.com verify ciphers=high + +SSeeccuurree sseerrvveerr cceerrttiiffiiccaattee vveerriiffiiccaattiioonn + +At the secure TLS security level, messages are sent only over secure-channel +TLS sessions where DNS forgery resistant server certificate verification +succeeds. If no suitable servers are found, the message will be deferred. +Postfix secure-channels can be configured by setting "smtp_tls_security_level = +secure". The smtp_tls_secure_cert_match parameter can override the default +"nexthop, dot-nexthop" certificate match strategy. For LMTP, use the +corresponding "lmtp_" parameters. + +If the server certificate chain is trusted (see smtp_tls_CAfile and +smtp_tls_CApath), any DNS names in the SubjectAlternativeName certificate +extension are used to verify the remote SMTP server name. If no DNS names are +specified, the CommonName is checked. If you want mandatory encryption without +server certificate verification, see above. + +With Postfix >= 2.11 the "smtp_tls_trust_anchor_file" parameter or more +typically the corresponding per-destination "tafile" attribute optionally +modifies trust chain verification. If the parameter is not empty the root CAs +in CAfile and CApath are no longer trusted. Rather, the Postfix SMTP client +will only trust certificate-chains signed by one of the trust-anchors contained +in the chosen files. The specified trust-anchor certificates and public keys +are not subject to expiration, and need not be (self-signed) root CAs. They +may, if desired, be intermediate certificates. Therefore, these certificates +also may be found "in the middle" of the trust chain presented by the remote +SMTP server, and any untrusted issuing parent certificates will be ignored. + +Despite the potential for eliminating "man-in-the-middle" and other attacks, +mandatory secure server certificate verification is not viable as a default +Internet mail delivery policy. Some MX hosts do not support TLS at all, and a +significant portion of TLS-enabled MTAs use self-signed certificates, or +certificates that are signed by a private Certification Authority. On a machine +that delivers mail to the Internet, you should not configure secure TLS +verification as a default policy. + +Mandatory secure server certificate verification as a default security level +may be appropriate if you know that you will only connect to servers that +support RFC 2487 and that present verifiable server certificates. An example +would be a client that sends all email to a central mailhub that offers the +necessary STARTTLS support. + +You can enable secure TLS verification just for specific destinations. With the +Postfix TLS policy table, specify the "secure" security level. + +Examples: + + * Secure-channel TLS without transport(5) table overrides: + + The Postfix SMTP client will encrypt all traffic and verify the destination + name immune from forged DNS responses. MX lookups are still used to find + the hostnames of the SMTP servers for example.com, but these hostnames are + not used when checking the names in the server certificate(s). Rather, the + requirement is that the MX hosts for example.com have trusted certificates + with a subject name of example.com or a sub-domain, see the documentation + for the smtp_tls_secure_cert_match parameter. + + The related domains example.co.uk and example.co.jp are hosted on the same + MX hosts as the primary example.com domain, and traffic to these is secured + by verifying the primary example.com domain in the server certificates. + This frees the server administrator from needing the CA to sign + certificates that list all the secondary domains. The downside is that + clients that want secure channels to the secondary domains need explicit + TLS policy table entries. + + Note, there are two ways to handle related domains. The first is to use the + default routing for each domain, but add policy table entries to override + the expected certificate subject name. The second is to override the next- + hop in the transport table, and use a single policy table entry for the + common nexthop. We choose the first approach, because it works better when + domain ownership changes. With the second approach we securely deliver mail + to the wrong destination, with the first approach, authentication fails and + mail stays in the local queue, the first approach is more appropriate in + most cases. + + /etc/postfix/main.cf: + smtp_tls_CAfile = /etc/postfix/CAfile.pem + smtp_tls_policy_maps = hash:/etc/postfix/tls_policy + + /etc/postfix/transport: + + /etc/postfix/tls_policy: + example.com secure + example.co.uk secure match=example.com:.example.com + example.co.jp secure match=example.com:.example.com + + * Secure-channel TLS with transport(5) table overrides: + + In this case traffic to example.com and its related domains is sent to a + single logical gateway (to avoid a single point of failure, its name may + resolve to one or more load-balancer addresses, or to the combined + addresses of multiple physical hosts). All the physical hosts reachable via + the gateway's IP addresses have the logical gateway name listed in their + certificates. + + /etc/postfix/main.cf: + smtp_tls_CAfile = /etc/postfix/CAfile.pem + transport_maps = hash:/etc/postfix/transport + smtp_tls_policy_maps = hash:/etc/postfix/tls_policy + + /etc/postfix/transport: + example.com smtp:[tls.example.com] + example.co.uk smtp:[tls.example.com] + example.co.jp smtp:[tls.example.com] + + /etc/postfix/tls_policy: + [tls.example.com] secure match=tls.example.com + +CClliieenntt--ssiiddee TTLLSS aaccttiivviittyy llooggggiinngg + +To get additional information about Postfix SMTP client TLS activity you can +increase the loglevel from 0..4. Each logging level also includes the +information that is logged at a lower logging level. + + _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ + |LLeevveell|PPoossttffiixx 22..99 aanndd llaatteerr |EEaarrlliieerr rreelleeaasseess.. | + |_ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |0 |Disable logging of TLS activity. | + |_ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |1 |Log only a summary message on TLS |Log the summary message and | + | |handshake completion -- no logging|unconditionally log trust-chain| + | |of remote SMTP server certificate |verification errors. | + | |trust-chain verification errors if| | + | |server certificate verification is| | + | |not required. | | + |_ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |2 |Also log levels during TLS negotiation. | + |_ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |3 |Also log hexadecimal and ASCII dump of TLS negotiation process. | + |_ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |4 |Also log hexadecimal and ASCII dump of complete transmission after| + | |STARTTLS. | + |_ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + +Example: + + /etc/postfix/main.cf: + smtp_tls_loglevel = 0 + +CClliieenntt--ssiiddee cceerrttiiffiiccaattee aanndd pprriivvaattee kkeeyy ccoonnffiigguurraattiioonn + +Do not configure Postfix SMTP client certificates unless you mmuusstt present +client TLS certificates to one or more servers. Client certificates are not +usually needed, and can cause problems in configurations that work well without +them. The recommended setting is to let the defaults stand: + + smtp_tls_cert_file = + smtp_tls_dcert_file = + smtp_tls_key_file = + smtp_tls_dkey_file = + # Postfix >= 2.6 + smtp_tls_eccert_file = + smtp_tls_eckey_file = + # Postfix >= 3.4 + smtp_tls_chain_files = + +The best way to use the default settings is to comment out the above parameters +in main.cf if present. + +During TLS startup negotiation the Postfix SMTP client may present a +certificate to the remote SMTP server. Browsers typically let the user select +among the certificates that match the CA names indicated by the remote SMTP +server. The Postfix SMTP client does not yet have a mechanism to select from +multiple candidate certificates on the fly, and supports a single set of +certificates (at most one per public key algorithm). + +RSA, DSA and ECDSA (Postfix >= 2.6) certificates are supported. You can +configure all three at the same time, in which case the cipher used determines +which certificate is presented. + +It is possible for the Postfix SMTP client to use the same key/certificate pair +as the Postfix SMTP server. If a certificate is to be presented, it must be in +"PEM" format. The private key must not be encrypted, meaning: it must be +accessible without password. Both parts (certificate and private key) may be in +the same file. + +With OpenSSL 1.1.1 and Postfix >= 3.4 it is also possible to configure Ed25519 +and Ed448 certificates. Rather than add two more pairs of key and certificate +parameters, Postfix 3.4 introduces a new "smtp_tls_chain_files" parameter which +specifies all the configured certificates at once, and handles files that hold +both the key and the associated certificates in one pass, thereby avoiding +potential race conditions during key rollover. + +To enable remote SMTP servers to verify the Postfix SMTP client certificate, +the issuing CA certificates must be made available to the server. You should +include the required certificates in the client certificate file, the client +certificate first, then the issuing CA(s) (bottom-up order). + +Example: the certificate for "client.example.com" was issued by "intermediate +CA" which itself has a certificate issued by "root CA". As the "root" super- +user create the client.pem file with: + + # uummaasskk 007777 + # ccaatt cclliieenntt__kkeeyy..ppeemm cclliieenntt__cceerrtt..ppeemm iinntteerrmmeeddiiaattee__CCAA..ppeemm >> cchhaaiinn..ppeemm + +A Postfix SMTP client certificate supplied here must be usable as SSL client +certificate and hence pass the "openssl verify -purpose sslclient ..." test. + +A server that trusts the root CA has a local copy of the root CA certificate, +so it is not necessary to include the root CA certificate here. Leaving it out +of the "chain.pem" file reduces the overhead of the TLS exchange. + +If you want the Postfix SMTP client to accept remote SMTP server certificates +issued by these CAs, append the root certificate to $smtp_tls_CAfile or install +it in the $smtp_tls_CApath directory. + +Example: Postfix >= 3.4 all-in-one chain file(s). One or more chain files that +start with a key that is immediately followed by the corresponding certificate +and any additional issuer certificates. A single file can hold multiple (key, +cert, [chain]) sequences, one per algorithm. It is typically simpler to keep +the chain for each algorithm in its own file. Most users are likely to deploy +at most a single RSA chain, but with OpenSSL 1.1.1, it is possible to deploy up +five chains, one each for RSA, ECDSA, ED25519, ED448 and even the obsolete DSA. + + # Postfix >= 3.4. Preferred configuration interface. Each file + # starts with the private key, followed by the corresponding + # certificate, and any intermediate issuer certificates. + # + smtp_tls_chain_files = + /etc/postfix/rsa.pem, + /etc/postfix/ecdsa.pem, + /etc/postfix/ed25519.pem, + /etc/postfix/ed448.pem + +You can also store the keys separately from their certificates, again provided +each is listed before the corresponding certificate chain. Storing a key and +its associated certificate chain in separate files is not recommended, because +this is prone to race conditions during key rollover, as there is no way to +update multiple files atomically. + + # Postfix >= 3.4. + # Storing keys separately from the associated certificates is not + # recommended. + smtp_tls_chain_files = + /etc/postfix/rsakey.pem, + /etc/postfix/rsacerts.pem, + /etc/postfix/ecdsakey.pem, + /etc/postfix/ecdsacerts.pem + +The below examples show the legacy algorithm-specific configurations for +Postfix 3.3 and older. With Postfix <= 3.3, even if the key is stored in the +same file as the certificate, the file is read twice and a (brief) race +condition still exists during key rollover. While Postfix >= 3.4 avoids the +race when the key and certificate are in the same file, you should use the new +"smtp_tls_chain_files" interface shown above. + +RSA key and certificate examples: + + /etc/postfix/main.cf: + smtp_tls_cert_file = /etc/postfix/client.pem + smtp_tls_key_file = $smtp_tls_cert_file + +Their DSA counterparts: + + /etc/postfix/main.cf: + smtp_tls_dcert_file = /etc/postfix/client-dsa.pem + smtp_tls_dkey_file = $smtp_tls_dcert_file + +Their ECDSA counterparts (Postfix >= 2.6 + OpenSSL >= 1.0.0): + + /etc/postfix/main.cf: + smtp_tls_eccert_file = /etc/postfix/client-ecdsa.pem + smtp_tls_eckey_file = $smtp_tls_eccert_file + +To verify a remote SMTP server certificate, the Postfix SMTP client needs to +trust the certificates of the issuing Certification Authorities. These +certificates in "pem" format can be stored in a single $smtp_tls_CAfile or in +multiple files, one CA per file in the $smtp_tls_CApath directory. If you use a +directory, don't forget to create the necessary "hash" links with: + + # $$OOPPEENNSSSSLL__HHOOMMEE//bbiinn//cc__rreehhaasshh //ppaatthh//ttoo//ddiirreeccttoorryy + +The $smtp_tls_CAfile contains the CA certificates of one or more trusted CAs. +The file is opened (with root privileges) before Postfix enters the optional +chroot jail and so need not be accessible from inside the chroot jail. + +Additional trusted CAs can be specified via the $smtp_tls_CApath directory, in +which case the certificates are read (with $mail_owner privileges) from the +files in the directory when the information is needed. Thus, the +$smtp_tls_CApath directory needs to be accessible inside the optional chroot +jail. + +The choice between $smtp_tls_CAfile and $smtp_tls_CApath is a space/time +tradeoff. If there are many trusted CAs, the cost of preloading them all into +memory may not pay off in reduced access time when the certificate is needed. + +Example: + + /etc/postfix/main.cf: + smtp_tls_CAfile = /etc/postfix/CAcert.pem + smtp_tls_CApath = /etc/postfix/certs + +CClliieenntt--ssiiddee TTLLSS ccoonnnneeccttiioonn rreeuussee + +Historically, the Postfix SMTP client has supported multiple deliveries per +plaintext connection. Postfix 3.4 introduces support for multiple deliveries +per TLS-encrypted connection. Multiple deliveries per connection improve mail +delivery performance, especially for destinations that throttle clients that +don't combine deliveries. + +To enable multiple deliveries per TLS connection, specify: + + /etc/postfix/main.cf: + smtp_tls_connection_reuse = yes + +Alternatively, specify the attribute "connection_reuse=yes" in an +smtp_tls_policy_maps entry. + +The implementation of TLS connection reuse relies on the same scache(8) service +as used for delivering plaintext SMTP mail, the same tlsproxy(8) daemon as used +by the postscreen(8) service, and relies on the same hints from the qmgr(8) +daemon. See "Postfix Connection Cache" for a description of the underlying +connection reuse infrastructure. + +Initial SMTP handshake: + + smtp(8) -> remote SMTP server + +Reused SMTP/TLS connection, or new SMTP/TLS connection: + + smtp(8) -> tlsproxy(8) -> remote SMTP server + +Cached SMTP/TLS connection: + + scache(8) -> tlsproxy(8) -> remote SMTP server + +As of Postfix 3.4, TLS connection reuse is disabled by default. This may change +once the impact on over-all performance is understood. + +CClliieenntt--ssiiddee TTLLSS sseessssiioonn ccaacchhee + +The remote SMTP server and the Postfix SMTP client negotiate a session, which +takes some computer time and network bandwidth. By default, this session +information is cached only in the smtp(8) process actually using this session +and is lost when the process terminates. To share the session information +between multiple smtp(8) processes, a persistent session cache can be used. You +can specify any database type that can store objects of several kbytes and that +supports the sequence operator. DBM databases are not suitable because they can +only store small objects. The cache is maintained by the tlsmgr(8) process, so +there is no problem with concurrent access. Session caching is highly +recommended, because the cost of repeatedly negotiating TLS session keys is +high. Future Postfix SMTP servers may limit the number of sessions that a +client is allowed to negotiate per unit time. + +Example: + + /etc/postfix/main.cf: + smtp_tls_session_cache_database = btree:/var/lib/postfix/smtp_scache + +Note: as of version 2.5, Postfix no longer uses root privileges when opening +this file. The file should now be stored under the Postfix-owned +data_directory. As a migration aid, an attempt to open the file under a non- +Postfix directory is redirected to the Postfix-owned data_directory, and a +warning is logged. + +Cached Postfix SMTP client session information expires after a certain amount +of time. Postfix/TLS does not use the OpenSSL default of 300s, but a longer +time of 3600s (=1 hour). RFC 2246 recommends a maximum of 24 hours. + +Example: + + /etc/postfix/main.cf: + smtp_tls_session_cache_timeout = 3600s + +As of Postfix 2.11 this setting cannot exceed 100 days. If set <= 0, session +caching is disabled. If set to a positive value less than 2 minutes, the +minimum value of 2 minutes is used instead. + +CClliieenntt TTLLSS lliimmiittaattiioonnss + +The security properties of TLS communication channels are application specific. +While the TLS protocol can provide a confidential, tamper-resistant, mutually +authenticated channel between client and server, not all of these security +features are applicable to every communication. + +For example, while mutual TLS authentication between browsers and web servers +is possible, it is not practical, or even useful, for web-servers that serve +the public to verify the identity of every potential user. In practice, most +HTTPS transactions are asymmetric: the browser verifies the HTTPS server's +identity, but the user remains anonymous. Much of the security policy is up to +the client. If the client chooses to not verify the server's name, the server +is not aware of this. There are many interesting browser security topics, but +we shall not dwell on them here. Rather, our goal is to understand the security +features of TLS in conjunction with SMTP. + +An important SMTP-specific observation is that a public MX host is even more at +the mercy of the SMTP client than is an HTTPS server. Not only can it not +enforce due care in the client's use of TLS, but it cannot even enforce the use +of TLS, because TLS support in SMTP clients is still the exception rather than +the rule. One cannot, in practice, limit access to one's MX hosts to just TLS- +enabled clients. Such a policy would result in a vast reduction in one's +ability to communicate by email with the world at large. + +One may be tempted to try enforcing TLS for mail from specific sending +organizations, but this, too, runs into obstacles. One such obstacle is that we +don't know who is (allegedly) sending mail until we see the "MAIL FROM:" SMTP +command, and at that point, if TLS is not already in use, a potentially +sensitive sender address (and with SMTP PIPELINING one or more of the +recipients) has (have) already been leaked in the clear. Another obstacle is +that mail from the sender to the recipient may be forwarded, and the forwarding +organization may not have any security arrangements with the final destination. +Bounces also need to be protected. These can only be identified by the IP +address and HELO name of the connecting client, and it is difficult to keep +track of all the potential IP addresses or HELO names of the outbound email +servers of the sending organization. + +Consequently, TLS security for mail delivery to public MX hosts is almost +entirely the client's responsibility. The server is largely a passive enabler +of TLS security, the rest is up to the client. While the server has a greater +opportunity to mandate client security policy when it is a dedicated MSA that +only handles outbound mail from trusted clients, below we focus on the client +security policy. + +On the SMTP client, there are further complications. When delivering mail to a +given domain, in contrast to HTTPS, one rarely uses the domain name directly as +the target host of the SMTP session. More typically, one uses MX lookups - +- these are usually unauthenticated -- to obtain the domain's SMTP server +hostname(s). When, as is current practice, the client verifies the insecurely +obtained MX hostname, it is subject to a DNS man-in-the-middle attack. + +Adoption of DNSSEC and RFC6698 (DANE) may gradually (as domains implement +DNSSEC and publish TLSA records for their MX hosts) address the DNS man-in-the- +middle risk and provide scalable key management for SMTP with TLS. Postfix >= +2.11 supports the new dane and dane-only security levels that take advantage of +these standards. + +If clients instead attempted to verify the recipient domain name, an SMTP +server for multiple domains would need to list all its email domain names in +its certificate, and generate a new certificate each time a new domain were +added. At least some CAs set fairly low limits (20 for one prominent CA) on the +number of names that server certificates can contain. This approach is not +consistent with current practice and does not scale. + +It is regrettably the case that TLS secure-channels (fully authenticated and +immune to man-in-the-middle attacks) impose constraints on the sending and +receiving sites that preclude ubiquitous deployment. One needs to manually +configure this type of security for each destination domain, and in many cases +implement non-default TLS policy table entries for additional domains hosted at +a common secured destination. For these reasons secure-channel configurations +will never be the norm. For the generic domain with which you have made no +specific security arrangements, this security level is not a good fit. + +Given that strong authentication is not generally possible, and that verifiable +certificates cost time and money, many servers that implement TLS use self- +signed certificates or private CAs. This further limits the applicability of +verified TLS on the public Internet. + +Historical note: while the documentation of these issues and many of the +related features were new with Postfix 2.3, the issue was well understood +before Postfix 1.0, when Lutz Ja"nicke was designing the first unofficial +Postfix TLS patch. See his original post http://www.imc.org/ietf-apps-tls/mail- +archive/msg00304.html and the first response http://www.imc.org/ietf-apps-tls/ +mail-archive/msg00305.html. The problem is not even unique to SMTP or even TLS, +similar issues exist for secure connections via aliases for HTTPS and Kerberos. +SMTP merely uses indirect naming (via MX records) more frequently. + +TTLLSS ppoolliiccyy ttaabbllee + +A small fraction of servers offer STARTTLS but the negotiation consistently +fails. As long as encryption is not mandatory, the Postfix SMTP client retries +the delivery immediately with TLS disabled, without any need to explicitly +disable TLS for the problem destinations. + +The policy table is specified via the smtp_tls_policy_maps parameter. This +lists optional lookup tables with the Postfix SMTP client TLS security policy +by next-hop destination. + +The TLS policy table is indexed by the full next-hop destination, which is +either the recipient domain, or the verbatim next-hop specified in the +transport table, $local_transport, $virtual_transport, $relay_transport or +$default_transport. This includes any enclosing square brackets and any non- +default destination server port suffix. The LMTP socket type prefix (inet: or +unix:) is not included in the lookup key. + +Only the next-hop domain, or $myhostname with LMTP over UNIX-domain sockets, is +used as the nexthop name for certificate verification. The port and any +enclosing square brackets are used in the table lookup key, but are not used +for server name verification. + +When the lookup key is a domain name without enclosing square brackets or any : +port suffix (typically the recipient domain), and the full domain is not found +in the table, just as with the transport(5) table, the parent domain starting +with a leading "." is matched recursively. This allows one to specify a +security policy for a recipient domain and all its sub-domains. + +The lookup result is a security level, followed by an optional list of +whitespace and/or comma separated name=value attributes that override related +main.cf settings. The TLS security levels are described above. Below, we +describe the corresponding table syntax: + +nnoonnee + No TLS. No additional attributes are supported at this level. +mmaayy + Opportunistic TLS. The optional "ciphers", "exclude" and "protocols" + attributes (available for opportunistic TLS with Postfix >= 2.6) override + the "smtp_tls_ciphers", "smtp_tls_exclude_ciphers" and "smtp_tls_protocols" + configuration parameters. At this level and higher, the optional + "servername" attribute (available with Postfix >= 3.4) overrides the global + "smtp_tls_servername" parameter, enabling per-destination configuration of + the SNI extension sent to the remote SMTP server. +eennccrryypptt + Mandatory encryption. Mail is delivered only if the remote SMTP server + offers STARTTLS and the TLS handshake succeeds. At this level and higher, + the optional "protocols" attribute overrides the main.cf + smtp_tls_mandatory_protocols parameter, the optional "ciphers" attribute + overrides the main.cf smtp_tls_mandatory_ciphers parameter, and the + optional "exclude" attribute (Postfix >= 2.6) overrides the main.cf + smtp_tls_mandatory_exclude_ciphers parameter. +ddaannee + Opportunistic DANE TLS. The TLS policy for the destination is obtained via + TLSA records in DNSSEC. If no TLSA records are found, the effective + security level used is may. If TLSA records are found, but none are usable, + the effective security level is encrypt. When usable TLSA records are + obtained for the remote SMTP server, SSLv2+3 are automatically disabled + (see smtp_tls_mandatory_protocols), and the server certificate must match + the TLSA records. RFC 7672 (DANE) TLS authentication and DNSSEC support is + available with Postfix 2.11 and later. +ddaannee--oonnllyy + Mandatory DANE TLS. The TLS policy for the destination is obtained via TLSA + records in DNSSEC. If no TLSA records are found, or none are usable, no + connection is made to the server. When usable TLSA records are obtained for + the remote SMTP server, SSLv2+3 are automatically disabled (see + smtp_tls_mandatory_protocols), and the server certificate must match the + TLSA records. RFC 7672 (DANE) TLS authentication and DNSSEC support is + available with Postfix 2.11 and later. +ffiinnggeerrpprriinntt + Certificate fingerprint verification. Available with Postfix 2.5 and later. + At this security level, there are no trusted Certification Authorities. The + certificate trust chain, expiration date, ... are not checked. Instead, the + optional mmaattcchh attribute, or else the main.cf + ssmmttpp__ttllss__ffiinnggeerrpprriinntt__cceerrtt__mmaattcchh parameter, lists the server certificate + fingerprints or public key fingerprints (Postfix 2.9 and later). The digest + algorithm used to calculate fingerprints is selected by the + ssmmttpp__ttllss__ffiinnggeerrpprriinntt__ddiiggeesstt parameter. Multiple fingerprints can be + combined with a "|" delimiter in a single match attribute, or multiple + match attributes can be employed. The ":" character is not used as a + delimiter as it occurs between each pair of fingerprint (hexadecimal) + digits. +vveerriiffyy + Mandatory server certificate verification. Mail is delivered only if the + TLS handshake succeeds, if the remote SMTP server certificate can be + validated (not expired or revoked, and signed by a trusted Certification + Authority), and if the server certificate name matches the optional "match" + attribute (or the main.cf smtp_tls_verify_cert_match parameter value when + no optional "match" attribute is specified). With Postfix >= 2.11 the + "tafile" attribute optionally modifies trust chain verification in the same + manner as the "smtp_tls_trust_anchor_file" parameter. The "tafile" + attribute may be specified multiple times to load multiple trust-anchor + files. +sseeccuurree + Secure certificate verification. Mail is delivered only if the TLS + handshake succeeds, if the remote SMTP server certificate can be validated + (not expired or revoked, and signed by a trusted Certification Authority), + and if the server certificate name matches the optional "match" attribute + (or the main.cf smtp_tls_secure_cert_match parameter value when no optional + "match" attribute is specified). With Postfix >= 2.11 the "tafile" + attribute optionally modifies trust chain verification in the same manner + as the "smtp_tls_trust_anchor_file" parameter. The "tafile" attribute may + be specified multiple times to load multiple trust-anchor files. +Notes: + + * The "match" attribute is especially useful to verify TLS certificates for + domains that are hosted on a shared server. In that case, specify "match" + rules for the shared server's name. While secure verification can also be + achieved with manual routing overrides in Postfix transport(5) tables, that + approach can deliver mail to the wrong host when domains are assigned to + new gateway hosts. The "match" attribute approach avoids the problems of + manual routing overrides; mail is deferred if verification of a new MX host + fails. + + * When a policy table entry specifies multiple match patterns, multiple match + strategies, or multiple protocols, these must be separated by colons. + + * The "exclude" attribute (Postfix >= 2.6) is used to disable ciphers that + cause handshake failures with a specific mandatory TLS destination, without + disabling the ciphers for all mandatory destinations. Alternatively, you + can exclude ciphers that cause issues with multiple remote servers in + main.cf, and selectively enable them on a per-destination basis in the + policy table by setting a shorter or empty exclusion list. The per- + destination "exclude" list preempts both the opportunistic and mandatory + security level exclusions, so that all excluded ciphers can be enabled for + known-good destinations. For non-mandatory TLS destinations that exhibit + cipher-specific problems, Postfix will fall back to plain-text delivery. If + plain-text is not acceptable make TLS mandatory and exclude the problem + ciphers. + +Example: + + /etc/postfix/main.cf: + smtp_tls_policy_maps = hash:/etc/postfix/tls_policy + # Postfix 2.5 and later + smtp_tls_fingerprint_digest = md5 + /etc/postfix/tls_policy: + example.edu none + example.mil may + example.gov encrypt ciphers=high + example.com verify match=hostname:dot-nexthop ciphers=high + example.net secure + .example.net secure match=.example.net:example.net + [mail.example.org]:587 secure match=nexthop + # Postfix 2.5 and later + [thumb.example.org] fingerprint + match=EC:3B:2D:B0:5B:B1:FB:6D:20:A3:9D:72:F6:8D:12:35 + match=3D:95:34:51:24:66:33:B9:D2:40:99:C0:C1:17:0B:D1 + # Postfix 2.6 and later + example.info may protocols=!SSLv2 ciphers=medium + exclude=3DES + +NNoottee:: The "hostname" strategy if listed in a non-default setting of +smtp_tls_secure_cert_match or in the "match" attribute in the policy table can +render the "secure" level vulnerable to DNS forgery. Do not use the "hostname" +strategy for secure-channel configurations in environments where DNS security +is not assured. + +DDiissccoovveerriinngg sseerrvveerrss tthhaatt ssuuppppoorrtt TTLLSS + +As we decide on a "per site" basis whether or not to use TLS, it would be good +to have a list of sites that offered "STARTTLS". We can collect it ourselves +with this option. + +If the smtp_tls_note_starttls_offer feature is enabled and a server offers +STARTTLS while TLS is not already enabled for that server, the Postfix SMTP +client logs a line as follows: + + postfix/smtp[pid]: Host offered STARTTLS: [hostname.example.com] + +Example: + + /etc/postfix/main.cf: + smtp_tls_note_starttls_offer = yes + +SSeerrvveerr cceerrttiiffiiccaattee vveerriiffiiccaattiioonn ddeepptthh + +The server certificate verification depth is specified with the main.cf +smtp_tls_scert_verifydepth parameter. The default verification depth is 9 (the +OpenSSL default), for compatibility with Postfix versions before 2.5 where +smtp_tls_scert_verifydepth was ignored. When you configure trust in a root CA, +it is not necessary to explicitly trust intermediary CAs signed by the root CA, +unless $smtp_tls_scert_verifydepth is less than the number of CAs in the +certificate chain for the servers of interest. With a verify depth of 1 you can +only verify certificates directly signed by a trusted CA, and all trusted +intermediary CAs need to be configured explicitly. With a verify depth of 2 you +can verify servers signed by a root CA or a direct intermediary CA (so long as +the server is correctly configured to supply its intermediate CA certificate). + +Example: + + /etc/postfix/main.cf: + smtp_tls_scert_verifydepth = 2 + +CClliieenntt--ssiiddee cciipphheerr ccoonnttrroollss + +The Postfix SMTP client supports 5 distinct cipher grades as specified by the +smtp_tls_mandatory_ciphers configuration parameter. This setting controls the +minimum acceptable SMTP client TLS cipher grade for use with mandatory TLS +encryption. The default value "medium" is suitable for most destinations with +which you may want to enforce TLS, and is beyond the reach of today's +cryptanalytic methods. See smtp_tls_policy_maps for information on how to +configure ciphers on a per-destination basis. + +By default anonymous ciphers are allowed, and automatically disabled when +remote SMTP server certificates are verified. If you want to disable anonymous +ciphers even at the "encrypt" security level, set +"smtp_tls_mandatory_exclude_ciphers = aNULL"; and to disable anonymous ciphers +even with opportunistic TLS, set "smtp_tls_exclude_ciphers = aNULL". There is +generally no need to take these measures. Anonymous ciphers save bandwidth and +TLS session cache space, if certificates are ignored, there is little point in +requesting them. + +The "smtp_tls_ciphers" configuration parameter (Postfix >= 2.6) provides +control over the minimum cipher grade for opportunistic TLS. The default +minimum cipher grade for opportunistic TLS is "medium" for Postfix releases +after the middle of 2015, and "export" for older releases. With Postfix < 2.6, +the minimum opportunistic TLS cipher grade is always "export". + +With mandatory and opportunistic TLS encryption, the Postfix SMTP client will +by default disable SSLv2 and SSLv3. The mandatory TLS protocol list is +specified via the smtp_tls_mandatory_protocols configuration parameter. The +corresponding smtp_tls_protocols parameter (Postfix >= 2.6) controls the SSL/ +TLS protocols used with opportunistic TLS. + +Example: + + /etc/postfix/main.cf: + smtp_tls_mandatory_ciphers = medium + smtp_tls_mandatory_exclude_ciphers = RC4, MD5 + smtp_tls_exclude_ciphers = aNULL + # Preferred form with Postfix >= 2.5: + smtp_tls_mandatory_protocols = !SSLv2 + # Legacy form for Postfix < 2.5: + smtp_tls_mandatory_protocols = SSLv3, TLSv1 + # Also available with Postfix >= 2.6: + smtp_tls_ciphers = medium + smtp_tls_protocols = !SSLv2 + +CClliieenntt--ssiiddee SSMMTTPPSS ssuuppppoorrtt + +These sections show how to send mail to a server that does not support +STARTTLS, but that provides the deprecated SMTPS service on TCP port 465. +Depending on the Postfix version, some additional tooling may be required. + +PPoossttffiixx >>== 33..00 + +The Postfix SMTP client has SMTPS support built-in as of version 3.0. Use one +of the following examples, to send all remote mail, or to send only some remote +mail, to an SMTPS server. + +PPoossttffiixx >>== 33..00:: SSeennddiinngg aallll rreemmoottee mmaaiill ttoo aann SSMMTTPPSS sseerrvveerr + +The first example will send all remote mail over SMTPS through a provider's +server called "mail.example.com": + + /etc/postfix/main.cf: + # Client-side SMTPS requires "encrypt" or stronger. + smtp_tls_security_level = encrypt + smtp_tls_wrappermode = yes + # The [] suppress MX lookups. + relayhost = [mail.example.com]:465 + +Use "postfix reload" to make the change effective. + +See SOHO_README for additional information about SASL authentication. + +PPoossttffiixx >>== 33..00:: SSeennddiinngg oonnllyy mmaaiill ffoorr aa ssppeecciiffiicc ddeessttiinnaattiioonn vviiaa SSMMTTPPSS + +The second example will send only mail for "example.com" via SMTPS. This time, +Postfix uses a transport map to deliver only mail for "example.com" via SMTPS: + + /etc/postfix/main.cf: + transport_maps = hash:/etc/postfix/transport + + /etc/postfix/transport: + example.com relay-smtps:example.com:465 + + /etc/postfix/master.cf: + relay-smtps unix - - n - - smtp + # Client-side SMTPS requires "encrypt" or stronger. + -o smtp_tls_security_level=encrypt + -o smtp_tls_wrappermode=yes + +Use "postmap hash:/etc/postfix/transport" and "postfix reload" to make the +change effective. + +See SOHO_README for additional information about SASL authentication. + +PPoossttffiixx << 33..00 + +Although older Postfix SMTP client versions do not support TLS wrapper mode, it +is relatively easy to forward a connection through the stunnel program if +Postfix needs to deliver mail to some legacy system that doesn't support +STARTTLS. + +PPoossttffiixx << 33..00:: SSeennddiinngg aallll rreemmoottee mmaaiill ttoo aann SSMMTTPPSS sseerrvveerr + +The first example uses SMTPS to send all remote mail to a provider's mail +server called "mail.example.com". + +A minimal stunnel.conf file is sufficient to set up a tunnel from local port +11125 to the remote destination "mail.example.com" and port "smtps". Postfix +will later use this tunnel to connect to the remote server. + + /path/to/stunnel.conf: + [smtp-tls-wrapper] + accept = 11125 + client = yes + connect = mail.example.com:smtps + +To test this tunnel, use: + + $ telnet localhost 11125 + +This should produce the greeting from the remote SMTP server at +mail.example.com. + +On the Postfix side, the relayhost feature sends all remote mail through the +local stunnel listener on port 11125: + + /etc/postfix/main.cf: + relayhost = [127.0.0.1]:11125 + +Use "postfix reload" to make the change effective. + +See SOHO_README for additional information about SASL authentication. + +PPoossttffiixx << 33..00:: SSeennddiinngg oonnllyy mmaaiill ffoorr aa ssppeecciiffiicc ddeessttiinnaattiioonn vviiaa SSMMTTPPSS + +The second example will use SMTPS to send only mail for "example.com" via +SMTPS. It uses the same stunnel configuration file as the first example, so it +won't be repeated here. + +This time, the Postfix side uses a transport map to direct only mail for +"example.com" through the tunnel: + + /etc/postfix/main.cf: + transport_maps = hash:/etc/postfix/transport + + /etc/postfix/transport: + example.com relay:[127.0.0.1]:11125 + +Use "postmap hash:/etc/postfix/transport" and "postfix reload" to make the +change effective. + +See SOHO_README for additional information about SASL authentication. + +MMiisscceellllaanneeoouuss cclliieenntt ccoonnttrroollss + +The smtp_starttls_timeout parameter limits the time of Postfix SMTP client +write and read operations during TLS startup and shutdown handshake procedures. +In case of problems the Postfix SMTP client tries the next network address on +the mail exchanger list, and defers delivery if no alternative server is +available. + +Example: + + /etc/postfix/main.cf: + smtp_starttls_timeout = 300s + +With Postfix 2.8 and later, the tls_disable_workarounds parameter specifies a +list or bit-mask of OpenSSL bug work-arounds to disable. This may be necessary +if one of the work-arounds enabled by default in OpenSSL proves to pose a +security risk, or introduces an unexpected interoperability issue. Some bug +work-arounds known to be problematic are disabled in the default value of the +parameter when linked with an OpenSSL library that could be vulnerable. + +Example: + + /etc/postfix/main.cf: + tls_disable_workarounds = 0xFFFFFFFF + tls_disable_workarounds = CVE-2010-4180, LEGACY_SERVER_CONNECT + +Note: Disabling LEGACY_SERVER_CONNECT is not wise at this time, lots of servers +are still unpatched and Postfix is not significantly vulnerable to the +renegotiation issue in the TLS protocol. + +With Postfix >= 2.11, the tls_ssl_options parameter specifies a list or bit- +mask of OpenSSL options to enable. Specify one or more of the named options +below, or a hexadecimal bitmask of options found in the ssl.h file +corresponding to the run-time OpenSSL library. While it may be reasonable to +turn off all bug workarounds (see above), it is not a good idea to attempt to +turn on all features. + +A future version of OpenSSL may by default no longer allow connections to +servers that don't support secure renegotiation. Since the exposure for SMTP is +minimal, and some SMTP servers may remain unpatched, you can add +LEGACY_SERVER_CONNECT to the options to restore the more permissive default of +current OpenSSL releases. + +Example: + + /etc/postfix/main.cf: + tls_ssl_options = NO_TICKET, NO_COMPRESSION, LEGACY_SERVER_CONNECT + +You should only enable features via the hexadecimal mask when the need to +control the feature is critical (to deal with a new vulnerability or a serious +interoperability problem). Postfix DOES NOT promise backwards compatible +behavior with respect to the mask bits. A feature enabled via the mask in one +release may be enabled by other means in a later release, and the mask bit will +then be ignored. Therefore, use of the hexadecimal mask is only a temporary +measure until a new Postfix or OpenSSL release provides a better solution. + +TTLLSS mmaannaaggeerr ssppeecciiffiicc sseettttiinnggss + +The security of cryptographic software such as TLS depends critically on the +ability to generate unpredictable numbers for keys and other information. To +this end, the tlsmgr(8) process maintains a Pseudo Random Number Generator +(PRNG) pool. This is queried by the smtp(8) and smtpd(8) processes when they +initialize. By default, these daemons request 32 bytes, the equivalent to 256 +bits. This is more than sufficient to generate a 128bit (or 168bit) session +key. + +Example: + + /etc/postfix/main.cf: + tls_daemon_random_bytes = 32 + +In order to feed its in-memory PRNG pool, the tlsmgr(8) reads entropy from an +external source, both at startup and during run-time. Specify a good entropy +source, like EGD or /dev/urandom; be sure to only use non-blocking sources (on +OpenBSD, use /dev/arandom when tlsmgr(8) complains about /dev/urandom timeout +errors). If the entropy source is not a regular file, you must prepend the +source type to the source name: "dev:" for a device special file, or "egd:" for +a source with EGD compatible socket interface. + +Examples (specify only one in main.cf): + + /etc/postfix/main.cf: + tls_random_source = dev:/dev/urandom + tls_random_source = egd:/var/run/egd-pool + +By default, tlsmgr(8) reads 32 bytes from the external entropy source at each +seeding event. This amount (256bits) is more than sufficient for generating a +128bit symmetric key. With EGD and device entropy sources, the tlsmgr(8) limits +the amount of data read at each step to 255 bytes. If you specify a regular +file as entropy source, a larger amount of data can be read. + +Example: + + /etc/postfix/main.cf: + tls_random_bytes = 32 + +In order to update its in-memory PRNG pool, the tlsmgr(8) queries the external +entropy source again after a pseudo-random amount of time. The time is +calculated using the PRNG, and is between 0 and the maximal time specified with +tls_random_reseed_period. The default maximal time interval is 1 hour. + +Example: + + /etc/postfix/main.cf: + tls_random_reseed_period = 3600s + +The tlsmgr(8) process saves the PRNG state to a persistent exchange file at +regular times and when the process terminates, so that it can recover the PRNG +state the next time it starts up. This file is created when it does not exist. + +Examples: + + /etc/postfix/main.cf: + tls_random_exchange_name = /var/lib/postfix/prng_exch + tls_random_prng_update_period = 3600s + +As of version 2.5, Postfix no longer uses root privileges when opening this +file. The file should now be stored under the Postfix-owned data_directory. As +a migration aid, an attempt to open the file under a non-Postfix directory is +redirected to the Postfix-owned data_directory, and a warning is logged. If you +wish to continue using a pre-existing PRNG state file, move it to the +data_directory and change the ownership to the account specified with the +mail_owner parameter. + +With earlier Postfix versions the default file location is under the Postfix +configuration directory, which is not the proper place for information that is +modified by Postfix. + +GGeettttiinngg ssttaarrtteedd,, qquuiicckk aanndd ddiirrttyy + +The following steps will get you started quickly. Because you sign your own +Postfix public key certificate, you get TLS encryption but no TLS +authentication. This is sufficient for testing, and for exchanging email with +sites that you have no trust relationship with. For real authentication you +need also enable DNSSEC record signing for your domain and publish TLSA records +and/or your Postfix public key certificate needs to be signed by a recognized +Certification Authority. To authenticate the certificates of remote host you +need a DNSSEC-validating local resolver and to enable DANE authentication and/ +or configure the Postfix SMTP client with a list of public key certificates of +Certification Authorities, but make sure to read about the limitations of the +latter approach. + +In the examples below, user input is shown in bboolldd font, and a "#" prompt +indicates a super-user shell. + + * Quick-start TLS with Postfix >= 3.1. + + * Self-signed server certificate. + + * Private Certification Authority. + +QQuuiicckk--ssttaarrtt TTLLSS wwiitthh PPoossttffiixx >>== 33..11 + +Postfix 3.1 provides built-in support for enabling TLS in the SMTP client and +server and for ongoing certificate and DANE TLSA record management. + + * Quick-start TLS in the Postfix >= 3.1 SMTP client. + + * Quick-start TLS in the Postfix >= 3.1 SMTP server. + +QQuuiicckk--ssttaarrtt TTLLSS iinn tthhee PPoossttffiixx >>== 33..11 SSMMTTPP cclliieenntt.. + +If you are using Postfix 3.1 or later, and your SMTP client TLS settings are in +their default state, you can enable opportunistic TLS in the SMTP client as +follows: + + # postfix tls enable-client + # postfix reload + +If some of the Postfix SMTP client TLS settings are not in their default state, +this will not make any changes, but will instead suggest the minimal required +settings for SMTP client TLS. The "postfix reload" command is optional, it is +only needed if you want the settings to take effect right away. Note, this does +not enable trust in any public certification authorities, and does not +configure client TLS certificates as these are largely pointless with +opportunistic TLS. + +There is not yet a turn-key command for enabling DANE authentication. This is +because DANE requires changes to your rreessoollvv..ccoonnff file and a corresponding +DNSSEC-validating resolver local to the Postfix host, these changes are +difficult to automate in a portable way. + +If you're willing to revert your settings to the defaults and switch to a +"stock" opportunistic TLS configuration, then you can: erase all the SMTP +client TLS settings and then enable client TLS: + + # postconf -X `postconf -nH | egrep '^smtp(_|_enforce_|_use_)tls'` + # postfix tls enable-client + # postfix reload + +QQuuiicckk--ssttaarrtt TTLLSS iinn tthhee PPoossttffiixx >>== 33..11 SSMMTTPP sseerrvveerr.. + +If you are using Postfix 3.1 or later, and your SMTP server TLS settings are in +their default state, you can enable opportunistic TLS in the SMTP server as +follows: + + # postfix tls enable-server + # postfix reload + +If some of the Postfix SMTP client TLS settings are not in their default state, +this will not make any changes, but will instead suggest the minimal required +settings for SMTP client TLS. The "postfix reload" command is optional, it is +only needed if you want the settings to take effect right away. This will +generate a self-signed private key and certificate and enable TLS in the +Postfix SMTP server. + +If you're willing to revert your settings to the defaults and switch to a +"stock" server TLS configuration, then you can: erase all the SMTP server TLS +settings and then enable server TLS: + + # postconf -X `postconf -nH | egrep '^smtpd(_|_enforce_|_use_)tls'` + # postfix tls enable-server + # postfix reload + +Postfix >= 3.1 provides additional built-in support for ongoing management of +TLS in the SMTP server, via additional "postfix tls" sub-commands. These make +it easy to generate certificate signing requests, create and deploy new keys +and certificates, and generate DANE TLSA records. See the postfix-tls(1) +documentation for details. + +SSeellff--ssiiggnneedd sseerrvveerr cceerrttiiffiiccaattee + +The following commands (credits: Viktor Dukhovni) generate and install a 2048- +bit RSA private key and 10-year self-signed certificate for the local Postfix +system. This requires super-user privileges. (By using date-specific filenames +for the certificate and key files, and updating main.cf with new filenames, a +potential race condition in which the key and certificate might not match is +avoided). + + # dir="$(postconf -h config_directory)" + # fqdn=$(postconf -h myhostname) + # case $fqdn in /*) fqdn=$(cat "$fqdn");; esac + # ymd=$(date +%Y-%m-%d) + # key="${dir}/key-${ymd}.pem"; rm -f "${key}" + # cert="${dir}/cert-${ymd}.pem"; rm -f "${cert}" + # (umask 077; openssl genrsa -out "${key}" 2048) && + openssl req -new -key "${key}" \ + -x509 -subj "/CN=${fqdn}" -days 3650 -out "${cert}" && + postconf -e \ + "smtpd_tls_cert_file = ${cert}" \ + "smtpd_tls_key_file = ${key}" \ + 'smtpd_tls_security_level = may' \ + 'smtpd_tls_received_header = yes' \ + 'smtpd_tls_loglevel = 1' \ + 'smtp_tls_security_level = may' \ + 'smtp_tls_loglevel = 1' \ + 'smtp_tls_session_cache_database = btree:${data_directory}/smtp_scache' + \ + 'tls_random_source = dev:/dev/urandom' + +Note: the last command requires both single (') and double (") quotes. + +The postconf(1) command above enables opportunistic TLS for receiving and +sending mail. It also enables logging of TLS connections and recording of TLS +use in the "Received" header. TLS session caching is also enabled in the +Postfix SMTP client. With Postfix >= 2.10, the SMTP server does not need an +explicit session cache since session reuse is better handled via RFC 5077 TLS +session tickets. + +PPrriivvaattee CCeerrttiiffiiccaattiioonn AAuutthhoorriittyy + + * Become your own Certification Authority, so that you can sign your own + certificates, and so that your own systems can authenticate certificates + from your own CA. This example uses the CA.pl script that ships with + OpenSSL. On some systems, OpenSSL installs this as /usr/local/openssl/misc/ + CA.pl. Some systems install this as part of a package named openssl-perl or + something similar. The script creates a private key in ./demoCA/private/ + cakey.pem and a public key in ./demoCA/cacert.pem. + + % //uussrr//llooccaall//ssssll//mmiisscc//CCAA..ppll --nneewwccaa + CA certificate filename (or enter to create) + + Making CA certificate ... + Using configuration from /etc/ssl/openssl.cnf + Generating a 1024 bit RSA private key + ....................++++++ + .....++++++ + writing new private key to './demoCA/private/cakey.pem' + Enter PEM pass phrase:wwhhaatteevveerr + + * Create an unpassworded private key for host foo.porcupine.org and create an + unsigned public key certificate. + + % ((uummaasskk 007777;; ooppeennssssll rreeqq --nneeww --nneewwkkeeyy rrssaa::22004488 --nnooddeess --kkeeyyoouutt ffoooo-- + kkeeyy..ppeemm --oouutt ffoooo--rreeqq..ppeemm)) + Using configuration from /etc/ssl/openssl.cnf + Generating a 2048 bit RSA private key + ........................................++++++ + ....++++++ + writing new private key to 'foo-key.pem' + ----- + You are about to be asked to enter information that will be + incorporated + into your certificate request. + What you are about to enter is what is called a Distinguished Name or a + DN. + There are quite a few fields but you can leave some blank + For some fields there will be a default value, + If you enter '.', the field will be left blank. + ----- + Country Name (2 letter code) [AU]:UUSS + State or Province Name (full name) [Some-State]:NNeeww YYoorrkk + Locality Name (eg, city) []:WWeessttcchheesstteerr + Organization Name (eg, company) [Internet Widgits Pty Ltd]:PPoorrccuuppiinnee + Organizational Unit Name (eg, section) []: + Common Name (eg, YOUR name) []:ffoooo..ppoorrccuuppiinnee..oorrgg + Email Address []:wwiieettssee@@ppoorrccuuppiinnee..oorrgg + + Please enter the following 'extra' attributes + to be sent with your certificate request + A challenge password []:wwhhaatteevveerr + An optional company name []: + + * Sign the public key certificate for host foo.porcupine.org with the + Certification Authority private key that we created a few steps ago. + + % ooppeennssssll ccaa --oouutt ffoooo--cceerrtt..ppeemm --ddaayyss 336655 --iinnffiilleess ffoooo--rreeqq..ppeemm + Using configuration from /etc/ssl/openssl.cnf + Enter PEM pass phrase:wwhhaatteevveerr + Check that the request matches the signature + Signature ok + The Subjects Distinguished Name is as follows + countryName :PRINTABLE:'US' + stateOrProvinceName :PRINTABLE:'New York' + localityName :PRINTABLE:'Westchester' + organizationName :PRINTABLE:'Porcupine' + commonName :PRINTABLE:'foo.porcupine.org' + emailAddress :IA5STRING:'wietse@porcupine.org' + Certificate is to be certified until Nov 21 19:40:56 2005 GMT (365 + days) + Sign the certificate? [y/n]:yy + + 1 out of 1 certificate requests certified, commit? [y/n]yy + Write out database with 1 new entries + Data Base Updated + + * Install the host private key, the host public key certificate, and the + Certification Authority certificate files. This requires super-user + privileges. + + The following commands assume that the key and certificate will be + installed for the local Postfix MTA. You will need to adjust the commands + if the Postfix MTA is on a different host. + + # ccpp ddeemmooCCAA//ccaacceerrtt..ppeemm ffoooo--kkeeyy..ppeemm ffoooo--cceerrtt..ppeemm //eettcc//ppoossttffiixx + # cchhmmoodd 664444 //eettcc//ppoossttffiixx//ffoooo--cceerrtt..ppeemm //eettcc//ppoossttffiixx//ccaacceerrtt..ppeemm + # cchhmmoodd 440000 //eettcc//ppoossttffiixx//ffoooo--kkeeyy..ppeemm + + * Configure Postfix, by adding the following to /etc/postfix/main.cf. It is + generally best to not configure client certificates, unless there are + servers which authenticate your mail submission via client certificates. + Often servers that perform TLS client authentication will issue the + required certificates signed by their own CA. If you configure the client + certificate and key incorrectly, you will be unable to send mail to sites + that request client certificate, but don't require them from all clients. + + /etc/postfix/main.cf: + smtp_tls_CAfile = /etc/postfix/cacert.pem + smtp_tls_session_cache_database = + btree:/var/lib/postfix/smtp_tls_session_cache + smtp_tls_security_level = may + smtp_tls_loglevel = 1 + smtpd_tls_CAfile = /etc/postfix/cacert.pem + smtpd_tls_cert_file = /etc/postfix/foo-cert.pem + smtpd_tls_key_file = /etc/postfix/foo-key.pem + smtpd_tls_received_header = yes + smtpd_tls_session_cache_database = + btree:/var/lib/postfix/smtpd_tls_session_cache + tls_random_source = dev:/dev/urandom + smtpd_tls_security_level = may + smtpd_tls_loglevel = 1 + +BBuuiillddiinngg PPoossttffiixx wwiitthh TTLLSS ssuuppppoorrtt + +These instructions assume that you build Postfix from source code as described +in the INSTALL document. Some modification may be required if you build Postfix +from a vendor-specific source package. + +To build Postfix with TLS support, first we need to generate the make(1) files +with the necessary definitions. This is done by invoking the command "make +makefiles" in the Postfix top-level directory and with arguments as shown next. + +NNOOTTEE:: DDoo nnoott uussee GGnnuu TTLLSS.. IItt wwiillll ssppoonnttaanneeoouussllyy tteerrmmiinnaattee aa PPoossttffiixx ddaaeemmoonn +pprroocceessss wwiitthh eexxiitt ssttaattuuss ccooddee 22,, iinnsstteeaadd ooff aalllloowwiinngg PPoossttffiixx ttoo 11)) rreeppoorrtt tthhee +eerrrroorr ttoo tthhee mmaaiilllloogg ffiillee,, aanndd ttoo 22)) pprroovviiddee ppllaaiinntteexxtt sseerrvviiccee wwhheerree tthhiiss iiss +aapppprroopprriiaattee.. + + * If the OpenSSL include files (such as ssl.h) are in directory /usr/include/ + openssl, and the OpenSSL libraries (such as libssl.so and libcrypto.so) are + in directory /usr/lib: + + % mmaakkee ttiiddyy # if you have left-over files from a previous build + % mmaakkee mmaakkeeffiilleess CCCCAARRGGSS==""--DDUUSSEE__TTLLSS"" AAUUXXLLIIBBSS==""--llssssll --llccrryyppttoo"" + + * If the OpenSSL include files (such as ssl.h) are in directory /usr/local/ + include/openssl, and the OpenSSL libraries (such as libssl.so and + libcrypto.so) are in directory /usr/local/lib: + + % mmaakkee ttiiddyy # if you have left-over files from a previous build + % mmaakkee mmaakkeeffiilleess CCCCAARRGGSS==""--DDUUSSEE__TTLLSS --II//uussrr//llooccaall//iinncclluuddee"" \\ + AAUUXXLLIIBBSS==""--LL//uussrr//llooccaall//lliibb --llssssll --llccrryyppttoo"" + + On Solaris, specify the -R option as shown below: + + % mmaakkee ttiiddyy # if you have left-over files from a previous build + % mmaakkee mmaakkeeffiilleess CCCCAARRGGSS==""--DDUUSSEE__TTLLSS --II//uussrr//llooccaall//iinncclluuddee"" \\ + AAUUXXLLIIBBSS==""--RR//uussrr//llooccaall//lliibb --LL//uussrr//llooccaall//lliibb --llssssll --llccrryyppttoo"" + +If you need to apply other customizations (such as Berkeley DB databases, +MySQL, PostgreSQL, LDAP or SASL), see the respective Postfix README documents, +and combine their "make makefiles" instructions with the instructions above: + + % mmaakkee ttiiddyy # if you have left-over files from a previous build + % mmaakkee mmaakkeeffiilleess CCCCAARRGGSS==""--DDUUSSEE__TTLLSS \\ + ((ootthheerr --DD oorr --II ooppttiioonnss))"" \\ + AAUUXXLLIIBBSS==""--llssssll --llccrryyppttoo \\ + ((ootthheerr --ll ooppttiioonnss ffoorr lliibbrraarriieess iinn //uussrr//lliibb)) \\ + ((--LL//ppaatthh//nnaammee ++ --ll ooppttiioonnss ffoorr ootthheerr lliibbrraarriieess))"" + +To complete the build process, see the Postfix INSTALL instructions. Postfix +has TLS support turned off by default, so you can start using Postfix as soon +as it is installed. + +RReeppoorrttiinngg pprroobblleemmss + +Problems are preferably reported via <postfix-users@postfix.org>. See http:// +www.postfix.org/lists.html for subscription information. When reporting a +problem, please be thorough in the report. Patches, when possible, are greatly +appreciated too. + +CCrreeddiittss + + * TLS support for Postfix was originally developed by Lutz Ja"nicke at + Cottbus Technical University. + * Wietse Venema adopted the code, did some restructuring, and compiled this + part of the documentation from Lutz's documents. + * Victor Duchovni was instrumental with the re-implementation of the + smtp_tls_per_site code in terms of enforcement levels, which simplified the + implementation greatly. + * Victor Duchovni implemented the fingerprint security level, added more + sanity checks, and separated TLS connection management from security policy + enforcement. The latter change simplified the code that verifies + certificate signatures, certificate names, and certificate fingerprints. + |