summaryrefslogtreecommitdiffstats
path: root/README_FILES/TLS_README
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--README_FILES/TLS_README2495
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.
+