SMTP time with the smtpd_command_filter feature. Files:
proto/VERP_README.html, proto/postconf.proto.
+ Feature: TLS certificate public-key fingerprint matching
+ (SMTP server and client), and TLS logging cleanup. Victor
+ Duchovni. Files: proto/SMTPD_POLICY_README.html,
+ proto/TLS_README.html, proto/postconf.proto, global/mail_proto.h,
+ smtpd/smtpd_check.c, tls/tls.h, tls/tls_client.c, tls/tls_misc.c,
+ tls/tls_proxy_print.c, tls/tls_proxy_scan.c, tls/tls_server.c,
+ tls/tls_stream.c, tls/tls_verify.c.
+
Documentation: complete list of "make makefiles" overrides.
File: proto/INSTALL.html.
parameter names). Files: postconf/postconf.c, postconf/postconf.h,
postconf_service.c, postconf/postconf_user.c.
+20111129
+
+ Cleanup: TLS logging level configuration. Files:
+ global/mail_params.h, smtp/lmtp_params.c, smtp/smtp.c,
+ smtp/smtp_params.c, smtp/smtp_proto.c, smtpd/smtpd.c,
+ tls/tls.h, tls/tls_client.c, tls/tls_misc.c, tls/tls_server.c,
+ tlsmgr/tlsmgr.c, tlsproxy/tlsproxy.c.
20111203
Cleanup: time-dependent sender addresses of address
smtpd/smtpd_check.c, verify/verify.c, proto/postconf.proto,
proto/ADDRESS_VERIFICATION_README.html.
+20111204
+
+ Cleanup: removed the log_level arguments from tls_client_start()
+ and tls_server_start() calls. This information is already
+ given to tls_client_init() and tls_server_init(). Files:
+ smtpd/smtpd.c, tlsproxy/tlsproxy.c, smtp/smtp_proto.c,
+ tls/tls.h, tls/tls_client.c, tls/tls_server.c, tls/tls_misc.c.
+
+20111205
+
+ Documentation: made the postconf(5) manpage more precise
+ in its use of "client" and "server"; reorganized the
+ TLS_README presentation of client configuration so that
+ most relevant information is presented earlier. Files:
+ proto/postconf.proto, proto/TLS_README.html.
+
+ Bugfix: tlsproxy(8) stored TLS sessions with a serverID of
+ "tlsproxy" instead of "smtpd", wasting an opportunity for
+ session reuse. File: tlsproxy/tlsproxy.c.
etrn_domain=
P\bPo\bos\bst\btf\bfi\bix\bx v\bve\ber\brs\bsi\bio\bon\bn 2\b2.\b.5\b5 a\ban\bnd\bd l\bla\bat\bte\ber\br:\b:
stress=
+ P\bPo\bos\bst\btf\bfi\bix\bx v\bve\ber\brs\bsi\bio\bon\bn 2\b2.\b.9\b9 a\ban\bnd\bd l\bla\bat\bte\ber\br:\b:
+ ccert_pubkey_fingerprint=68:B3:29:DA:98:93:E3:40:99:C7:D8:AD:5C:B9:C9:40
[empty line]
Notes:
Topics covered in this document:
* How Postfix TLS support works
- * Building Postfix with TLS support
* SMTP Server specific settings
* SMTP Client specific settings
* TLS manager specific settings
+ * Building Postfix with TLS support
* Reporting problems
* Credits
session state session
key cache file key cache
-B\bBu\bui\bil\bld\bdi\bin\bng\bg P\bPo\bos\bst\btf\bfi\bix\bx w\bwi\bit\bth\bh T\bTL\bLS\bS s\bsu\bup\bpp\bpo\bor\brt\bt
-
-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.
-
-N\bNO\bOT\bTE\bE:\b: D\bDo\bo n\bno\bot\bt u\bus\bse\be G\bGn\bnu\bu T\bTL\bLS\bS.\b. I\bIt\bt w\bwi\bil\bll\bl s\bsp\bpo\bon\bnt\bta\ban\bne\beo\bou\bus\bsl\bly\by t\bte\ber\brm\bmi\bin\bna\bat\bte\be a\ba P\bPo\bos\bst\btf\bfi\bix\bx d\bda\bae\bem\bmo\bon\bn
-p\bpr\bro\boc\bce\bes\bss\bs w\bwi\bit\bth\bh e\bex\bxi\bit\bt s\bst\bta\bat\btu\bus\bs c\bco\bod\bde\be 2\b2,\b, i\bin\bns\bst\bte\bea\bad\bd o\bof\bf a\bal\bll\blo\bow\bwi\bin\bng\bg P\bPo\bos\bst\btf\bfi\bix\bx t\bto\bo 1\b1)\b) r\bre\bep\bpo\bor\brt\bt t\bth\bhe\be
-e\ber\brr\bro\bor\br t\bto\bo t\bth\bhe\be m\bma\bai\bil\bll\blo\bog\bg f\bfi\bil\ble\be,\b, a\ban\bnd\bd t\bto\bo 2\b2)\b) p\bpr\bro\bov\bvi\bid\bde\be p\bpl\bla\bai\bin\bnt\bte\bex\bxt\bt s\bse\ber\brv\bvi\bic\bce\be w\bwh\bhe\ber\bre\be t\bth\bhi\bis\bs i\bis\bs
-a\bap\bpp\bpr\bro\bop\bpr\bri\bia\bat\bte\be.\b.
-
- * 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:
-
- % m\bma\bak\bke\be t\bti\bid\bdy\by # if you have left-over files from a previous build
- % m\bma\bak\bke\be m\bma\bak\bke\bef\bfi\bil\ble\bes\bs C\bCC\bCA\bAR\bRG\bGS\bS=\b="\b"-\b-D\bDU\bUS\bSE\bE_\b_T\bTL\bLS\bS"\b" A\bAU\bUX\bXL\bLI\bIB\bBS\bS=\b="\b"-\b-l\bls\bss\bsl\bl -\b-l\blc\bcr\bry\byp\bpt\bto\bo"\b"
-
- * 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:
-
- % m\bma\bak\bke\be t\bti\bid\bdy\by # if you have left-over files from a previous build
- % m\bma\bak\bke\be m\bma\bak\bke\bef\bfi\bil\ble\bes\bs C\bCC\bCA\bAR\bRG\bGS\bS=\b="\b"-\b-D\bDU\bUS\bSE\bE_\b_T\bTL\bLS\bS -\b-I\bI/\b/u\bus\bsr\br/\b/l\blo\boc\bca\bal\bl/\b/i\bin\bnc\bcl\blu\bud\bde\be"\b" \\b\
- A\bAU\bUX\bXL\bLI\bIB\bBS\bS=\b="\b"-\b-L\bL/\b/u\bus\bsr\br/\b/l\blo\boc\bca\bal\bl/\b/l\bli\bib\bb -\b-l\bls\bss\bsl\bl -\b-l\blc\bcr\bry\byp\bpt\bto\bo"\b"
-
- On Solaris, specify the -R option as shown below:
-
- % m\bma\bak\bke\be t\bti\bid\bdy\by # if you have left-over files from a previous build
- % m\bma\bak\bke\be m\bma\bak\bke\bef\bfi\bil\ble\bes\bs C\bCC\bCA\bAR\bRG\bGS\bS=\b="\b"-\b-D\bDU\bUS\bSE\bE_\b_T\bTL\bLS\bS -\b-I\bI/\b/u\bus\bsr\br/\b/l\blo\boc\bca\bal\bl/\b/i\bin\bnc\bcl\blu\bud\bde\be"\b" \\b\
- A\bAU\bUX\bXL\bLI\bIB\bBS\bS=\b="\b"-\b-R\bR/\b/u\bus\bsr\br/\b/l\blo\boc\bca\bal\bl/\b/l\bli\bib\bb -\b-L\bL/\b/u\bus\bsr\br/\b/l\blo\boc\bca\bal\bl/\b/l\bli\bib\bb -\b-l\bls\bss\bsl\bl -\b-l\blc\bcr\bry\byp\bpt\bto\bo"\b"
-
-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:
-
- % m\bma\bak\bke\be t\bti\bid\bdy\by # if you have left-over files from a previous build
- % m\bma\bak\bke\be m\bma\bak\bke\bef\bfi\bil\ble\bes\bs C\bCC\bCA\bAR\bRG\bGS\bS=\b="\b"-\b-D\bDU\bUS\bSE\bE_\b_T\bTL\bLS\bS \\b\
- (\b(o\bot\bth\bhe\ber\br -\b-D\bD o\bor\br -\b-I\bI o\bop\bpt\bti\bio\bon\bns\bs)\b)"\b" \\b\
- A\bAU\bUX\bXL\bLI\bIB\bBS\bS=\b="\b"-\b-l\bls\bss\bsl\bl -\b-l\blc\bcr\bry\byp\bpt\bto\bo \\b\
- (\b(o\bot\bth\bhe\ber\br -\b-l\bl o\bop\bpt\bti\bio\bon\bns\bs f\bfo\bor\br l\bli\bib\bbr\bra\bar\bri\bie\bes\bs i\bin\bn /\b/u\bus\bsr\br/\b/l\bli\bib\bb)\b) \\b\
- (\b(-\b-L\bL/\b/p\bpa\bat\bth\bh/\b/n\bna\bam\bme\be +\b+ -\b-l\bl o\bop\bpt\bti\bio\bon\bns\bs f\bfo\bor\br o\bot\bth\bhe\ber\br l\bli\bib\bbr\bra\bar\bri\bie\bes\bs)\b)"\b"
-
-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.
-
S\bSM\bMT\bTP\bP S\bSe\ber\brv\bve\ber\br s\bsp\bpe\bec\bci\bif\bfi\bic\bc s\bse\bet\btt\bti\bin\bng\bgs\bs
Topics covered in this section:
increase the log level from 0..4. Each logging level also includes the
information that is logged at a lower logging level.
- 0 Disable logging of TLS activity.
-
- 1 Log TLS handshake and certificate information.
-
- 2 Log levels during TLS negotiation.
-
- 3 Log hexadecimal and ASCII dump of TLS negotiation process
-
- 4 Log hexadecimal and ASCII dump of complete transmission after STARTTLS
+ _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b
+ |L\bLe\bev\bve\bel\bl|P\bPo\bos\bst\btf\bfi\bix\bx 2\b2.\b.9\b9 a\ban\bnd\bd l\bla\bat\bte\ber\br |E\bEa\bar\brl\bli\bie\ber\br r\bre\bel\ble\bea\bas\bse\bes\bs.\b. |
+ |_\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
+ |0 |Log only a summary message on TLS |Disable logging of TLS activity.|
+ | |handshake completion -- no logging| |
+ | |of client certificate trust-chain | |
+ | |verification errors if client | |
+ | |certificate verification is not | |
+ | |required. | |
+ |_\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
+ |1 |Also log trust-chain verification |Also log TLS handshake and |
+ | |errors and peer certificate |certificate information. |
+ | |summary information. | |
+ |_\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
+ |2 |Also log levels during TLS negotiation. |
+ |_\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
+ |3 |Also log hexadecimal and ASCII dump of TLS negotiation process. |
+ |_\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
+ |4 |Also log hexadecimal and ASCII dump of complete transmission after |
+ | |STARTTLS. |
+ |_\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
Use log level 3 only in case of problems. Use of log level 4 is strongly
discouraged.
permit_tls_clientcerts
Allow the remote SMTP client request if the client certificate
- fingerprint is listed in the client certificate table (see
- relay_clientcerts discussion below).
+ 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
certificates to trusted clients (and not otherwise).
check_ccert_access type:table
- Use the remote SMTP client certificate fingerprint as the lookup key
- for the specified access(5) 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 construct the client certificate fingerprints is
+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.
Topics covered in this section:
- * TLS support in the LMTP delivery agent
- * Client-side certificate and private key configuration
+ * Configuring TLS in the SMTP/LMTP client
* Client-side TLS activity logging
+ * Client-side certificate and private key configuration
* Client-side TLS session cache
* Client TLS limitations
- * Configuring TLS in the SMTP/LMTP client
* Per-destination TLS policy
* Obsolete per-site TLS policy support
* Closing a DNS loophole with obsolete per-site TLS policies
* Client-side SMTPS support
* Miscellaneous client controls
+C\bCo\bon\bnf\bfi\big\bgu\bur\bri\bin\bng\bg T\bTL\bLS\bS i\bin\bn t\bth\bhe\be S\bSM\bMT\bTP\bP/\b/L\bLM\bMT\bTP\bP c\bcl\bli\bie\ben\bnt\bt
+
+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.
+
+n\bno\bon\bne\be
+ No TLS.
+m\bma\bay\by
+ Opportunistic TLS.
+e\ben\bnc\bcr\bry\byp\bpt\bt
+ Mandatory TLS encryption.
+f\bfi\bin\bng\bge\ber\brp\bpr\bri\bin\bnt\bt
+ Certificate fingerprint verification.
+v\bve\ber\bri\bif\bfy\by
+ Mandatory server certificate verification.
+s\bse\bec\bcu\bur\bre\be
+ Secure-channel TLS.
+
T\bTL\bLS\bS s\bsu\bup\bpp\bpo\bor\brt\bt i\bin\bn t\bth\bhe\be L\bLM\bMT\bTP\bP d\bde\bel\bli\biv\bve\ber\bry\by a\bag\bge\ben\bnt\bt
The smtp(8) and lmtp(8) delivery agents are implemented by a single dual-
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 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.
+to set the TLS verification nexthop and hostname.
-C\bCl\bli\bie\ben\bnt\bt-\b-s\bsi\bid\bde\be c\bce\ber\brt\bti\bif\bfi\bic\bca\bat\bte\be a\ban\bnd\bd p\bpr\bri\biv\bva\bat\bte\be k\bke\bey\by c\bco\bon\bnf\bfi\big\bgu\bur\bra\bat\bti\bio\bon\bn
+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.
-Do not configure Postfix SMTP client certificates unless you m\bmu\bus\bst\bt 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:
+N\bNo\bo T\bTL\bLS\bS e\ben\bnc\bcr\bry\byp\bpt\bti\bio\bon\bn
- 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 =
+At the "none" TLS security level, TLS encryption is disabled. This is the
+default security level. With Postfix 2.3 and later, it can be configured
+explicitly by setting "smtp_tls_security_level = none".
-The best way to use the default settings is to comment out the above parameters
-in main.cf if present.
+With Postfix 2.2 and earlier, or when smtp_tls_security_level is set to its
+default (backwards compatible) empty value, the appropriate configuration
+settings are "smtp_use_tls = no" and "smtp_enforce_tls = no". With either
+approach, TLS is not used even if supported by the server. For LMTP, use the
+corresponding "lmtp_" parameters.
-During TLS startup negotiation the Postfix SMTP client may present a
-certificate to the remote SMTP server. The Netscape client is rather clever
-here and lets the user select between only those certificates that match CA
-certificates offered by the remote SMTP server. As the Postfix SMTP client uses
-the "SSL_connect()" function from the OpenSSL package, this is not possible and
-we have to choose just one certificate. So for now the default is to use _no_
-certificate and key unless one is explicitly specified here.
+Per destination settings may override this default setting, in which case TLS
+is used selectively, only with destinations explicitly configured for TLS.
-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.
+You can disable TLS for a subset of destinations, while leaving it enabled for
+the rest. With the Postfix 2.3 and later TLS policy table, specify the "none"
+security level. With the obsolete per-site table, specify the "NONE" keyword.
-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.
+O\bOp\bpp\bpo\bor\brt\btu\bun\bni\bis\bst\bti\bic\bc T\bTL\bLS\bS
-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).
+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. With Postfix 2.3 and later,
+opportunistic TLS can be configured by setting "smtp_tls_security_level = may".
-Example: the certificate for "client.example.com" was issued by "intermediate
-CA" which itself has a certificate issued by "root CA". Create the client.pem
-file with:
+Since sending in the clear is acceptable, demanding stronger than default TLS
+security mostly reduces inter-operability. If you must restrict TLS protocol or
+cipher selection even with opportunistic TLS, the "smtp_tls_ciphers" and
+"smtp_tls_protocols" configuration parameters (Postfix >= 2.6) provide control
+over the protocols and cipher grade used with opportunistic TLS. With earlier
+releases the opportunistic TLS cipher grade is always "export" and no protocols
+are disabled.
- % c\bca\bat\bt c\bcl\bli\bie\ben\bnt\bt_\b_c\bce\ber\brt\bt.\b.p\bpe\bem\bm i\bin\bnt\bte\ber\brm\bme\bed\bdi\bia\bat\bte\be_\b_C\bCA\bA.\b.p\bpe\bem\bm >\b> c\bcl\bli\bie\ben\bnt\bt.\b.p\bpe\bem\bm
+With Postfix 2.2 and earlier, or when smtp_tls_security_level is set to its
+default (backwards compatible) empty value, the appropriate configuration
+settings are "smtp_use_tls = yes" and "smtp_enforce_tls = no". For LMTP use the
+corresponding "lmtp_" parameters.
-A Postfix SMTP client certificate supplied here must be usable as SSL client
-certificate and hence pass the "openssl verify -purpose sslclient ..." test.
+With opportunistic TLS, mail delivery continues even if the server certificate
+is untrusted or bears the wrong name. Starting with Postfix 2.3, when the TLS
+handshake fails for an opportunistic TLS session, rather than give up on mail
+delivery, the transaction is retried with TLS disabled. Trying an unencrypted
+connection makes it possible to deliver mail to sites with non-interoperable
+server TLS implementations.
-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 "client.pem" file reduces the overhead of the TLS exchange.
+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.
-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.
+You can enable opportunistic TLS just for selected destinations. With the
+Postfix 2.3 and later TLS policy table, specify the "may" security level. With
+the obsolete per-site table, specify the "MAY" keyword.
-RSA key and certificate examples:
+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_cert_file = /etc/postfix/client.pem
- smtp_tls_key_file = $smtp_tls_cert_file
+ smtp_tls_security_level = may
-Their DSA counterparts:
+Postfix 2.2 syntax:
/etc/postfix/main.cf:
- smtp_tls_dcert_file = /etc/postfix/client-dsa.pem
- smtp_tls_dkey_file = $smtp_tls_dcert_file
+ smtp_use_tls = yes
+ smtp_enforce_tls = no
-Their ECDSA counterparts (Postfix >= 2.6 + OpenSSL >= 0.9.9):
+M\bMa\ban\bnd\bda\bat\bto\bor\bry\by T\bTL\bLS\bS e\ben\bnc\bcr\bry\byp\bpt\bti\bio\bon\bn
- /etc/postfix/main.cf:
- smtp_tls_eccert_file = /etc/postfix/client-ecdsa.pem
- smtp_tls_eckey_file = $smtp_tls_eccert_file
+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. With Postfix 2.3 and later, 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.
-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:
+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.
- # $\b$O\bOP\bPE\bEN\bNS\bSS\bSL\bL_\b_H\bHO\bOM\bME\bE/\b/b\bbi\bin\bn/\b/c\bc_\b_r\bre\beh\bha\bas\bsh\bh /\b/p\bpa\bat\bth\bh/\b/t\bto\bo/\b/d\bdi\bir\bre\bec\bct\bto\bor\bry\by
+With Postfix 2.2 and earlier, or when smtp_tls_security_level is set to its
+default (backwards compatible) empty value, the appropriate configuration
+settings are "smtp_enforce_tls = yes" and "smtp_tls_enforce_peername = no". For
+LMTP use the corresponding "lmtp_" parameters.
-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.
+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. Most 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.
-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.
+You can enable mandatory TLS encryption just for specific destinations. With
+the Postfix 2.3 and later TLS policy table, specify the "encrypt" security
+level. With the obsolete per-site table, specify the "MUST_NOPEERMATCH"
+keyword. While the obsolete approach still works with Postfix 2.3, it is
+strongly discouraged: users of Postfix 2.3 and later should use the new TLS
+policy settings.
-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.
+Examples:
-Example:
+In the example below, traffic to example.com and its sub-domains via the
+corresponding MX hosts always uses TLS. The protocol version will be "SSLv3" or
+"TLSv1" (the default setting of smtp_tls_mandatory_protocols excludes "SSLv2").
+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_CAfile = /etc/postfix/CAcert.pem
- smtp_tls_CApath = /etc/postfix/certs
-
-C\bCl\bli\bie\ben\bnt\bt-\b-s\bsi\bid\bde\be T\bTL\bLS\bS a\bac\bct\bti\biv\bvi\bit\bty\by l\blo\bog\bgg\bgi\bin\bng\bg
+ smtp_tls_policy_maps = hash:/etc/postfix/tls_policy
-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.
-
- 0 Disable logging of TLS activity.
-
- 1 Log TLS handshake and certificate information.
-
- 2 Log levels during TLS negotiation.
-
- 3 Log hexadecimal and ASCII dump of TLS negotiation process
-
- 4 Log hexadecimal and ASCII dump of complete transmission after STARTTLS
-
-Example:
-
- /etc/postfix/main.cf:
- smtp_tls_loglevel = 0
-
-C\bCl\bli\bie\ben\bnt\bt-\b-s\bsi\bid\bde\be T\bTL\bLS\bS s\bse\bes\bss\bsi\bio\bon\bn c\bca\bac\bch\bhe\be
-
-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
-
-C\bCl\bli\bie\ben\bnt\bt T\bTL\bLS\bS l\bli\bim\bmi\bit\bta\bat\bti\bio\bon\bns\bs
-
-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.
-
-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. With Postfix 2.3, we make secure-channel
-configurations substantially easier to configure, but they 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 are new with Postfix 2.3, the issue was well understood before
-Postfix 1.0, when Lutz Jä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.
-
-C\bCo\bon\bnf\bfi\big\bgu\bur\bri\bin\bng\bg T\bTL\bLS\bS i\bin\bn t\bth\bhe\be S\bSM\bMT\bTP\bP/\b/L\bLM\bMT\bTP\bP c\bcl\bli\bie\ben\bnt\bt
-
-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.
-
-n\bno\bon\bne\be
- No TLS.
-m\bma\bay\by
- Opportunistic TLS.
-e\ben\bnc\bcr\bry\byp\bpt\bt
- Mandatory TLS encryption.
-f\bfi\bin\bng\bge\ber\brp\bpr\bri\bin\bnt\bt
- Certificate fingerprint verification.
-v\bve\ber\bri\bif\bfy\by
- Mandatory server certificate verification.
-s\bse\bec\bcu\bur\bre\be
- Secure-channel TLS.
-
-N\bNo\bo T\bTL\bLS\bS e\ben\bnc\bcr\bry\byp\bpt\bti\bio\bon\bn
-
-At the "none" TLS security level, TLS encryption is disabled. This is the
-default security level. With Postfix 2.3 and later, it can be configured
-explicitly by setting "smtp_tls_security_level = none".
-
-With Postfix 2.2 and earlier, or when smtp_tls_security_level is set to its
-default (backwards compatible) empty value, the appropriate configuration
-settings are "smtp_use_tls = no" and "smtp_enforce_tls = no". With either
-approach, TLS is not used even if supported by the server. For LMTP, use the
-corresponding "lmtp_" parameters.
-
-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 2.3 and later TLS policy table, specify the "none"
-security level. With the obsolete per-site table, specify the "NONE" keyword.
-
-O\bOp\bpp\bpo\bor\brt\btu\bun\bni\bis\bst\bti\bic\bc T\bTL\bLS\bS
-
-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. With Postfix 2.3 and later,
-opportunistic TLS can be configured by setting "smtp_tls_security_level = may".
-
-Since sending in the clear is acceptable, demanding stronger than default TLS
-security mostly reduces inter-operability. If you must restrict TLS protocol or
-cipher selection even with opportunistic TLS, the "smtp_tls_ciphers" and
-"smtp_tls_protocols" configuration parameters (Postfix >= 2.6) provide control
-over the protocols and cipher grade used with opportunistic TLS. With earlier
-releases the opportunistic TLS cipher grade is always "export" and no protocols
-are disabled.
-
-With Postfix 2.2 and earlier, or when smtp_tls_security_level is set to its
-default (backwards compatible) empty value, the appropriate configuration
-settings are "smtp_use_tls = yes" and "smtp_enforce_tls = no". For LMTP use the
-corresponding "lmtp_" parameters.
-
-With opportunistic TLS, mail delivery continues even if the server certificate
-is untrusted or bears the wrong name. Starting with Postfix 2.3, when the TLS
-handshake fails for an opportunistic TLS session, rather than give up on mail
-delivery, the transaction is retried 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 2.3 and later TLS policy table, specify the "may" security level. With
-the obsolete per-site table, specify the "MAY" keyword.
-
-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
-
-Postfix 2.2 syntax:
-
- /etc/postfix/main.cf:
- smtp_use_tls = yes
- smtp_enforce_tls = no
-
-M\bMa\ban\bnd\bda\bat\bto\bor\bry\by T\bTL\bLS\bS e\ben\bnc\bcr\bry\byp\bpt\bti\bio\bon\bn
-
-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. With Postfix 2.3 and later, 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.
-
-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.
-
-With Postfix 2.2 and earlier, or when smtp_tls_security_level is set to its
-default (backwards compatible) empty value, the appropriate configuration
-settings are "smtp_enforce_tls = yes" and "smtp_tls_enforce_peername = no". For
-LMTP use the corresponding "lmtp_" parameters.
-
-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. Most 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 2.3 and later TLS policy table, specify the "encrypt" security
-level. With the obsolete per-site table, specify the "MUST_NOPEERMATCH"
-keyword. While the obsolete approach still works with Postfix 2.3, it is
-strongly discouraged: users of Postfix 2.3 and later should use the new TLS
-policy settings.
-
-Examples:
-
-In the example below, traffic to example.com and its sub-domains via the
-corresponding MX hosts always uses TLS. The protocol version will be "SSLv3" or
-"TLSv1" (the default setting of smtp_tls_mandatory_protocols excludes "SSLv2").
-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
+ /etc/postfix/tls_policy:
+ example.com encrypt
+ .example.com encrypt
Postfix 2.2 syntax (no support for sub-domains without resorting to regexp
tables). With Postfix 2.3 and later, do not use the obsolete per-site table.
certificate authorities are used or required. The certificate trust chain,
expiration date, ... are not checked. Instead, the
smtp_tls_fingerprint_cert_match parameter or the "match" attribute in the
-policy table lists the valid "fingerprints" of the remote SMTP server
-certificate.
+policy table lists the remote SMTP server certificate fingerprint or public key
+fingerprint (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. This may be feasible for an SMTP "VPN" connecting a small
+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, p\bpr\bro\bov\bvi\bid\bde\bed\bd 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
"smtp_tls_security_level = secure". The smtp_tls_secure_cert_match parameter
can override the default "nexthop, dot-nexthop" certificate match strategy.
-With Postfix 2.2 and earlier, or when smtp_tls_security_level is set to its
-default (backwards compatible) empty value, the appropriate configuration
-settings are "smtp_enforce_tls = yes" and "smtp_tls_enforce_peername = yes"
-with additional settings to harden peer certificate verification against forged
-DNS data. For LMTP, use the corresponding "lmtp_" parameters.
+With Postfix 2.2 and earlier, or when smtp_tls_security_level is set to its
+default (backwards compatible) empty value, the appropriate configuration
+settings are "smtp_enforce_tls = yes" and "smtp_tls_enforce_peername = yes"
+with additional settings to harden peer certificate verification against forged
+DNS data. 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.
+
+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. Most 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 certificate 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 2.3 and later TLS policy table, specify the "secure" security level.
+With the obsolete per-site table, specify the "MUST" keyword and harden the
+certificate verification against DNS forgery. While the obsolete approach still
+works with Postfix 2.3, it is strongly discouraged: users of Postfix 2.3 and
+later should use the new TLS policy settings.
+
+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. This
+secure-channel configuration can also be implemented via a hardened variant of
+the MUST policy in the obsolete per-site table. As stated above, this approach
+has the potential to mis-deliver email if the related domains change hands.
+
+ /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
+
+Postfix 2.2.9 and later syntax:
+
+N\bNo\bot\bte\be:\b: Avoid policy lookups with the bare hostname (for example,
+"tls.example.com"). Instead, use the destination (for example, "
+[tls.example.com]") as the per-site table lookup key (a recipient domain or MX-
+enabled transport nexthop with no port suffix may look like a bare hostname,
+but is still a suitable destination). With Postfix 2.3 and later, do not use
+the obsolete per-site table; use the new policy table instead.
+
+ /etc/postfix/main.cf:
+ smtp_cname_overrides_servername = no
+ smtp_tls_CAfile = /etc/postfix/CAfile.pem
+ transport_maps = hash:/etc/postfix/transport
+ smtp_tls_per_site = hash:/etc/postfix/tls_per_site
+
+ /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_per_site:
+ [tls.example.com] MUST
+
+C\bCl\bli\bie\ben\bnt\bt-\b-s\bsi\bid\bde\be T\bTL\bLS\bS a\bac\bct\bti\biv\bvi\bit\bty\by l\blo\bog\bgg\bgi\bin\bng\bg
+
+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.
+
+ _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b
+ |L\bLe\bev\bve\bel\bl|P\bPo\bos\bst\btf\bfi\bix\bx 2\b2.\b.9\b9 a\ban\bnd\bd l\bla\bat\bte\ber\br |E\bEa\bar\brl\bli\bie\ber\br r\bre\bel\ble\bea\bas\bse\bes\bs.\b. |
+ |_\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
+ |0 |Log only a summary message on TLS |Disable logging of TLS activity.|
+ | |handshake completion -- no logging| |
+ | |of remote SMTP server certificate | |
+ | |trust-chain verification errors if| |
+ | |server certificate verification is| |
+ | |not required. | |
+ |_\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
+ |1 |Also log remote SMTP server trust-|Also log TLS handshake and |
+ | |chain verification errors and peer|certificate information. |
+ | |certificate summary information. | |
+ |_\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
+ |2 |Also log levels during TLS negotiation. |
+ |_\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
+ |3 |Also log hexadecimal and ASCII dump of TLS negotiation process. |
+ |_\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
+ |4 |Also log hexadecimal and ASCII dump of complete transmission after |
+ | |STARTTLS. |
+ |_\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
+
+Example:
+
+ /etc/postfix/main.cf:
+ smtp_tls_loglevel = 0
+
+C\bCl\bli\bie\ben\bnt\bt-\b-s\bsi\bid\bde\be c\bce\ber\brt\bti\bif\bfi\bic\bca\bat\bte\be a\ban\bnd\bd p\bpr\bri\biv\bva\bat\bte\be k\bke\bey\by c\bco\bon\bnf\bfi\big\bgu\bur\bra\bat\bti\bio\bon\bn
+
+Do not configure Postfix SMTP client certificates unless you m\bmu\bus\bst\bt 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 =
+
+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. The Netscape client is rather clever
+here and lets the user select between only those certificates that match CA
+certificates offered by the remote SMTP server. As the Postfix SMTP client uses
+the "SSL_connect()" function from the OpenSSL package, this is not possible and
+we have to choose just one certificate. So for now the default is to use _no_
+certificate and key unless one is explicitly specified here.
+
+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.
+
+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". Create the client.pem
+file with:
+
+ % c\bca\bat\bt c\bcl\bli\bie\ben\bnt\bt_\b_c\bce\ber\brt\bt.\b.p\bpe\bem\bm i\bin\bnt\bte\ber\brm\bme\bed\bdi\bia\bat\bte\be_\b_C\bCA\bA.\b.p\bpe\bem\bm >\b> c\bcl\bli\bie\ben\bnt\bt.\b.p\bpe\bem\bm
+
+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 "client.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.
+
+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 >= 0.9.9):
+
+ /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:
+
+ # $\b$O\bOP\bPE\bEN\bNS\bSS\bSL\bL_\b_H\bHO\bOM\bME\bE/\b/b\bbi\bin\bn/\b/c\bc_\b_r\bre\beh\bha\bas\bsh\bh /\b/p\bpa\bat\bth\bh/\b/t\bto\bo/\b/d\bdi\bir\bre\bec\bct\bto\bor\bry\by
+
+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.
-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.
+Example:
-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. Most 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 certificate authority. On a machine
-that delivers mail to the Internet, you should not configure secure TLS
-verification as a default policy.
+ /etc/postfix/main.cf:
+ smtp_tls_CAfile = /etc/postfix/CAcert.pem
+ smtp_tls_CApath = /etc/postfix/certs
-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.
+C\bCl\bli\bie\ben\bnt\bt-\b-s\bsi\bid\bde\be T\bTL\bLS\bS s\bse\bes\bss\bsi\bio\bon\bn c\bca\bac\bch\bhe\be
-You can enable secure TLS verification just for specific destinations. With the
-Postfix 2.3 and later TLS policy table, specify the "secure" security level.
-With the obsolete per-site table, specify the "MUST" keyword and harden the
-certificate verification against DNS forgery. While the obsolete approach still
-works with Postfix 2.3, it is strongly discouraged: users of Postfix 2.3 and
-later should use the new TLS policy settings.
+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.
-Examples:
+Example:
-Secure-channel TLS without transport(5) table overrides:
+ /etc/postfix/main.cf:
+ smtp_tls_session_cache_database = btree:/var/lib/postfix/smtp_scache
-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.
+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.
-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.
+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.
-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.
+Example:
/etc/postfix/main.cf:
- smtp_tls_CAfile = /etc/postfix/CAfile.pem
- smtp_tls_policy_maps = hash:/etc/postfix/tls_policy
-
- /etc/postfix/transport:
+ smtp_tls_session_cache_timeout = 3600s
- /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
+C\bCl\bli\bie\ben\bnt\bt T\bTL\bLS\bS l\bli\bim\bmi\bit\bta\bat\bti\bio\bon\bns\bs
-Secure-channel TLS with transport(5) table overrides:
+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.
-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. This
-secure-channel configuration can also be implemented via a hardened variant of
-the MUST policy in the obsolete per-site table. As stated above, this approach
-has the potential to mis-deliver email if the related domains change hands.
+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.
- /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
+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.
- /etc/postfix/transport:
- example.com smtp:[tls.example.com]
- example.co.uk smtp:[tls.example.com]
- example.co.jp smtp:[tls.example.com]
+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.
- /etc/postfix/tls_policy:
- [tls.example.com] secure match=tls.example.com
+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.
-Postfix 2.2.9 and later syntax:
+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.
-N\bNo\bot\bte\be:\b: Avoid policy lookups with the bare hostname (for example,
-"tls.example.com"). Instead, use the destination (for example, "
-[tls.example.com]") as the per-site table lookup key (a recipient domain or MX-
-enabled transport nexthop with no port suffix may look like a bare hostname,
-but is still a suitable destination). With Postfix 2.3 and later, do not use
-the obsolete per-site table; use the new policy table instead.
+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.
- /etc/postfix/main.cf:
- smtp_cname_overrides_servername = no
- smtp_tls_CAfile = /etc/postfix/CAfile.pem
- transport_maps = hash:/etc/postfix/transport
- smtp_tls_per_site = hash:/etc/postfix/tls_per_site
+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. With Postfix 2.3, we make secure-channel
+configurations substantially easier to configure, but they 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.
- /etc/postfix/transport:
- example.com smtp:[tls.example.com]
- example.co.uk smtp:[tls.example.com]
- example.co.jp smtp:[tls.example.com]
+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.
- /etc/postfix/tls_per_site:
- [tls.example.com] MUST
+Historical note: while the documentation of these issues and many of the
+related features are new with Postfix 2.3, the issue was well understood before
+Postfix 1.0, when Lutz Jä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.
T\bTL\bLS\bS p\bpo\bol\bli\bic\bcy\by t\bta\bab\bbl\ble\be
At this security level, there are no trusted certificate authorities. The
certificate trust chain, expiration date, ... are not checked. Instead, the
optional m\bma\bat\btc\bch\bh attribute, or else the main.cf
- s\bsm\bmt\btp\bp_\b_t\btl\bls\bs_\b_f\bfi\bin\bng\bge\ber\brp\bpr\bri\bin\bnt\bt_\b_c\bce\ber\brt\bt_\b_m\bma\bat\btc\bch\bh parameter, lists the valid fingerprints of
- the server certificate. The digest algorithm used to calculate fingerprints
- is selected by the s\bsm\bmt\btp\bp_\b_t\btl\bls\bs_\b_f\bfi\bin\bng\bge\ber\brp\bpr\bri\bin\bnt\bt_\b_d\bdi\big\bge\bes\bst\bt 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.
+ s\bsm\bmt\btp\bp_\b_t\btl\bls\bs_\b_f\bfi\bin\bng\bge\ber\brp\bpr\bri\bin\bnt\bt_\b_c\bce\ber\brt\bt_\b_m\bma\bat\btc\bch\bh 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
+ s\bsm\bmt\btp\bp_\b_t\btl\bls\bs_\b_f\bfi\bin\bng\bge\ber\brp\bpr\bri\bin\bnt\bt_\b_d\bdi\big\bge\bes\bst\bt 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.
v\bve\ber\bri\bif\bfy\by
Mandatory server certificate verification. Mail is delivered only if the
TLS handshake succeeds, if the remote SMTP server certificate can be
# Obsolete, but still supported
smtpd_use_tls = yes
+B\bBu\bui\bil\bld\bdi\bin\bng\bg P\bPo\bos\bst\btf\bfi\bix\bx w\bwi\bit\bth\bh T\bTL\bLS\bS s\bsu\bup\bpp\bpo\bor\brt\bt
+
+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.
+
+N\bNO\bOT\bTE\bE:\b: D\bDo\bo n\bno\bot\bt u\bus\bse\be G\bGn\bnu\bu T\bTL\bLS\bS.\b. I\bIt\bt w\bwi\bil\bll\bl s\bsp\bpo\bon\bnt\bta\ban\bne\beo\bou\bus\bsl\bly\by t\bte\ber\brm\bmi\bin\bna\bat\bte\be a\ba P\bPo\bos\bst\btf\bfi\bix\bx d\bda\bae\bem\bmo\bon\bn
+p\bpr\bro\boc\bce\bes\bss\bs w\bwi\bit\bth\bh e\bex\bxi\bit\bt s\bst\bta\bat\btu\bus\bs c\bco\bod\bde\be 2\b2,\b, i\bin\bns\bst\bte\bea\bad\bd o\bof\bf a\bal\bll\blo\bow\bwi\bin\bng\bg P\bPo\bos\bst\btf\bfi\bix\bx t\bto\bo 1\b1)\b) r\bre\bep\bpo\bor\brt\bt t\bth\bhe\be
+e\ber\brr\bro\bor\br t\bto\bo t\bth\bhe\be m\bma\bai\bil\bll\blo\bog\bg f\bfi\bil\ble\be,\b, a\ban\bnd\bd t\bto\bo 2\b2)\b) p\bpr\bro\bov\bvi\bid\bde\be p\bpl\bla\bai\bin\bnt\bte\bex\bxt\bt s\bse\ber\brv\bvi\bic\bce\be w\bwh\bhe\ber\bre\be t\bth\bhi\bis\bs i\bis\bs
+a\bap\bpp\bpr\bro\bop\bpr\bri\bia\bat\bte\be.\b.
+
+ * 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:
+
+ % m\bma\bak\bke\be t\bti\bid\bdy\by # if you have left-over files from a previous build
+ % m\bma\bak\bke\be m\bma\bak\bke\bef\bfi\bil\ble\bes\bs C\bCC\bCA\bAR\bRG\bGS\bS=\b="\b"-\b-D\bDU\bUS\bSE\bE_\b_T\bTL\bLS\bS"\b" A\bAU\bUX\bXL\bLI\bIB\bBS\bS=\b="\b"-\b-l\bls\bss\bsl\bl -\b-l\blc\bcr\bry\byp\bpt\bto\bo"\b"
+
+ * 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:
+
+ % m\bma\bak\bke\be t\bti\bid\bdy\by # if you have left-over files from a previous build
+ % m\bma\bak\bke\be m\bma\bak\bke\bef\bfi\bil\ble\bes\bs C\bCC\bCA\bAR\bRG\bGS\bS=\b="\b"-\b-D\bDU\bUS\bSE\bE_\b_T\bTL\bLS\bS -\b-I\bI/\b/u\bus\bsr\br/\b/l\blo\boc\bca\bal\bl/\b/i\bin\bnc\bcl\blu\bud\bde\be"\b" \\b\
+ A\bAU\bUX\bXL\bLI\bIB\bBS\bS=\b="\b"-\b-L\bL/\b/u\bus\bsr\br/\b/l\blo\boc\bca\bal\bl/\b/l\bli\bib\bb -\b-l\bls\bss\bsl\bl -\b-l\blc\bcr\bry\byp\bpt\bto\bo"\b"
+
+ On Solaris, specify the -R option as shown below:
+
+ % m\bma\bak\bke\be t\bti\bid\bdy\by # if you have left-over files from a previous build
+ % m\bma\bak\bke\be m\bma\bak\bke\bef\bfi\bil\ble\bes\bs C\bCC\bCA\bAR\bRG\bGS\bS=\b="\b"-\b-D\bDU\bUS\bSE\bE_\b_T\bTL\bLS\bS -\b-I\bI/\b/u\bus\bsr\br/\b/l\blo\boc\bca\bal\bl/\b/i\bin\bnc\bcl\blu\bud\bde\be"\b" \\b\
+ A\bAU\bUX\bXL\bLI\bIB\bBS\bS=\b="\b"-\b-R\bR/\b/u\bus\bsr\br/\b/l\blo\boc\bca\bal\bl/\b/l\bli\bib\bb -\b-L\bL/\b/u\bus\bsr\br/\b/l\blo\boc\bca\bal\bl/\b/l\bli\bib\bb -\b-l\bls\bss\bsl\bl -\b-l\blc\bcr\bry\byp\bpt\bto\bo"\b"
+
+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:
+
+ % m\bma\bak\bke\be t\bti\bid\bdy\by # if you have left-over files from a previous build
+ % m\bma\bak\bke\be m\bma\bak\bke\bef\bfi\bil\ble\bes\bs C\bCC\bCA\bAR\bRG\bGS\bS=\b="\b"-\b-D\bDU\bUS\bSE\bE_\b_T\bTL\bLS\bS \\b\
+ (\b(o\bot\bth\bhe\ber\br -\b-D\bD o\bor\br -\b-I\bI o\bop\bpt\bti\bio\bon\bns\bs)\b)"\b" \\b\
+ A\bAU\bUX\bXL\bLI\bIB\bBS\bS=\b="\b"-\b-l\bls\bss\bsl\bl -\b-l\blc\bcr\bry\byp\bpt\bto\bo \\b\
+ (\b(o\bot\bth\bhe\ber\br -\b-l\bl o\bop\bpt\bti\bio\bon\bns\bs f\bfo\bor\br l\bli\bib\bbr\bra\bar\bri\bie\bes\bs i\bin\bn /\b/u\bus\bsr\br/\b/l\bli\bib\bb)\b) \\b\
+ (\b(-\b-L\bL/\b/p\bpa\bat\bth\bh/\b/n\bna\bam\bme\be +\b+ -\b-l\bl o\bop\bpt\bti\bio\bon\bns\bs f\bfo\bor\br o\bot\bth\bhe\ber\br l\bli\bib\bbr\bra\bar\bri\bie\bes\bs)\b)"\b"
+
+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.
+
R\bRe\bep\bpo\bor\brt\bti\bin\bng\bg p\bpr\bro\bob\bbl\ble\bem\bms\bs
Problems are preferably reported via <postfix-users@postfix.org>. See http://
If you upgrade from Postfix 2.7 or earlier, read RELEASE_NOTES-2.8
before proceeding.
+Incompatible changes with snapshot 20111205
+===========================================
+
+Postfix now logs the result of succesful TLS negotiation with TLS
+logging levels of 0. See the smtp_tls_loglevel and smtpd_tls_loglevel
+descriptions in the postconf(5) manpage for other minor differences.
+
+Major changes with snapshot 20111205
+====================================
+
+Support for TLS public key fingerprint matching in the Postfix SMTP
+client (in smtp_tls_policy_maps) and server (in check_ccert access
+maps). Public key fingerprints are inherently more specific than
+fingerprints over the entire certificate.
+
+Revision of Postfix TLS logging. The main difference is that Postfix
+now logs the result of succesful TLS negotiation with TLS logging
+levels of 0. See the smtp_tls_loglevel and smtpd_tls_loglevel
+descriptions in the postconf(5) manpage for other minor differences.
+
Major changes with snapshot 20111203
====================================
Things to do after the stable release:
- TLS_README has the priorities reversed. The section about
- SMTP client settings begins with an exposition about client
- certificates, which almost no-one needs. Instead, the text
- should first explain how to turn on opportunistic TLS. After
- that, it can discuss the gory details of higher security
- levels for the few people who need it.
-
- make address_verify_sender dynamic so it won't work
- with address harvesters.
-
Investigate viability of memcached for applications
that require performance for low-security operations
such as sharing the postscreen cache.
etrn_domain=
<b>Postfix version 2.5 and later:</b>
stress=
+<b>Postfix version 2.9 and later:</b>
+ccert_pubkey_fingerprint=68:B3:29:DA:98:93:E3:40:99:C7:D8:AD:5C:B9:C9:40
[empty line]
</pre>
</blockquote>
<li><a href="#how">How Postfix TLS support works</a>
-<li><a href="#build_tls">Building Postfix with TLS support</a>
-
<li><a href="#server_tls">SMTP Server specific settings</a>
<li> <a href="#client_tls">SMTP Client specific settings</a>
<li><a href="#tlsmgr_controls"> TLS manager specific settings </a>
+<li><a href="#build_tls">Building Postfix with TLS support</a>
+
<li><a href="#problems"> Reporting problems </a>
<li><a href="#credits"> Credits </a>
</table>
-<h2><a name="build_tls">Building Postfix with TLS support</a></h2>
-
-<p> These instructions assume that you build Postfix from source
-code as described in the <a href="INSTALL.html">INSTALL</a> document. Some modification may
-be required if you build Postfix from a vendor-specific source
-package. </p>
-
-<p> To build Postfix with TLS support, first we need to generate
-the <tt>make(1)</tt> files with the necessary definitions. This is
-done by invoking the command "<tt>make makefiles</tt>" in the Postfix
-top-level directory and with arguments as shown next. </p>
-
-<p> <b> NOTE: Do not use Gnu TLS. It will spontaneously terminate
-a Postfix daemon process with exit status code 2, instead of allowing
-Postfix to 1) report the error to the maillog file, and to 2) provide
-plaintext service where this is appropriate. </b> </p>
-
-<ul>
-
-<li> <p> If the OpenSSL include files (such as <tt>ssl.h</tt>) are
-in directory <tt>/usr/include/openssl</tt>, and the OpenSSL libraries
-(such as <tt>libssl.so</tt> and <tt>libcrypto.so</tt>) are in
-directory <tt>/usr/lib</tt>: </p>
-
-<blockquote>
-<pre>
-% <b>make tidy</b> # if you have left-over files from a previous build
-% <b>make makefiles CCARGS="-DUSE_TLS" AUXLIBS="-lssl -lcrypto"</b>
-</pre>
-</blockquote>
-
-<li> <p> If the OpenSSL include files (such as <tt>ssl.h</tt>) are
-in directory <tt>/usr/local/include/openssl</tt>, and the OpenSSL
-libraries (such as <tt>libssl.so</tt> and <tt>libcrypto.so</tt>)
-are in directory <tt>/usr/local/lib</tt>: </p>
-
-<blockquote>
-<pre>
-% <b>make tidy</b> # if you have left-over files from a previous build
-% <b>make makefiles CCARGS="-DUSE_TLS -I/usr/local/include" \
- AUXLIBS="-L/usr/local/lib -lssl -lcrypto" </b>
-</pre>
-</blockquote>
-
-<p> On Solaris, specify the <tt>-R</tt> option as shown below:
-
-<blockquote>
-<pre>
-% <b>make tidy</b> # if you have left-over files from a previous build
-% <b>make makefiles CCARGS="-DUSE_TLS -I/usr/local/include" \
- AUXLIBS="-R/usr/local/lib -L/usr/local/lib -lssl -lcrypto" </b>
-</pre>
-</blockquote>
-
-</ul>
-
-<p> 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 "<tt>make makefiles</tt>"
-instructions with the instructions above: </p>
-
-<blockquote>
-<pre>
-% <b>make tidy</b> # if you have left-over files from a previous build
-% <b>make makefiles CCARGS="-DUSE_TLS \
- <i>(other -D or -I options)</i>" \
- AUXLIBS="-lssl -lcrypto \
- <i>(other -l options for libraries in /usr/lib)</i> \
- <i>(-L/path/name + -l options for other libraries)</i>"</b>
-</pre>
-</blockquote>
-
-<p> To complete the build process, see the Postfix <a href="INSTALL.html">INSTALL</a>
-instructions. Postfix has TLS support turned off by default, so
-you can start using Postfix as soon as it is installed. </p>
-
<h2><a name="server_tls">SMTP Server specific settings</a></h2>
<p> Topics covered in this section: </p>
<blockquote>
-<table>
+<table border="1">
+
+<tr> <th> Level </th> <th> Postfix 2.9 and later</th> <th> Earlier
+releases. </th> </tr>
-<tr> <td> 0 </td> <td> Disable logging of TLS activity.</td> </tr>
+<tr> <td valign="top"> 0 </td> <td valign="top"> Log only a summary
+message on TLS handshake completion — no logging of client
+certificate trust-chain verification errors if client certificate
+verification is not required. </td> <td valign="top"> Disable logging
+of TLS activity.</td> </tr>
-<tr> <td> 1 </td> <td> Log TLS handshake and certificate information.
+<tr> <td valign="top"> 1 </td> <td valign="top"> Also log trust-chain
+verification errors and peer certificate summary information. </td>
+<td valign="top"> Also log TLS handshake and certificate information.
</td> </tr>
-<tr> <td> 2 </td> <td> Log levels during TLS negotiation. </td>
-</tr>
+<tr> <td valign="top"> 2 </td> <td valign="top" colspan="2"> Also
+log levels during TLS negotiation. </td> </tr>
-<tr> <td> 3 </td> <td> Log hexadecimal and ASCII dump of TLS
-negotiation process </td> </tr>
+<tr> <td valign="top"> 3 </td> <td valign="top" colspan="2"> Also
+log hexadecimal and ASCII dump of TLS negotiation process. </td>
+</tr>
-<tr> <td> 4 </td> <td> Log hexadecimal and ASCII dump of complete
-transmission after STARTTLS </td> </tr>
+<tr> <td valign="top"> 4 </td> <td valign="top" colspan="2"> Also
+log hexadecimal and ASCII dump of complete transmission after
+STARTTLS. </td></tr>
</table>
<dl>
-<dt> <a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a> </dt> <dd> <p> Allow the remote SMTP client
-request if the client certificate fingerprint is listed in the
-client certificate table (see <a href="postconf.5.html#relay_clientcerts">relay_clientcerts</a> discussion below). </p>
-</dd>
+<dt> <a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a> </dt> <dd> <p> 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 <a href="postconf.5.html#relay_clientcerts">relay_clientcerts</a> discussion below).
+</p> </dd>
<dt> <a href="postconf.5.html#permit_tls_all_clientcerts">permit_tls_all_clientcerts</a> </dt> <dd> <p> 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). </p> </dd>
-<dt> <a href="postconf.5.html#check_ccert_access">check_ccert_access</a> <a href="DATABASE_README.html">type:table</a></dt> <dd> <p> Use the remote SMTP
-client
-
certificate fingerprint as the lookup key for the specified <a href="access.5.html">access(5)</a>
+<dt> <a href="postconf.5.html#check_ccert_access">check_ccert_access</a> <a href="DATABASE_README.html">type:table</a></dt> <dd> <p> Use the remote
+SMTP client certificate fingerprint or public key fingerprint
+
(Postfix 2.9 and later) as the lookup key for the specified <a href="access.5.html">access(5)</a>
table. </p> </dd>
</dl>
</blockquote>
-<p> The digest algorithm used to construct the client certificate
+<p> The digest algorithm used to compute the client certificate
fingerprints is specified with the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtpd_tls_fingerprint_digest">smtpd_tls_fingerprint_digest</a>
parameter. The default is "md5", for compatibility with Postfix
versions < 2.5. </p>
<ul>
-<li><a href="#client_lmtp_tls"> TLS support in the LMTP delivery agent </a>
+<li><a href="#client_tls_levels"> Configuring TLS in the SMTP/LMTP client </a>
+
+<li><a href="#client_logging"> Client-side TLS activity logging </a>
<li><a href="#client_cert_key">Client-side certificate and private
key configuration </a>
-<li><a href="#client_logging"> Client-side TLS activity logging
-</a>
-
<li><a href="#client_tls_cache">Client-side TLS session cache</a>
<li><a href="#client_tls_limits"> Client TLS limitations </a>
-<li><a href="#client_tls_levels"> Configuring TLS in the SMTP/LMTP client </a>
-
<li><a href="#client_tls_policy"> Per-destination TLS policy </a>
<li><a href="#client_tls_obs"> Obsolete per-site TLS policy support </a>
</ul>
-<h3><a name="client_lmtp_tls"> TLS support in the LMTP delivery agent </a>
+<h3><a name="client_tls_levels"> Configuring TLS in the SMTP/LMTP client </a>
</h3>
+<p> 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.</p>
+
+<dl>
+<dt><b>none</b></dt>
+<dd><a href="#client_tls_none">No TLS.</a></dd>
+<dt><b>may</b></dt>
+<dd><a href="#client_tls_may">Opportunistic TLS.</a></dd>
+<dt><b>encrypt</b></dt>
+<dd><a href="#client_tls_encrypt">Mandatory TLS encryption.</a>
+<dt><b>fingerprint</b></dt>
+<dd><a href="#client_tls_fprint">Certificate fingerprint verification.</a>
+<dt><b>verify</b></dt>
+<dd><a href="#client_tls_verify">Mandatory server certificate verification.</a>
+<dt><b>secure</b></dt>
+<dd><a href="#client_tls_secure">Secure-channel TLS.</a>
+</dl>
+
+<h4><a name="client_lmtp_tls"> TLS support in the LMTP delivery agent </a> </h4>
+
<p> The <a href="smtp.8.html">smtp(8)</a> and <a href="lmtp.8.html">lmtp(8)</a> delivery agents are implemented by a
single dual-purpose program. Specifically, all the TLS features
described below apply
on UNIX-domain sockets. When server certificate verification is enabled
and the server is listening on a UNIX-domain socket, the $<a href="postconf.5.html#myhostname">myhostname</a>
parameter is used to set the TLS verification <i>nexthop</i> and
-<i>hostname</i>. Note, opportunistic encryption of LMTP traffic over
-UNIX-domain sockets is futile. TLS is only useful in this context when
+<i>hostname</i>. </p>
+
+<p> 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. </p>
-<h3><a name="client_cert_key">Client-side certificate and private
-key configuration </a> </h3>
+<h4><a name="client_tls_none"> No TLS encryption </a> </h4>
-<p> Do not configure Postfix SMTP client certificates unless you <b>must</b>
-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: </p>
+<p> At the "none" TLS security level, TLS encryption is
+disabled. This is the default security level. With Postfix 2.3 and later,
+it can be configured explicitly by setting "<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = none". </p>
-<blockquote>
-<pre>
- <a href="postconf.5.html#smtp_tls_cert_file">smtp_tls_cert_file</a> =
- <a href="postconf.5.html#smtp_tls_dcert_file">smtp_tls_dcert_file</a> =
- <a href="postconf.5.html#smtp_tls_key_file">smtp_tls_key_file</a> =
- <a href="postconf.5.html#smtp_tls_dkey_file">smtp_tls_dkey_file</a> =
- # Postfix ≥ 2.6
- <a href="postconf.5.html#smtp_tls_eccert_file">smtp_tls_eccert_file</a> =
- <a href="postconf.5.html#smtp_tls_eckey_file">smtp_tls_eckey_file</a> =
-</pre>
-</blockquote>
+<p> With Postfix 2.2 and earlier, or when <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> is set to
+its default (backwards compatible) empty value, the appropriate configuration
+settings are "<a href="postconf.5.html#smtp_use_tls">smtp_use_tls</a> = no" and "<a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> = no".
+With either approach, TLS is not used even if supported by the server.
+For LMTP, use the corresponding "lmtp_" parameters. </p>
-<p> The best way to use the default settings is to comment out the above
-parameters in <a href="postconf.5.html">main.cf</a> if present. </p>
+<p> Per destination settings may override this default setting, in which case
+TLS is used selectively, only with destinations explicitly configured
+for TLS. </p>
-<p> During TLS startup negotiation the Postfix SMTP client may present
-a certificate to the remote SMTP server. The Netscape client is
-rather clever here and lets the user select between only those
-certificates that match CA certificates offered by the remote SMTP
-server. As the Postfix SMTP client uses the "SSL_connect()" function
-from the OpenSSL package, this is not possible and we have to choose
-just one certificate. So for now the default is to use _no_
-certificate and key unless one is explicitly specified here. </p>
+<p> You can disable TLS for a subset of destinations, while leaving
+it enabled for the rest. With the Postfix 2.3 and later TLS <a
+href="#client_tls_policy">policy table</a>, specify the "none"
+security level. With the obsolete <a href="#client_tls_obs">per-site</a>
+table, specify the "NONE" keyword. </p>
-<p> 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. </p>
+<h4><a name="client_tls_may"> Opportunistic TLS </a> </h4>
-<p> 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. </p>
+<p> At the "may" TLS security level, TLS encryption is <i>opportunistic</i>.
+The SMTP transaction is encrypted if the STARTTLS ESMTP feature
+is supported by the server. Otherwise, messages are sent in the clear.
+With Postfix 2.3 and later, opportunistic TLS can be configured by
+setting "<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = may".
-<p> 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). </p>
+<p> Since sending in the clear is acceptable, demanding stronger
+than default TLS security mostly reduces inter-operability. If you
+must restrict TLS protocol or cipher selection even with opportunistic
+TLS, the "<a href="postconf.5.html#smtp_tls_ciphers">smtp_tls_ciphers</a>" and "<a href="postconf.5.html#smtp_tls_protocols">smtp_tls_protocols</a>" configuration
+parameters (Postfix ≥ 2.6) provide control over the protocols
+and cipher grade
+used with opportunistic TLS. With earlier releases the opportunistic TLS
+cipher grade is always "export" and no protocols are disabled. </p>
-<p> Example: the certificate for "client.example.com" was issued by
-"intermediate CA" which itself has a certificate issued by "root CA".
-Create the client.pem file with: </p>
+<p> With Postfix 2.2 and earlier, or when <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> is
+set to its default (backwards compatible) empty value, the appropriate
+configuration settings are "<a href="postconf.5.html#smtp_use_tls">smtp_use_tls</a> = yes" and
+"<a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> = no".
+For LMTP use the corresponding "lmtp_" parameters. </p>
-<blockquote>
-<pre>
-% <b>cat client_cert.pem intermediate_CA.pem > client.pem </b>
-</pre>
-</blockquote>
+<p> With opportunistic TLS, mail delivery continues even if the
+server certificate is untrusted or bears the wrong name. Starting
+with Postfix 2.3, when the TLS handshake fails for an opportunistic
+TLS session, rather than give up on mail delivery, the transaction
+is retried with TLS disabled. Trying an unencrypted connection makes
+it possible to deliver mail to sites with non-interoperable server
+TLS implementations. </p>
-<p> A Postfix SMTP client certificate supplied here must be usable
-as SSL client certificate and hence pass the "openssl verify -purpose
-sslclient ..." test. </p>
+<p> 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
+<a href="#client_tls_encrypt">encrypt</a> security level or higher.
+Attempts to configure opportunistic encryption of LMTP sessions will
+be ignored with a warning written to the mail logs. </p>
-<p> 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 "client.pem" file reduces
-the overhead of the TLS exchange. </p>
+<p> You can enable opportunistic TLS just for selected destinations. With
+the Postfix 2.3 and later TLS <a href="#client_tls_policy">policy table</a>,
+specify the "may" security level. With the obsolete <a
+href="#client_tls_obs">per-site</a> table, specify the "MAY" keyword.</p>
-<p> If you want the Postfix SMTP client to accept remote SMTP server
-certificates issued by these CAs, append the root certificate to
-$<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> or install it in the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> directory. </p>
+<p> 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 <a href="#client_tls_limits">limitations</a> above. </p>
+
+<p> Example: </p>
-<p> RSA key and certificate examples: </p>
-
<blockquote>
<pre>
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtp_tls_cert_file">smtp_tls_cert_file</a> = /etc/postfix/client.pem
- <a href="postconf.5.html#smtp_tls_key_file">smtp_tls_key_file</a> = $<a href="postconf.5.html#smtp_tls_cert_file">smtp_tls_cert_file</a>
+ <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = may
</pre>
</blockquote>
-<p> Their DSA counterparts: </p>
+<p> Postfix 2.2 syntax: </p>
<blockquote>
<pre>
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtp_tls_dcert_file">smtp_tls_dcert_file</a> = /etc/postfix/client-dsa.pem
- <a href="postconf.5.html#smtp_tls_dkey_file">smtp_tls_dkey_file</a> = $<a href="postconf.5.html#smtp_tls_dcert_file">smtp_tls_dcert_file</a>
-</pre>
+ <a href="postconf.5.html#smtp_use_tls">smtp_use_tls</a> = yes
+ <a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> = no
+</pre>
</blockquote>
-<p> Their ECDSA counterparts (Postfix ≥ 2.6 + OpenSSL ≥ 0.9.9): </p>
-
-<blockquote>
-<pre>
-/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtp_tls_eccert_file">smtp_tls_eccert_file</a> = /etc/postfix/client-ecdsa.pem
- <a href="postconf.5.html#smtp_tls_eckey_file">smtp_tls_eckey_file</a> = $<a href="postconf.5.html#smtp_tls_eccert_file">smtp_tls_eccert_file</a>
-</pre>
-</blockquote>
-
-<p> 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 $<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> or in multiple files, one CA per file in
-the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> directory. If you use a directory, don't forget
-to create the necessary "hash" links with: </p>
-
-<blockquote>
-<pre>
-# <b>$OPENSSL_HOME/bin/c_rehash <i>/path/to/directory</i> </b>
-</pre>
-</blockquote>
-
-<p> The $<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> 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. </p>
-
-<p> Additional trusted CAs can be specified via the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a>
-directory, in which case the certificates are read (with $<a href="postconf.5.html#mail_owner">mail_owner</a>
-privileges) from the files in the directory when the information
-is needed. Thus, the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> directory needs to be accessible
-inside the optional chroot jail. </p>
-
-<p> The choice between $<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> and $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> 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. </p>
-
-<p> Example: </p>
-
-<blockquote>
-<pre>
-/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = /etc/postfix/CAcert.pem
- <a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> = /etc/postfix/certs
-</pre>
-</blockquote>
-
-<h3><a name="client_logging"> Client-side TLS activity logging </a> </h3>
-
-<p> 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. </p>
-
-<blockquote>
-
-<table>
-
-<tr> <td> 0 </td> <td> Disable logging of TLS activity.</td> </tr>
-
-<tr> <td> 1 </td> <td> Log TLS handshake and certificate information.
-</td> </tr>
-
-<tr> <td> 2 </td> <td> Log levels during TLS negotiation. </td>
-</tr>
-
-<tr> <td> 3 </td> <td> Log hexadecimal and ASCII dump of TLS
-negotiation process </td> </tr>
-
-<tr> <td> 4 </td> <td> Log hexadecimal and ASCII dump of complete
-transmission after STARTTLS </td> </tr>
-
-</table>
-
-</blockquote>
-
-<p> Example: </p>
-
-<blockquote>
-<pre>
-/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtp_tls_loglevel">smtp_tls_loglevel</a> = 0
-</pre>
-</blockquote>
-
-<h3><a name="client_tls_cache">Client-side TLS session cache</a> </h3>
-
-<p> 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 <a href="smtp.8.html">smtp(8)</a>
-process actually using this session and is lost when the process
-terminates. To share the session information between multiple
-<a href="smtp.8.html">smtp(8)</a> 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 <a href="tlsmgr.8.html">tlsmgr(8)</a> 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.</p>
-
-
-<p> Example: </p>
-
-<blockquote>
-<pre>
-/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtp_tls_session_cache_database">smtp_tls_session_cache_database</a> = btree:/var/lib/postfix/smtp_scache
-</pre>
-</blockquote>
-
-<p> 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 <a href="postconf.5.html#data_directory">data_directory</a>. As a migration aid, an attempt to
-open the file under a non-Postfix directory is redirected to the
-Postfix-owned <a href="postconf.5.html#data_directory">data_directory</a>, and a warning is logged. </p>
-
-<p> 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). <a href="http://tools.ietf.org/html/rfc2246">RFC 2246</a>
-recommends a maximum of 24 hours. </p>
-
-<p> Example: </p>
-
-<blockquote>
-<pre>
-/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtp_tls_session_cache_timeout">smtp_tls_session_cache_timeout</a> = 3600s
-</pre>
-</blockquote>
-
-<h3><a name="client_tls_limits"> Client TLS limitations </a>
-</h3>
-
-<p> 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. </p>
-
-<p> 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. </p>
-
-<p> 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. </p>
-
-<p> 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. </p>
-
-<p> 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. </p>
-
-<p> 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. </p>
-
-<p> 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. </p>
-
-<p> It is regrettably the case that TLS <i>secure-channels</i>
-(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
-<a href="#client_tls_policy">policy table</a> entries for additional
-domains hosted at a common secured destination. With Postfix 2.3, we
-make secure-channel configurations substantially easier to configure,
-but they 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. </p>
-
-<p> 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. </p>
-
-<p> Historical note: while the documentation of these issues and many of the
-related features are new with Postfix 2.3, the issue was well
-understood before Postfix 1.0, when Lutz Jänicke was designing
-the first unofficial Postfix TLS patch. See his original post <a
-href="http://www.imc.org/ietf-apps-tls/mail-archive/msg00304.html">http://www.imc.org/ietf-apps-tls/mail-archive/msg00304.html</a>
-and the first response <a
-href="http://www.imc.org/ietf-apps-tls/mail-archive/msg00305.html">http://www.imc.org/ietf-apps-tls/mail-archive/msg00305.html</a>.
-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. </p>
-
-<h3><a name="client_tls_levels"> Configuring TLS in the SMTP/LMTP client </a>
-</h3>
-
-<p> 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.</p>
-
-<dl>
-<dt><b>none</b></dt>
-<dd><a href="#client_tls_none">No TLS.</a></dd>
-<dt><b>may</b></dt>
-<dd><a href="#client_tls_may">Opportunistic TLS.</a></dd>
-<dt><b>encrypt</b></dt>
-<dd><a href="#client_tls_encrypt">Mandatory TLS encryption.</a>
-<dt><b>fingerprint</b></dt>
-<dd><a href="#client_tls_fprint">Certificate fingerprint verification.</a>
-<dt><b>verify</b></dt>
-<dd><a href="#client_tls_verify">Mandatory server certificate verification.</a>
-<dt><b>secure</b></dt>
-<dd><a href="#client_tls_secure">Secure-channel TLS.</a>
-</dl>
-
-<h3><a name="client_tls_none"> No TLS encryption </a>
-</h3>
-
-<p> At the "none" TLS security level, TLS encryption is
-disabled. This is the default security level. With Postfix 2.3 and later,
-it can be configured explicitly by setting "<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = none". </p>
-
-<p> With Postfix 2.2 and earlier, or when <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> is set to
-its default (backwards compatible) empty value, the appropriate configuration
-settings are "<a href="postconf.5.html#smtp_use_tls">smtp_use_tls</a> = no" and "<a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> = no".
-With either approach, TLS is not used even if supported by the server.
-For LMTP, use the corresponding "lmtp_" parameters. </p>
-
-<p> Per destination settings may override this default setting, in which case
-TLS is used selectively, only with destinations explicitly configured
-for TLS. </p>
-
-<p> You can disable TLS for a subset of destinations, while leaving
-it enabled for the rest. With the Postfix 2.3 and later TLS <a
-href="#client_tls_policy">policy table</a>, specify the "none"
-security level. With the obsolete <a href="#client_tls_obs">per-site</a>
-table, specify the "NONE" keyword. </p>
-
-<h3><a name="client_tls_may"> Opportunistic TLS </a>
-</h3>
-
-<p> At the "may" TLS security level, TLS encryption is <i>opportunistic</i>.
-The SMTP transaction is encrypted if the STARTTLS ESMTP feature
-is supported by the server. Otherwise, messages are sent in the clear.
-With Postfix 2.3 and later, opportunistic TLS can be configured by
-setting "<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = may".
-
-<p> Since sending in the clear is acceptable, demanding stronger
-than default TLS security mostly reduces inter-operability. If you
-must restrict TLS protocol or cipher selection even with opportunistic
-TLS, the "<a href="postconf.5.html#smtp_tls_ciphers">smtp_tls_ciphers</a>" and "<a href="postconf.5.html#smtp_tls_protocols">smtp_tls_protocols</a>" configuration
-parameters (Postfix ≥ 2.6) provide control over the protocols
-and cipher grade
-used with opportunistic TLS. With earlier releases the opportunistic TLS
-cipher grade is always "export" and no protocols are disabled. </p>
-
-<p> With Postfix 2.2 and earlier, or when <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> is
-set to its default (backwards compatible) empty value, the appropriate
-configuration settings are "<a href="postconf.5.html#smtp_use_tls">smtp_use_tls</a> = yes" and
-"<a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> = no".
-For LMTP use the corresponding "lmtp_" parameters. </p>
-
-<p> With opportunistic TLS, mail delivery continues even if the
-server certificate is untrusted or bears the wrong name. Starting
-with Postfix 2.3, when the TLS handshake fails for an opportunistic
-TLS session, rather than give up on mail delivery, the transaction
-is retried with TLS disabled. Trying an unencrypted connection makes
-it possible to deliver mail to sites with non-interoperable server
-TLS implementations. </p>
-
-<p> 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
-<a href="#client_tls_encrypt">encrypt</a> security level or higher.
-Attempts to configure opportunistic encryption of LMTP sessions will
-be ignored with a warning written to the mail logs. </p>
-
-<p> You can enable opportunistic TLS just for selected destinations. With
-the Postfix 2.3 and later TLS <a href="#client_tls_policy">policy table</a>,
-specify the "may" security level. With the obsolete <a
-href="#client_tls_obs">per-site</a> table, specify the "MAY" keyword.</p>
-
-<p> 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 <a href="#client_tls_limits">limitations</a> above. </p>
-
-<p> Example: </p>
-
-<blockquote>
-<pre>
-/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = may
-</pre>
-</blockquote>
-
-<p> Postfix 2.2 syntax: </p>
-
-<blockquote>
-<pre>
-/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtp_use_tls">smtp_use_tls</a> = yes
- <a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> = no
-</pre>
-</blockquote>
-
-<h3><a name="client_tls_encrypt"> Mandatory TLS encryption </a>
-</h3>
+<h4><a name="client_tls_encrypt"> Mandatory TLS encryption </a> </h4>
<p> At the "encrypt" TLS security level, messages are sent only
over TLS encrypted sessions. The SMTP transaction is aborted unless
</pre>
</blockquote>
-<h3><a name="client_tls_fprint"> Certificate fingerprint verification </a>
-</h3>
+<h4><a name="client_tls_fprint"> Certificate fingerprint verification </a> </h4>
-<p> Certificate fingerprint verification is available with Postfix 2.5 and
-later. At this security level ("<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = fingerprint"),
-no trusted certificate authorities are used or required. The certificate
-trust chain, expiration date, ... are not checked. Instead, the
-<a href="postconf.5.html#smtp_tls_fingerprint_cert_match">smtp_tls_fingerprint_cert_match</a> parameter or the "match" attribute
-in the <a href="#client_tls_policy">policy</a> table lists the valid
-"fingerprints" of the remote SMTP server certificate. </p>
+<p> Certificate fingerprint verification is available with Postfix
+2.5 and later. At this security level ("<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> =
+fingerprint"), no trusted certificate authorities are used or
+required. The certificate trust chain, expiration date, ... are
+not checked. Instead, the <a href="postconf.5.html#smtp_tls_fingerprint_cert_match">smtp_tls_fingerprint_cert_match</a> parameter
+or the "match" attribute in the <a href="#client_tls_policy">policy</a>
+table lists the remote SMTP server certificate fingerprint or
+public key fingerprint (Postfix 2.9 and later).
<p> 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. This 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. </p>
+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,
+<b>provided</b> that the same public/private keys are used to obtain
+the new certificate. </p>
+
+<p> 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. </p>
<p> The digest algorithm used to calculate the fingerprint is
selected by the <b><a href="postconf.5.html#smtp_tls_fingerprint_digest">smtp_tls_fingerprint_digest</a></b> parameter. In the <a
</pre>
</blockquote>
-<h3><a name="client_tls_verify"> Mandatory server certificate verification </a>
-</h3>
+<h4><a name="client_tls_verify"> Mandatory server certificate verification </a> </h4>
<p> At the "verify" TLS security level, messages are sent only over
TLS encrypted sessions if the remote SMTP server certificate is
</pre>
</blockquote>
-<h3><a name="client_tls_secure"> Secure server certificate verification </a>
-</h3>
+<h4><a name="client_tls_secure"> Secure server certificate verification </a> </h4>
<p> At the <i>secure</i> TLS security level, messages are sent only over
<i>secure-channel</i> TLS sessions where DNS forgery resistant server
<blockquote>
<pre>
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = /etc/postfix/CAfile.pem
- <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> = 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
+ <a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = /etc/postfix/CAfile.pem
+ <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> = 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
+</pre>
+</blockquote>
+
+<p> Secure-channel TLS with <a href="transport.5.html">transport(5)</a> table overrides: <p>
+
+<p> In this case traffic to <i>example.com</i> 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. This secure-channel configuration can also
+be implemented via a <a href="#client_tls_harden">hardened</a> variant of
+the MUST policy in the obsolete <a href="#client_tls_obs">per-site</a>
+table. As stated above, this approach has the potential to mis-deliver
+email if the related domains change hands. </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = /etc/postfix/CAfile.pem
+ <a href="postconf.5.html#transport_maps">transport_maps</a> = hash:/etc/postfix/transport
+ <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> = hash:/etc/postfix/tls_policy
+
+/etc/postfix/transport:
+ example.com <a href="smtp.8.html">smtp</a>:[tls.example.com]
+ example.co.uk <a href="smtp.8.html">smtp</a>:[tls.example.com]
+ example.co.jp <a href="smtp.8.html">smtp</a>:[tls.example.com]
+
+/etc/postfix/tls_policy:
+ [tls.example.com] secure match=tls.example.com
+</pre>
+</blockquote>
+
+<p> Postfix 2.2.9 and later syntax: </p>
+
+<p> <b>Note:</b> Avoid policy lookups with the bare hostname (for
+example, "tls.example.com"). Instead, use the destination (for
+example, "[tls.example.com]") as the <a
+href="#client_tls_obs">per-site</a> table lookup key (a recipient domain
+or MX-enabled transport nexthop with no port suffix may look like a bare
+hostname, but is still a suitable <i>destination</i>). With Postfix 2.3
+and later,
+do not use the obsolete <a href="#client_tls_obs">per-site</a> table;
+use the new <a href="#client_tls_policy">policy table</a> instead. </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtp_cname_overrides_servername">smtp_cname_overrides_servername</a> = no
+ <a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = /etc/postfix/CAfile.pem
+ <a href="postconf.5.html#transport_maps">transport_maps</a> = hash:/etc/postfix/transport
+ <a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a> = hash:/etc/postfix/tls_per_site
+
+/etc/postfix/transport:
+ example.com <a href="smtp.8.html">smtp</a>:[tls.example.com]
+ example.co.uk <a href="smtp.8.html">smtp</a>:[tls.example.com]
+ example.co.jp <a href="smtp.8.html">smtp</a>:[tls.example.com]
+
+/etc/postfix/tls_per_site:
+ [tls.example.com] MUST
+</pre>
+</blockquote>
+
+<h3><a name="client_logging"> Client-side TLS activity logging </a> </h3>
+
+<p> 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. </p>
+
+<blockquote>
+
+<table border="1">
+
+<tr> <th> Level </th> <th> Postfix 2.9 and later</th> <th> Earlier
+releases. </th> </tr>
+
+<tr> <td valign="top"> 0 </td> <td valign="top"> Log only a summary
+message on TLS handshake completion — no logging of remote
+SMTP server certificate trust-chain verification errors if server
+certificate verification is not required. </td> <td valign="top">
+Disable logging of TLS activity.</td> </tr>
+
+<tr> <td valign="top"> 1 </td> <td valign="top"> Also log remote
+SMTP server trust-chain verification errors and peer certificate
+summary information. </td> <td valign="top"> Also log TLS handshake
+and certificate information. </td> </tr>
+
+<tr> <td valign="top"> 2 </td> <td valign="top" colspan="2"> Also
+log levels during TLS negotiation. </td> </tr>
+
+<tr> <td valign="top"> 3 </td> <td valign="top" colspan="2"> Also
+log hexadecimal and ASCII dump of TLS negotiation process. </td>
+</tr>
+
+<tr> <td valign="top"> 4 </td> <td valign="top" colspan="2"> Also
+log hexadecimal and ASCII dump of complete transmission after
+STARTTLS. </td> </tr>
+
+</table>
+
+</blockquote>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtp_tls_loglevel">smtp_tls_loglevel</a> = 0
+</pre>
+</blockquote>
+
+<h3><a name="client_cert_key">Client-side certificate and private
+key configuration </a> </h3>
+
+<p> Do not configure Postfix SMTP client certificates unless you <b>must</b>
+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: </p>
+
+<blockquote>
+<pre>
+ <a href="postconf.5.html#smtp_tls_cert_file">smtp_tls_cert_file</a> =
+ <a href="postconf.5.html#smtp_tls_dcert_file">smtp_tls_dcert_file</a> =
+ <a href="postconf.5.html#smtp_tls_key_file">smtp_tls_key_file</a> =
+ <a href="postconf.5.html#smtp_tls_dkey_file">smtp_tls_dkey_file</a> =
+ # Postfix ≥ 2.6
+ <a href="postconf.5.html#smtp_tls_eccert_file">smtp_tls_eccert_file</a> =
+ <a href="postconf.5.html#smtp_tls_eckey_file">smtp_tls_eckey_file</a> =
+</pre>
+</blockquote>
+
+<p> The best way to use the default settings is to comment out the above
+parameters in <a href="postconf.5.html">main.cf</a> if present. </p>
+
+<p> During TLS startup negotiation the Postfix SMTP client may present
+a certificate to the remote SMTP server. The Netscape client is
+rather clever here and lets the user select between only those
+certificates that match CA certificates offered by the remote SMTP
+server. As the Postfix SMTP client uses the "SSL_connect()" function
+from the OpenSSL package, this is not possible and we have to choose
+just one certificate. So for now the default is to use _no_
+certificate and key unless one is explicitly specified here. </p>
+
+<p> 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. </p>
+
+<p> 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. </p>
+
+<p> 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). </p>
+
+<p> Example: the certificate for "client.example.com" was issued by
+"intermediate CA" which itself has a certificate issued by "root CA".
+Create the client.pem file with: </p>
+
+<blockquote>
+<pre>
+% <b>cat client_cert.pem intermediate_CA.pem > client.pem </b>
+</pre>
+</blockquote>
+
+<p> A Postfix SMTP client certificate supplied here must be usable
+as SSL client certificate and hence pass the "openssl verify -purpose
+sslclient ..." test. </p>
+
+<p> 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 "client.pem" file reduces
+the overhead of the TLS exchange. </p>
+
+<p> If you want the Postfix SMTP client to accept remote SMTP server
+certificates issued by these CAs, append the root certificate to
+$<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> or install it in the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> directory. </p>
+
+<p> RSA key and certificate examples: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtp_tls_cert_file">smtp_tls_cert_file</a> = /etc/postfix/client.pem
+ <a href="postconf.5.html#smtp_tls_key_file">smtp_tls_key_file</a> = $<a href="postconf.5.html#smtp_tls_cert_file">smtp_tls_cert_file</a>
+</pre>
+</blockquote>
+
+<p> Their DSA counterparts: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtp_tls_dcert_file">smtp_tls_dcert_file</a> = /etc/postfix/client-dsa.pem
+ <a href="postconf.5.html#smtp_tls_dkey_file">smtp_tls_dkey_file</a> = $<a href="postconf.5.html#smtp_tls_dcert_file">smtp_tls_dcert_file</a>
+</pre>
+</blockquote>
+
+<p> Their ECDSA counterparts (Postfix ≥ 2.6 + OpenSSL ≥ 0.9.9): </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtp_tls_eccert_file">smtp_tls_eccert_file</a> = /etc/postfix/client-ecdsa.pem
+ <a href="postconf.5.html#smtp_tls_eckey_file">smtp_tls_eckey_file</a> = $<a href="postconf.5.html#smtp_tls_eccert_file">smtp_tls_eccert_file</a>
+</pre>
+</blockquote>
+
+<p> 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 $<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> or in multiple files, one CA per file in
+the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> directory. If you use a directory, don't forget
+to create the necessary "hash" links with: </p>
+
+<blockquote>
+<pre>
+# <b>$OPENSSL_HOME/bin/c_rehash <i>/path/to/directory</i> </b>
+</pre>
+</blockquote>
+
+<p> The $<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> 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. </p>
+
+<p> Additional trusted CAs can be specified via the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a>
+directory, in which case the certificates are read (with $<a href="postconf.5.html#mail_owner">mail_owner</a>
+privileges) from the files in the directory when the information
+is needed. Thus, the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> directory needs to be accessible
+inside the optional chroot jail. </p>
+
+<p> The choice between $<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> and $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> 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. </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = /etc/postfix/CAcert.pem
+ <a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> = /etc/postfix/certs
</pre>
</blockquote>
-<p> Secure-channel TLS with <a href="transport.5.html">transport(5)</a> table overrides: <p>
+<h3><a name="client_tls_cache">Client-side TLS session cache</a> </h3>
+
+<p> 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 <a href="smtp.8.html">smtp(8)</a>
+process actually using this session and is lost when the process
+terminates. To share the session information between multiple
+<a href="smtp.8.html">smtp(8)</a> 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 <a href="tlsmgr.8.html">tlsmgr(8)</a> 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.</p>
-<p> In this case traffic to <i>example.com</i> 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. This secure-channel configuration can also
-be implemented via a <a href="#client_tls_harden">hardened</a> variant of
-the MUST policy in the obsolete <a href="#client_tls_obs">per-site</a>
-table. As stated above, this approach has the potential to mis-deliver
-email if the related domains change hands. </p>
+<p> Example: </p>
+
<blockquote>
<pre>
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = /etc/postfix/CAfile.pem
- <a href="postconf.5.html#transport_maps">transport_maps</a> = hash:/etc/postfix/transport
- <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> = hash:/etc/postfix/tls_policy
-
-/etc/postfix/transport:
- example.com <a href="smtp.8.html">smtp</a>:[tls.example.com]
- example.co.uk <a href="smtp.8.html">smtp</a>:[tls.example.com]
- example.co.jp <a href="smtp.8.html">smtp</a>:[tls.example.com]
-
-/etc/postfix/tls_policy:
- [tls.example.com] secure match=tls.example.com
+ <a href="postconf.5.html#smtp_tls_session_cache_database">smtp_tls_session_cache_database</a> = btree:/var/lib/postfix/smtp_scache
</pre>
</blockquote>
-<p> Postfix 2.2.9 and later syntax: </p>
+<p> 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 <a href="postconf.5.html#data_directory">data_directory</a>. As a migration aid, an attempt to
+open the file under a non-Postfix directory is redirected to the
+Postfix-owned <a href="postconf.5.html#data_directory">data_directory</a>, and a warning is logged. </p>
-<p> <b>Note:</b> Avoid policy lookups with the bare hostname (for
-example, "tls.example.com"). Instead, use the destination (for
-example, "[tls.example.com]") as the <a
-href="#client_tls_obs">per-site</a> table lookup key (a recipient domain
-or MX-enabled transport nexthop with no port suffix may look like a bare
-hostname, but is still a suitable <i>destination</i>). With Postfix 2.3
-and later,
-do not use the obsolete <a href="#client_tls_obs">per-site</a> table;
-use the new <a href="#client_tls_policy">policy table</a> instead. </p>
+<p> 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). <a href="http://tools.ietf.org/html/rfc2246">RFC 2246</a>
+recommends a maximum of 24 hours. </p>
+<p> Example: </p>
+
<blockquote>
<pre>
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtp_cname_overrides_servername">smtp_cname_overrides_servername</a> = no
- <a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = /etc/postfix/CAfile.pem
- <a href="postconf.5.html#transport_maps">transport_maps</a> = hash:/etc/postfix/transport
- <a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a> = hash:/etc/postfix/tls_per_site
-
-/etc/postfix/transport:
- example.com <a href="smtp.8.html">smtp</a>:[tls.example.com]
- example.co.uk <a href="smtp.8.html">smtp</a>:[tls.example.com]
- example.co.jp <a href="smtp.8.html">smtp</a>:[tls.example.com]
-
-/etc/postfix/tls_per_site:
- [tls.example.com] MUST
+ <a href="postconf.5.html#smtp_tls_session_cache_timeout">smtp_tls_session_cache_timeout</a> = 3600s
</pre>
</blockquote>
+<h3><a name="client_tls_limits"> Client TLS limitations </a>
+</h3>
+
+<p> 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. </p>
+
+<p> 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. </p>
+
+<p> 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. </p>
+
+<p> 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. </p>
+
+<p> 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. </p>
+
+<p> 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. </p>
+
+<p> 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. </p>
+
+<p> It is regrettably the case that TLS <i>secure-channels</i>
+(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
+<a href="#client_tls_policy">policy table</a> entries for additional
+domains hosted at a common secured destination. With Postfix 2.3, we
+make secure-channel configurations substantially easier to configure,
+but they 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. </p>
+
+<p> 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. </p>
+
+<p> Historical note: while the documentation of these issues and many of the
+related features are new with Postfix 2.3, the issue was well
+understood before Postfix 1.0, when Lutz Jänicke was designing
+the first unofficial Postfix TLS patch. See his original post <a
+href="http://www.imc.org/ietf-apps-tls/mail-archive/msg00304.html">http://www.imc.org/ietf-apps-tls/mail-archive/msg00304.html</a>
+and the first response <a
+href="http://www.imc.org/ietf-apps-tls/mail-archive/msg00305.html">http://www.imc.org/ietf-apps-tls/mail-archive/msg00305.html</a>.
+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. </p>
+
<h3> <a name="client_tls_policy"> TLS policy table </a>
</h3>
later. At this security level, there are no trusted certificate
authorities. The certificate trust chain, expiration date, ... are
not checked. Instead, the optional <b>match</b> attribute, or else
-the <a href="postconf.5.html">main.cf</a> <b><a href="postconf.5.html#smtp_tls_fingerprint_cert_match">smtp_tls_fingerprint_cert_match</a></b> parameter,
-lists the valid fingerprints of the server certificate. The
+the <a href="postconf.5.html">main.cf</a> <b><a href="postconf.5.html#smtp_tls_fingerprint_cert_match">smtp_tls_fingerprint_cert_match</a></b> 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
<b><a href="postconf.5.html#smtp_tls_fingerprint_digest">smtp_tls_fingerprint_digest</a></b> parameter. Multiple fingerprints can
be combined with a "|" delimiter in a single match attribute, or multiple
</ul>
+<h2><a name="build_tls">Building Postfix with TLS support</a></h2>
+
+<p> These instructions assume that you build Postfix from source
+code as described in the <a href="INSTALL.html">INSTALL</a> document. Some modification may
+be required if you build Postfix from a vendor-specific source
+package. </p>
+
+<p> To build Postfix with TLS support, first we need to generate
+the <tt>make(1)</tt> files with the necessary definitions. This is
+done by invoking the command "<tt>make makefiles</tt>" in the Postfix
+top-level directory and with arguments as shown next. </p>
+
+<p> <b> NOTE: Do not use Gnu TLS. It will spontaneously terminate
+a Postfix daemon process with exit status code 2, instead of allowing
+Postfix to 1) report the error to the maillog file, and to 2) provide
+plaintext service where this is appropriate. </b> </p>
+
+<ul>
+
+<li> <p> If the OpenSSL include files (such as <tt>ssl.h</tt>) are
+in directory <tt>/usr/include/openssl</tt>, and the OpenSSL libraries
+(such as <tt>libssl.so</tt> and <tt>libcrypto.so</tt>) are in
+directory <tt>/usr/lib</tt>: </p>
+
+<blockquote>
+<pre>
+% <b>make tidy</b> # if you have left-over files from a previous build
+% <b>make makefiles CCARGS="-DUSE_TLS" AUXLIBS="-lssl -lcrypto"</b>
+</pre>
+</blockquote>
+
+<li> <p> If the OpenSSL include files (such as <tt>ssl.h</tt>) are
+in directory <tt>/usr/local/include/openssl</tt>, and the OpenSSL
+libraries (such as <tt>libssl.so</tt> and <tt>libcrypto.so</tt>)
+are in directory <tt>/usr/local/lib</tt>: </p>
+
+<blockquote>
+<pre>
+% <b>make tidy</b> # if you have left-over files from a previous build
+% <b>make makefiles CCARGS="-DUSE_TLS -I/usr/local/include" \
+ AUXLIBS="-L/usr/local/lib -lssl -lcrypto" </b>
+</pre>
+</blockquote>
+
+<p> On Solaris, specify the <tt>-R</tt> option as shown below:
+
+<blockquote>
+<pre>
+% <b>make tidy</b> # if you have left-over files from a previous build
+% <b>make makefiles CCARGS="-DUSE_TLS -I/usr/local/include" \
+ AUXLIBS="-R/usr/local/lib -L/usr/local/lib -lssl -lcrypto" </b>
+</pre>
+</blockquote>
+
+</ul>
+
+<p> 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 "<tt>make makefiles</tt>"
+instructions with the instructions above: </p>
+
+<blockquote>
+<pre>
+% <b>make tidy</b> # if you have left-over files from a previous build
+% <b>make makefiles CCARGS="-DUSE_TLS \
+ <i>(other -D or -I options)</i>" \
+ AUXLIBS="-lssl -lcrypto \
+ <i>(other -l options for libraries in /usr/lib)</i> \
+ <i>(-L/path/name + -l options for other libraries)</i>"</b>
+</pre>
+</blockquote>
+
+<p> To complete the build process, see the Postfix <a href="INSTALL.html">INSTALL</a>
+instructions. Postfix has TLS support turned off by default, so
+you can start using Postfix as soon as it is installed. </p>
+
<h2> <a name="problems"> Reporting problems </a> </h2>
<p> Problems are preferably reported via <postfix-users@postfix.org>.
PIX firewall bugs.
<b><a href="postconf.5.html#smtp_quote_rfc821_envelope">smtp_quote_rfc821_envelope</a> (yes)</b>
- Quote addresses in SMTP MAIL FROM and RCPT TO com-
- mands as required by <a href="http://tools.ietf.org/html/rfc2821">RFC 2821</a>.
+ Quote addresses in Postfix SMTP client MAIL FROM
+
and RCPT TO commands as required by <a href="http://tools.ietf.org/html/rfc2821">RFC 2821</a>.
<b><a href="postconf.5.html#smtp_reply_filter">smtp_reply_filter</a> (empty)</b>
A mechanism to transform replies from remote SMTP
servers one line at a time.
<b><a href="postconf.5.html#smtp_skip_5xx_greeting">smtp_skip_5xx_greeting</a> (yes)</b>
- Skip SMTP servers that greet with a 5XX status code
- (go away, do not try again later).
+ Skip remote SMTP servers that greet with a 5XX sta-
+ tus code (go away, do not try again later).
<b><a href="postconf.5.html#smtp_skip_quit_response">smtp_skip_quit_response</a> (yes)</b>
Do not wait for the response to the SMTP QUIT com-
<b><a href="postconf.5.html#smtp_generic_maps">smtp_generic_maps</a> (empty)</b>
Optional lookup tables that perform address rewrit-
- ing in the SMTP client, typically to transform a
- locally valid address into a globally valid address
- when sending mail across the Internet.
+ ing in the Postfix SMTP client, typically to trans-
+ form a locally valid address into a globally valid
+ address when sending mail across the Internet.
Available in Postfix version 2.2.9 and later:
Lookup tables, indexed by the remote LMTP server
address, with case insensitive lists of LHLO key-
words (pipelining, starttls, auth, etc.) that the
- LMTP client will ignore in the LHLO response from a
- remote LMTP server.
+ Postfix LMTP client will ignore in the LHLO
+ response from a remote LMTP server.
<b><a href="postconf.5.html#lmtp_discard_lhlo_keywords">lmtp_discard_lhlo_keywords</a> (empty)</b>
A case insensitive list of LHLO keywords (pipelin-
- ing, starttls, auth, etc.) that the LMTP client
- will ignore in the LHLO response from a remote LMTP
- server.
+ ing, starttls, auth, etc.) that the Postfix LMTP
+ client will ignore in the LHLO response from a
+ remote LMTP server.
Available in Postfix version 2.4.4 and later:
client.
<b><a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a> (empty)</b>
- Optional SMTP client lookup tables with one user-
- name:password entry per remote hostname or domain,
- or sender address when sender-dependent authentica-
- tion is enabled.
+ Optional Postfix SMTP client lookup tables with one
+ username:password entry per remote hostname or
+ domain, or sender address when sender-dependent
+ authentication is enabled.
<b><a href="postconf.5.html#smtp_sasl_security_options">smtp_sasl_security_options</a> (noplaintext, noanonymous)</b>
Postfix SMTP client SASL security options; as of
<b><a href="postconf.5.html#smtp_tls_mandatory_exclude_ciphers">smtp_tls_mandatory_exclude_ciphers</a> (empty)</b>
Additional list of ciphers or cipher types to
- exclude from the SMTP client cipher list at manda-
- tory TLS security levels.
+ exclude from the Postfix SMTP client cipher list at
+ mandatory TLS security levels.
<b><a href="postconf.5.html#smtp_tls_dcert_file">smtp_tls_dcert_file</a> (empty)</b>
File with the Postfix SMTP client DSA certificate
tificates.
<b><a href="postconf.5.html#smtp_tls_secure_cert_match">smtp_tls_secure_cert_match</a> (nexthop, dot-nexthop)</b>
- The server certificate peername verification method
- for the "secure" TLS security level.
+ How the Postfix SMTP client verifies the server
+ certificate peername for the "secure" TLS security
+ level.
<b><a href="postconf.5.html#smtp_tls_session_cache_database">smtp_tls_session_cache_database</a> (empty)</b>
- Name of the file containing the optional Postfix
+ Name of the file containing the optional Postfix
SMTP client TLS session cache.
<b><a href="postconf.5.html#smtp_tls_session_cache_timeout">smtp_tls_session_cache_timeout</a> (3600s)</b>
sion cache information.
<b><a href="postconf.5.html#smtp_tls_verify_cert_match">smtp_tls_verify_cert_match</a> (hostname)</b>
- The server certificate peername verification method
- for the "verify" TLS security level.
+ How the Postfix SMTP client verifies the server
+ certificate peername for the "verify" TLS security
+ level.
<b><a href="postconf.5.html#tls_daemon_random_bytes">tls_daemon_random_bytes</a> (32)</b>
The number of pseudo-random bytes that an <a href="smtp.8.html"><b>smtp</b>(8)</a>
the smtp message delivery transport.
<b><a href="postconf.5.html#smtp_connect_timeout">smtp_connect_timeout</a> (30s)</b>
- The SMTP client time limit for completing a TCP
- connection, or zero (use the operating system
+ The Postfix SMTP client time limit for completing a
+ TCP connection, or zero (use the operating system
built-in time limit).
<b><a href="postconf.5.html#smtp_helo_timeout">smtp_helo_timeout</a> (300s)</b>
- The SMTP client time limit for sending the HELO or
- EHLO command, and for receiving the initial server
- response.
+ The Postfix SMTP client time limit for sending the
+ HELO or EHLO command, and for receiving the initial
+ remote SMTP server response.
<b><a href="postconf.5.html#lmtp_lhlo_timeout">lmtp_lhlo_timeout</a> (300s)</b>
- The LMTP client time limit for sending the LHLO
- command, and for receiving the initial server
- response.
+ The Postfix LMTP client time limit for sending the
+ LHLO command, and for receiving the initial remote
+ LMTP server response.
<b><a href="postconf.5.html#smtp_xforward_timeout">smtp_xforward_timeout</a> (300s)</b>
- The SMTP client time limit for sending the XFORWARD
- command, and for receiving the server response.
+ The Postfix SMTP client time limit for sending the
+ XFORWARD command, and for receiving the remote SMTP
+ server response.
<b><a href="postconf.5.html#smtp_mail_timeout">smtp_mail_timeout</a> (300s)</b>
- The SMTP client time limit for sending the MAIL
- FROM command, and for receiving the server
- response.
+ The Postfix SMTP client time limit for sending the
+ MAIL FROM command, and for receiving the remote
+ SMTP server response.
<b><a href="postconf.5.html#smtp_rcpt_timeout">smtp_rcpt_timeout</a> (300s)</b>
- The SMTP client time limit for sending the SMTP
- RCPT TO command, and for receiving the server
- response.
+ The Postfix SMTP client time limit for sending the
+ SMTP RCPT TO command, and for receiving the remote
+ SMTP server response.
<b><a href="postconf.5.html#smtp_data_init_timeout">smtp_data_init_timeout</a> (120s)</b>
- The SMTP client time limit for sending the SMTP
- DATA command, and for receiving the server
- response.
+ The Postfix SMTP client time limit for sending the
+ SMTP DATA command, and for receiving the remote
+ SMTP server response.
<b><a href="postconf.5.html#smtp_data_xfer_timeout">smtp_data_xfer_timeout</a> (180s)</b>
- The SMTP client time limit for sending the SMTP
- message content.
+ The Postfix SMTP client time limit for sending the
+ SMTP message content.
<b><a href="postconf.5.html#smtp_data_done_timeout">smtp_data_done_timeout</a> (600s)</b>
- The SMTP client time limit for sending the SMTP
- ".", and for receiving the server response.
+ The Postfix SMTP client time limit for sending the
+ SMTP ".", and for receiving the remote SMTP server
+ response.
<b><a href="postconf.5.html#smtp_quit_timeout">smtp_quit_timeout</a> (300s)</b>
- The SMTP client time limit for sending the QUIT
- command, and for receiving the server response.
+ The Postfix SMTP client time limit for sending the
+ QUIT command, and for receiving the remote SMTP
+ server response.
Available in Postfix version 2.1 and later:
<b><a href="postconf.5.html#smtp_mx_address_limit">smtp_mx_address_limit</a> (5)</b>
The maximal number of MX (mail exchanger) IP
- addresses that can result from mail exchanger
- lookups, or zero (no limit).
+ addresses that can result from Postfix SMTP client
+ mail exchanger lookups, or zero (no limit).
<b><a href="postconf.5.html#smtp_mx_session_limit">smtp_mx_session_limit</a> (2)</b>
- The maximal number of SMTP sessions per delivery
- request before giving up or delivering to a fall-
- back <a href="postconf.5.html#relayhost">relay host</a>, or zero (no limit).
+ The maximal number of SMTP sessions per delivery
+ request before the Postfix SMTP client gives up or
+ delivers to a fall-back <a href="postconf.5.html#relayhost">relay host</a>, or zero (no
+ limit).
<b><a href="postconf.5.html#smtp_rset_timeout">smtp_rset_timeout</a> (20s)</b>
- The SMTP client time limit for sending the RSET
- command, and for receiving the server response.
+ The Postfix SMTP client time limit for sending the
+ RSET command, and for receiving the remote SMTP
+ server response.
Available in Postfix version 2.2 and earlier:
Available in Postfix version 2.2 and later:
<b><a href="postconf.5.html#smtp_connection_cache_destinations">smtp_connection_cache_destinations</a> (empty)</b>
- Permanently enable SMTP connection caching for the
+ Permanently enable SMTP connection caching for the
specified destinations.
<b><a href="postconf.5.html#smtp_connection_cache_on_demand">smtp_connection_cache_on_demand</a> (yes)</b>
- Temporarily enable SMTP connection caching while a
+ Temporarily enable SMTP connection caching while a
destination has a high volume of mail in the active
queue.
<b><a href="postconf.5.html#smtp_connection_cache_time_limit">smtp_connection_cache_time_limit</a> (2s)</b>
When SMTP connection caching is enabled, the amount
- of time that an unused SMTP client socket is kept
+ of time that an unused SMTP client socket is kept
open before it is closed.
Available in Postfix version 2.3 and later:
<b><a href="postconf.5.html#connection_cache_protocol_timeout">connection_cache_protocol_timeout</a> (5s)</b>
- Time limit for connection cache connect, send or
+ Time limit for connection cache connect, send or
receive operations.
Available in Postfix version 2.9 and later:
<b><a href="postconf.5.html#smtp_per_record_deadline">smtp_per_record_deadline</a> (no)</b>
Change the behavior of the smtp_*_timeout time lim-
- its, from a time limit per read or write system
+ its, from a time limit per read or write system
call, to a time limit to send or receive a complete
- record (an SMTP command line, SMTP response line,
- SMTP message content line, or TLS protocol mes-
+ record (an SMTP command line, SMTP response line,
+ SMTP message content line, or TLS protocol mes-
sage).
<b>TROUBLE SHOOTING CONTROLS</b>
<b><a href="postconf.5.html#debug_peer_level">debug_peer_level</a> (2)</b>
- The increment in verbose logging level when a
- remote client or server matches a pattern in the
+ The increment in verbose logging level when a
+ remote client or server matches a pattern in the
<a href="postconf.5.html#debug_peer_list">debug_peer_list</a> parameter.
<b><a href="postconf.5.html#debug_peer_list">debug_peer_list</a> (empty)</b>
- Optional list of remote client or server hostname
- or network address patterns that cause the verbose
- logging level to increase by the amount specified
+ Optional list of remote client or server hostname
+ or network address patterns that cause the verbose
+ logging level to increase by the amount specified
in $<a href="postconf.5.html#debug_peer_level">debug_peer_level</a>.
<b><a href="postconf.5.html#error_notice_recipient">error_notice_recipient</a> (postmaster)</b>
- The recipient of postmaster notifications about
- mail delivery problems that are caused by policy,
+ The recipient of postmaster notifications about
+ mail delivery problems that are caused by policy,
resource, software or protocol errors.
<b><a href="postconf.5.html#internal_mail_filter_classes">internal_mail_filter_classes</a> (empty)</b>
- What categories of Postfix-generated mail are sub-
- ject to before-queue content inspection by
+ What categories of Postfix-generated mail are sub-
+ ject to before-queue content inspection by
<a href="postconf.5.html#non_smtpd_milters">non_smtpd_milters</a>, <a href="postconf.5.html#header_checks">header_checks</a> and <a href="postconf.5.html#body_checks">body_checks</a>.
<b><a href="postconf.5.html#notify_classes">notify_classes</a> (resource, software)</b>
- The list of error classes that are reported to the
+ The list of error classes that are reported to the
postmaster.
<b>MISCELLANEOUS CONTROLS</b>
<b><a href="postconf.5.html#best_mx_transport">best_mx_transport</a> (empty)</b>
- Where the Postfix SMTP client should deliver mail
+ Where the Postfix SMTP client should deliver mail
when it detects a "mail loops back to myself" error
condition.
<b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
- The default location of the Postfix <a href="postconf.5.html">main.cf</a> and
+ The default location of the Postfix <a href="postconf.5.html">main.cf</a> and
<a href="master.5.html">master.cf</a> configuration files.
<b><a href="postconf.5.html#daemon_timeout">daemon_timeout</a> (18000s)</b>
- How much time a Postfix daemon process may take to
- handle a request before it is terminated by a
+ How much time a Postfix daemon process may take to
+ handle a request before it is terminated by a
built-in watchdog timer.
<b><a href="postconf.5.html#delay_logging_resolution_limit">delay_logging_resolution_limit</a> (2)</b>
- The maximal number of digits after the decimal
+ The maximal number of digits after the decimal
point when logging sub-second delay values.
<b><a href="postconf.5.html#disable_dns_lookups">disable_dns_lookups</a> (no)</b>
- Disable DNS lookups in the Postfix SMTP and LMTP
+ Disable DNS lookups in the Postfix SMTP and LMTP
clients.
<b><a href="postconf.5.html#inet_interfaces">inet_interfaces</a> (all)</b>
tem receives mail on.
<b><a href="postconf.5.html#inet_protocols">inet_protocols</a> (all)</b>
- The Internet protocols Postfix will attempt to use
+ The Internet protocols Postfix will attempt to use
when making or accepting connections.
<b><a href="postconf.5.html#ipc_timeout">ipc_timeout</a> (3600s)</b>
over an internal communication channel.
<b><a href="postconf.5.html#lmtp_assume_final">lmtp_assume_final</a> (no)</b>
- When an LMTP server announces no DSN support,
+ When a remote LMTP server announces no DSN support,
assume that the server performs final delivery, and
- send "delivered" delivery status notifications
+ send "delivered" delivery status notifications
instead of "relayed".
<b><a href="postconf.5.html#lmtp_tcp_port">lmtp_tcp_port</a> (24)</b>
- The default TCP port that the Postfix LMTP client
+ The default TCP port that the Postfix LMTP client
connects to.
<b><a href="postconf.5.html#max_idle">max_idle</a> (100s)</b>
- The maximum amount of time that an idle Postfix
- daemon process waits for an incoming connection
+ The maximum amount of time that an idle Postfix
+ daemon process waits for an incoming connection
before terminating voluntarily.
<b><a href="postconf.5.html#max_use">max_use</a> (100)</b>
- The maximal number of incoming connections that a
- Postfix daemon process will service before termi-
+ The maximal number of incoming connections that a
+ Postfix daemon process will service before termi-
nating voluntarily.
<b><a href="postconf.5.html#process_id">process_id</a> (read-only)</b>
- The process ID of a Postfix command or daemon
+ The process ID of a Postfix command or daemon
process.
<b><a href="postconf.5.html#process_name">process_name</a> (read-only)</b>
- The process name of a Postfix command or daemon
+ The process name of a Postfix command or daemon
process.
<b><a href="postconf.5.html#proxy_interfaces">proxy_interfaces</a> (empty)</b>
The network interface addresses that this mail sys-
- tem receives mail on by way of a proxy or network
+ tem receives mail on by way of a proxy or network
address translation unit.
<b><a href="postconf.5.html#smtp_address_preference">smtp_address_preference</a> (any)</b>
The address type ("ipv6", "ipv4" or "any") that the
Postfix SMTP client will try first, when a destina-
- tion has IPv6 and IPv4 addresses with equal MX
+ tion has IPv6 and IPv4 addresses with equal MX
preference.
<b><a href="postconf.5.html#smtp_bind_address">smtp_bind_address</a> (empty)</b>
- An optional numerical network address that the
- Postfix SMTP client should bind to when making an
+ An optional numerical network address that the
+ Postfix SMTP client should bind to when making an
IPv4 connection.
<b><a href="postconf.5.html#smtp_bind_address6">smtp_bind_address6</a> (empty)</b>
- An optional numerical network address that the
- Postfix SMTP client should bind to when making an
+ An optional numerical network address that the
+ Postfix SMTP client should bind to when making an
IPv6 connection.
<b><a href="postconf.5.html#smtp_helo_name">smtp_helo_name</a> ($<a href="postconf.5.html#myhostname">myhostname</a>)</b>
- The hostname to send in the SMTP EHLO or HELO com-
+ The hostname to send in the SMTP EHLO or HELO com-
mand.
<b><a href="postconf.5.html#lmtp_lhlo_name">lmtp_lhlo_name</a> ($<a href="postconf.5.html#myhostname">myhostname</a>)</b>
The hostname to send in the LMTP LHLO command.
<b><a href="postconf.5.html#smtp_host_lookup">smtp_host_lookup</a> (dns)</b>
- What mechanisms the Postfix SMTP client uses to
+ What mechanisms the Postfix SMTP client uses to
look up a host's IP address.
<b><a href="postconf.5.html#smtp_randomize_addresses">smtp_randomize_addresses</a> (yes)</b>
- Randomize the order of equal-preference MX host
+ Randomize the order of equal-preference MX host
addresses.
<b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b>
The syslog facility of Postfix logging.
<b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b>
- The mail system name that is prepended to the
- process name in syslog records, so that "smtpd"
+ The mail system name that is prepended to the
+ process name in syslog records, so that "smtpd"
becomes, for example, "postfix/smtpd".
Available with Postfix 2.2 and earlier:
<b><a href="postconf.5.html#fallback_relay">fallback_relay</a> (empty)</b>
- Optional list of relay hosts for SMTP destinations
+ Optional list of relay hosts for SMTP destinations
that can't be found or that are unreachable.
Available with Postfix 2.3 and later:
<b><a href="postconf.5.html#smtp_fallback_relay">smtp_fallback_relay</a> ($<a href="postconf.5.html#fallback_relay">fallback_relay</a>)</b>
- Optional list of relay hosts for SMTP destinations
+ Optional list of relay hosts for SMTP destinations
that can't be found or that are unreachable.
<b>SEE ALSO</b>
<a href="TLS_README.html">TLS_README</a>, Postfix STARTTLS howto
<b>LICENSE</b>
- The Secure Mailer license must be distributed with this
+ The Secure Mailer license must be distributed with this
software.
<b>AUTHOR(S)</b>
<b>user</b> Parameters with user-defined names.
- The default is as if "<b>-C builtin,service,user</b>" is
- specified.
+ <b>all</b> All the above classes.
+
+ The default is as if "<b>-C all</b>" is specified.
<b>-d</b> Print <a href="postconf.5.html"><b>main.cf</b></a> default parameter settings instead of
- actual settings. Specify <b>-df</b> to fold long lines
+ actual settings. Specify <b>-df</b> to fold long lines
for human readability (Postfix 2.9 and later).
- <b>-e</b> Edit the <a href="postconf.5.html"><b>main.cf</b></a> configuration file, and update
- parameter settings with the "<i>name</i>=<i>value</i>" pairs on
+ <b>-e</b> Edit the <a href="postconf.5.html"><b>main.cf</b></a> configuration file, and update
+ parameter settings with the "<i>name</i>=<i>value</i>" pairs on
the <a href="postconf.1.html"><b>postconf</b>(1)</a> command line. The file is copied to
- a temporary file then renamed into place. Specify
+ a temporary file then renamed into place. Specify
quotes to protect special characters and whitespace
on the <a href="postconf.1.html"><b>postconf</b>(1)</a> command line.
The <b>-e</b> is no longer needed with Postfix version 2.8
and later.
- <b>-f</b> Fold
long lines when printing <a href="postconf.5.html"><b>main.cf</b></a> or <a href="master.5.html"><b>master.cf</b></a>
- configuration file entries, for human readability.
+ <b>-f</b> Fold
long lines when printing <a href="postconf.5.html"><b>main.cf</b></a> or <a href="master.5.html"><b>master.cf</b></a>
+ configuration file entries, for human readability.
- This feature is available with Postfix 2.9 and
+ This feature is available with Postfix 2.9 and
later.
<b>-h</b> Show <a href="postconf.5.html"><b>main.cf</b></a> parameter values without the "<i>name</i> = "
label that normally precedes the value.
- <b>-l</b> List the names of all supported mailbox locking
+ <b>-l</b> List the names of all supported mailbox locking
methods. Postfix supports the following methods:
- <b>flock</b> A kernel-based advisory locking method for
- local files only. This locking method is
- available on systems with a BSD compatible
+ <b>flock</b> A kernel-based advisory locking method for
+ local files only. This locking method is
+ available on systems with a BSD compatible
library.
- <b>fcntl</b> A kernel-based advisory locking method for
+ <b>fcntl</b> A kernel-based advisory locking method for
local and remote files.
<b>dotlock</b>
- An application-level locking method. An
- application locks a file named <i>filename</i> by
- creating a file named <i>filename</i><b>.lock</b>. The
- application is expected to remove its own
- lock file, as well as stale lock files that
+ An application-level locking method. An
+ application locks a file named <i>filename</i> by
+ creating a file named <i>filename</i><b>.lock</b>. The
+ application is expected to remove its own
+ lock file, as well as stale lock files that
were left behind after abnormal termination.
<b>-m</b> List the names of all supported lookup table types.
- In Postfix configuration files, lookup tables are
- specified as <i>type</i><b>:</b><i>name</i>, where <i>type</i> is one of the
- types listed below. The table <i>name</i> syntax depends
- on
the lookup table type as described in the <a href="DATABASE_README.html">DATA</a>-
+ In Postfix configuration files, lookup tables are
+ specified as <i>type</i><b>:</b><i>name</i>, where <i>type</i> is one of the
+ types listed below. The table <i>name</i> syntax depends
+ on
the lookup table type as described in the <a href="DATABASE_README.html">DATA</a>-
<a href="DATABASE_README.html">BASE_README</a> document.
- <b>btree</b> A sorted, balanced tree structure. This is
+ <b>btree</b> A sorted, balanced tree structure. This is
available on systems with support for Berke-
ley DB databases.
- <b>cdb</b> A read-optimized structure with no support
- for incremental updates. This is available
+ <b>cdb</b> A read-optimized structure with no support
+ for incremental updates. This is available
on systems with support for CDB databases.
- <b>cidr</b> A table that associates values with Class-
- less Inter-Domain Routing (CIDR) patterns.
+ <b>cidr</b> A table that associates values with Class-
+ less Inter-Domain Routing (CIDR) patterns.
This is described in <a href="cidr_table.5.html"><b>cidr_table</b>(5)</a>.
<b>dbm</b> An indexed file type based on hashing. This
<b>environ</b>
The UNIX process environment array. The
- lookup key is the variable name. Originally
- implemented for testing, someone may find
+ lookup key is the variable name. Originally
+ implemented for testing, someone may find
this useful someday.
<b>hash</b> An indexed file type based on hashing. This
- is available on systems with support for
+ is available on systems with support for
Berkeley DB databases.
<b>internal</b>
tent are lost when a process terminates.
<b>ldap</b> (read-only)
- Perform lookups using the LDAP protocol.
+ Perform lookups using the LDAP protocol.
This is described in <a href="ldap_table.5.html"><b>ldap_table</b>(5)</a>.
<b>mysql</b> (read-only)
- Perform lookups using the MYSQL protocol.
+ Perform lookups using the MYSQL protocol.
This is described in <a href="mysql_table.5.html"><b>mysql_table</b>(5)</a>.
<b>pcre</b> (read-only)
A lookup table based on Perl Compatible Reg-
- ular Expressions. The file format is
+ ular Expressions. The file format is
described in <a href="pcre_table.5.html"><b>pcre_table</b>(5)</a>.
<b>pgsql</b> (read-only)
- Perform lookups using the PostgreSQL proto-
+ Perform lookups using the PostgreSQL proto-
col. This is described in <a href="pgsql_table.5.html"><b>pgsql_table</b>(5)</a>.
<b>proxy</b> (read-only)
- A lookup table that is implemented via the
- Postfix <a href="proxymap.8.html"><b>proxymap</b>(8)</a> service. The table name
+ A lookup table that is implemented via the
+ Postfix <a href="proxymap.8.html"><b>proxymap</b>(8)</a> service. The table name
syntax is <i>type</i><b>:</b><i>name</i>.
<b>regexp</b> (read-only)
A lookup table based on regular expressions.
- The
file format is described in <a href="regexp_table.5.html"><b>regexp_ta-</b></a>
+ The
file format is described in <a href="regexp_table.5.html"><b>regexp_ta-</b></a>
<a href="regexp_table.5.html"><b>ble</b>(5)</a>.
<b>sdbm</b> An indexed file type based on hashing. This
- is available on systems with support for
+ is available on systems with support for
SDBM databases.
<b>sqlite</b> (read-only)
- Perform lookups from SQLite database files.
+ Perform lookups from SQLite database files.
This is described in <a href="sqlite_table.5.html"><b>sqlite_table</b>(5)</a>.
<b>static</b> (read-only)
- A table that always returns its name as
- lookup
result. For example, <b><a href="DATABASE_README.html#types">static</a>:foobar</b>
- always returns the string <b>foobar</b> as lookup
+ A table that always returns its name as
+ lookup
result. For example, <b><a href="DATABASE_README.html#types">static</a>:foobar</b>
+ always returns the string <b>foobar</b> as lookup
result.
<b>tcp</b> (read-only)
Perform lookups using a simple request-reply
- protocol
that is described in <a href="tcp_table.5.html"><b>tcp_table</b>(5)</a>.
+ protocol
that is described in <a href="tcp_table.5.html"><b>tcp_table</b>(5)</a>.
<b>texthash</b> (read-only)
- Produces similar results as hash: files,
+ Produces similar results as hash: files,
except that you don't need to run the
- <a href="postmap.1.html"><b>postmap</b>(1)</a> command before you can use the
- file, and that it does not detect changes
+ <a href="postmap.1.html"><b>postmap</b>(1)</a> command before you can use the
+ file, and that it does not detect changes
after the file is read.
<b>unix</b> (read-only)
- A limited way to query the UNIX authentica-
+ A limited way to query the UNIX authentica-
tion database. The following tables are
implemented:
<b>unix:passwd.byname</b>
- The table is the UNIX password data-
- base. The key is a login name. The
- result is a password file entry in
+ The table is the UNIX password data-
+ base. The key is a login name. The
+ result is a password file entry in
<b>passwd</b>(5) format.
<b>unix:group.byname</b>
The table is the UNIX group database.
- The key is a group name. The result
- is a group file entry in <b>group</b>(5)
+ The key is a group name. The result
+ is a group file entry in <b>group</b>(5)
format.
- Other table types may exist depending on how Post-
+ Other table types may exist depending on how Post-
fix was built.
- <b>-M</b> Show
<a href="master.5.html"><b>master.cf</b></a> file contents instead of <a href="postconf.5.html"><b>main.cf</b></a>
- file contents. Specify <b>-Mf</b> to fold long lines for
+ <b>-M</b> Show
<a href="master.5.html"><b>master.cf</b></a> file contents instead of <a href="postconf.5.html"><b>main.cf</b></a>
+ file contents. Specify <b>-Mf</b> to fold long lines for
human readability.
If <i>service ...</i> is specified, only the matching ser-
- vices will be output. For example, "<b>postconf -Mf</b>
- <b>inet</b>" will output all services that listen on the
+ vices will be output. For example, "<b>postconf -Mf</b>
+ <b>inet</b>" will output all services that listen on the
network.
- Specify zero or more arguments, each with a <i>ser-</i>
- <i>vice-type</i> name (<b>inet</b>, <b>unix</b>, <b>fifo</b>, or <b>pass</b>) or with
- a <i>service-name.service-type</i> pair, where <i>service-</i>
+ Specify zero or more arguments, each with a <i>ser-</i>
+ <i>vice-type</i> name (<b>inet</b>, <b>unix</b>, <b>fifo</b>, or <b>pass</b>) or with
+ a <i>service-name.service-type</i> pair, where <i>service-</i>
<i>name</i> is the first field of a <a href="master.5.html">master.cf</a> entry.
- This feature is available with Postfix 2.9 and
+ This feature is available with Postfix 2.9 and
later.
- <b>-n</b> Print <a href="postconf.5.html"><b>main.cf</b></a> parameter settings that are explic-
- itly specified in <a href="postconf.5.html"><b>main.cf</b></a>. Specify <b>-nf</b> to fold
- long lines for human readability (Postfix 2.9 and
+ <b>-n</b> Print <a href="postconf.5.html"><b>main.cf</b></a> parameter settings that are explic-
+ itly specified in <a href="postconf.5.html"><b>main.cf</b></a>. Specify <b>-nf</b> to fold
+ long lines for human readability (Postfix 2.9 and
later).
<b>-t</b> [<i>template</i><b>_</b><i>file</i>]
- Display the templates for text that appears at the
- beginning of delivery status notification (DSN)
+ Display the templates for text that appears at the
+ beginning of delivery status notification (DSN)
messages, without expanding $<b>name</b> expressions.
- To override the built-in templates, specify a tem-
- plate file name at the end of the <a href="postconf.1.html"><b>postconf</b>(1)</a> com-
- mand line, or specify a file name in <a href="postconf.5.html"><b>main.cf</b></a> with
+ To override the built-in templates, specify a tem-
+ plate file name at the end of the <a href="postconf.1.html"><b>postconf</b>(1)</a> com-
+ mand line, or specify a file name in <a href="postconf.5.html"><b>main.cf</b></a> with
the <b><a href="postconf.5.html#bounce_template_file">bounce_template_file</a></b> parameter.
To force selection of the built-in templates, spec-
- ify
an empty template file name on the <a href="postconf.1.html"><b>postconf</b>(1)</a>
+ ify
an empty template file name on the <a href="postconf.1.html"><b>postconf</b>(1)</a>
command line (in shell language: "").
- This feature is available with Postfix 2.3 and
+ This feature is available with Postfix 2.3 and
later.
<b>-v</b> Enable verbose logging for debugging purposes. Mul-
- tiple <b>-v</b> options make the software increasingly
+ tiple <b>-v</b> options make the software increasingly
verbose.
- <b>-#</b> Edit the <a href="postconf.5.html"><b>main.cf</b></a> configuration file, and comment
+ <b>-#</b> Edit the <a href="postconf.5.html"><b>main.cf</b></a> configuration file, and comment
out the parameters given on the <a href="postconf.1.html"><b>postconf</b>(1)</a> command
- line, so that those parameters revert to their
- default values. The file is copied to a temporary
- file then renamed into place. Specify a list of
+ line, so that those parameters revert to their
+ default values. The file is copied to a temporary
+ file then renamed into place. Specify a list of
parameter names, not <i>name</i>=<i>value</i> pairs. There is no
- <a href="postconf.1.html"><b>postconf</b>(1)</a> command to perform the reverse opera-
+ <a href="postconf.1.html"><b>postconf</b>(1)</a> command to perform the reverse opera-
tion.
- This feature is available with Postfix 2.6 and
+ This feature is available with Postfix 2.6 and
later.
<b>DIAGNOSTICS</b>
Directory with Postfix configuration files.
<b>CONFIGURATION PARAMETERS</b>
- The following <a href="postconf.5.html"><b>main.cf</b></a> parameters are especially relevant
+ The following <a href="postconf.5.html"><b>main.cf</b></a> parameters are especially relevant
to this program.
- The text below provides only a parameter summary. See
+ The text below provides only a parameter summary. See
<a href="postconf.5.html"><b>postconf</b>(5)</a> for more details including examples.
<b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
- The default location of the Postfix <a href="postconf.5.html">main.cf</a> and
+ The default location of the Postfix <a href="postconf.5.html">main.cf</a> and
<a href="master.5.html">master.cf</a> configuration files.
<b><a href="postconf.5.html#bounce_template_file">bounce_template_file</a> (empty)</b>
- Pathname of a configuration file with bounce mes-
+ Pathname of a configuration file with bounce mes-
sage templates.
<b>FILES</b>
<a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview
<b>LICENSE</b>
- The Secure Mailer license must be distributed with this
+ The Secure Mailer license must be distributed with this
software.
<b>AUTHOR(S)</b>
<p>
How long the <a href="postkick.1.html">postkick(1)</a> command waits for a request to enter the
-server's input buffer before giving up.
+Postfix daemon process input buffer before giving up.
</p>
<p>
<DT><b><a name="authorized_verp_clients">authorized_verp_clients</a>
(default: $<a href="postconf.5.html#mynetworks">mynetworks</a>)</b></DT><DD>
-<p> What SMTP clients are allowed to specify the XVERP command.
+<p> What remote SMTP clients are allowed to specify the XVERP command.
This command requests that mail be delivered one recipient at a
time with a per recipient return address. </p>
(default: no)</b></DT><DD>
<p>
-Enable inter-operability with SMTP clients that implement an obsolete
+Enable inter-operability with remote SMTP clients that implement an obsolete
version of the AUTH command (<a href="http://tools.ietf.org/html/rfc4954">RFC 4954</a>). Examples of such clients
are MicroSoft Outlook Express version 4 and MicroSoft Exchange
version 5.0.
(default: see "postconf -d" output)</b></DT><DD>
<p>
-The default SMTP server response template for a request that is
+The default Postfix SMTP server response template for a request that is
rejected by an RBL-based restriction. This template can be overruled
by specific entries in the optional <a href="postconf.5.html#rbl_reply_maps">rbl_reply_maps</a> lookup table.
</p>
</p>
<p>
-With the default 100 SMTP server process limit, "<a href="postconf.5.html#in_flow_delay">in_flow_delay</a>
+With the default 100
Postfix SMTP server process limit, "<a href="postconf.5.html#in_flow_delay">in_flow_delay</a>
= 1s" limits the mail inflow to 100 messages per second above the
number of messages delivered per second.
</p>
<p>
On a multi-homed firewall with separate Postfix instances listening on the
"inside" and "outside" interfaces, this can prevent each instance from
-being able to reach servers on the "other side" of the firewall. Setting
+being able to reach remote SMTP servers on the "other side" of the
+firewall. Setting
<a href="postconf.5.html#smtp_bind_address">smtp_bind_address</a> to 0.0.0.0 avoids the potential problem for
IPv4, and setting <a href="postconf.5.html#smtp_bind_address6">smtp_bind_address6</a> to :: solves the problem
for IPv6. </p>
<p>
The time after which a client closes an idle internal communication
-channel. The purpose is to allow servers to terminate voluntarily
-after they become idle. This is used, for example, by the address
-resolving and rewriting clients.
+channel. The purpose is to allow Postfix daemon processes to
+terminate voluntarily after they become idle. This is used, for
+example, by the Postfix address resolving and rewriting clients.
</p>
<p> With Postfix 2.4 the default value was reduced from 100s to 5s. </p>
<p>
The time after which a client closes an active internal communication
-channel. The purpose is to allow servers to terminate voluntarily
+channel. The purpose is to allow Postfix daemon processes to
+terminate voluntarily
after reaching their client limit. This is used, for example, by
-the address resolving and rewriting clients.
+the Postfix address resolving and rewriting clients.
</p>
<p>
<DT><b><a name="lmtp_assume_final">lmtp_assume_final</a>
(default: no)</b></DT><DD>
-<p> When an LMTP server announces no DSN support, assume that the
+<p> When a remote LMTP server announces no DSN support, assume that
+the
server performs final delivery, and send "delivered" delivery status
notifications instead of "relayed". The default setting is backwards
compatible to avoid the infinetisimal possibility of breaking
<p>
The effectiveness of cached connections will be determined by the
-number of LMTP servers in use, and the concurrency limit specified
-for the LMTP client. Cached connections are closed under any of
+number of remote LMTP servers in use, and the concurrency limit specified
+for the Postfix LMTP client. Cached connections are closed under any of
the following conditions:
</p>
<ul>
-<li> The LMTP client idle time limit is reached. This limit is
+<li> The Postfix LMTP client idle time limit is reached. This limit is
specified with the Postfix <a href="postconf.5.html#max_idle">max_idle</a> configuration parameter.
<li> A delivery request specifies a different destination than the
reached. This limit is specified with the Postfix <a href="postconf.5.html#max_use">max_use</a>
configuration parameter.
-<li> Upon the onset of another delivery request, the LMTP server
+<li> Upon the onset of another delivery request, the remote LMTP server
associated with the current session does not respond to the RSET
command.
</ul>
<p>
-Most of these limitations will be removed after Postfix implements
+Most of these limitations have been with the Postfix
a connection cache that is shared among multiple LMTP client
programs.
</p>
<DT><b><a name="lmtp_connect_timeout">lmtp_connect_timeout</a>
(default: 0s)</b></DT><DD>
-<p> The LMTP client time limit for completing a TCP connection, or
+<p> The Postfix LMTP client time limit for completing a TCP connection, or
zero (use the operating system built-in time limit). When no
connection can be made within the deadline, the LMTP client tries
the next address on the mail exchanger list. </p>
<DT><b><a name="lmtp_data_done_timeout">lmtp_data_done_timeout</a>
(default: 600s)</b></DT><DD>
-<p> The LMTP client time limit for sending the LMTP ".", and for
-receiving the server response. When no response is received within
-the deadline, a warning is logged that the mail may be delivered
-multiple times. </p>
+<p> The Postfix LMTP client time limit for sending the LMTP ".",
+and for receiving the remote LMTP server response. When no response
+is received within the deadline, a warning is logged that the mail
+may be delivered multiple times. </p>
<p>
Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
(default: 120s)</b></DT><DD>
<p>
-The LMTP client time limit for sending the LMTP DATA command, and
-for receiving the server response.
+The Postfix LMTP client time limit for sending the LMTP DATA command,
+and
+for receiving the remote LMTP server response.
</p>
<p>
(default: 180s)</b></DT><DD>
<p>
-The LMTP client time limit for sending the LMTP message content.
+The Postfix LMTP client time limit for sending the LMTP message
+content.
When the connection stalls for more than $<a href="postconf.5.html#lmtp_data_xfer_timeout">lmtp_data_xfer_timeout</a>
the LMTP client terminates the transfer.
</p>
<p> Lookup tables, indexed by the remote LMTP server address, with
case insensitive lists of LHLO keywords (pipelining, starttls,
-auth, etc.) that the LMTP client will ignore in the LHLO response
+auth, etc.) that the Postfix LMTP client will ignore in the LHLO
+response
from a remote LMTP server. See <a href="postconf.5.html#lmtp_discard_lhlo_keywords">lmtp_discard_lhlo_keywords</a> for
details. The table is not indexed by hostname for consistency with
<a href="postconf.5.html#smtpd_discard_ehlo_keyword_address_maps">smtpd_discard_ehlo_keyword_address_maps</a>. </p>
(default: empty)</b></DT><DD>
<p> A case insensitive list of LHLO keywords (pipelining, starttls,
-auth, etc.) that the LMTP client will ignore in the LHLO response
+auth, etc.) that the Postfix LMTP client will ignore in the LHLO
+response
from a remote LMTP server. </p>
<p> This feature is available in Postfix 2.3 and later. </p>
<DT><b><a name="lmtp_lhlo_timeout">lmtp_lhlo_timeout</a>
(default: 300s)</b></DT><DD>
-<p> The LMTP client time limit for sending the LHLO command, and
-for receiving the initial server response. </p>
+<p> The Postfix LMTP client time limit for sending the LHLO command,
+and for receiving the initial remote LMTP server response. </p>
<p> Time units: s (seconds), m (minutes), h (hours), d (days), w
(weeks). The default time unit is s (seconds). </p>
(default: 300s)</b></DT><DD>
<p>
-The LMTP client time limit for sending the MAIL FROM command, and
-for receiving the server response.
+The Postfix LMTP client time limit for sending the MAIL FROM command,
+and for receiving the remote LMTP server response.
</p>
<p>
(default: 300s)</b></DT><DD>
<p>
-The LMTP client time limit for sending the QUIT command, and for
-receiving the server response.
+The Postfix LMTP client time limit for sending the QUIT command,
+and for receiving the remote LMTP server response.
</p>
<p>
(default: 300s)</b></DT><DD>
<p>
-The LMTP client time limit for sending the RCPT TO command, and
-for receiving the server response.
+The Postfix LMTP client time limit for sending the RCPT TO command,
+and for receiving the remote LMTP server response.
</p>
<p>
<DT><b><a name="lmtp_rset_timeout">lmtp_rset_timeout</a>
(default: 20s)</b></DT><DD>
-<p> The LMTP client time limit for sending the RSET command, and
-for receiving the server response. The LMTP client sends RSET in
+<p> The Postfix LMTP client time limit for sending the RSET command,
+and for receiving the remote LMTP server response. The LMTP client
+sends RSET in
order to finish a recipient address probe, or to verify that a
cached connection is still alive. </p>
(default: empty)</b></DT><DD>
<p>
-Optional LMTP client lookup tables with one username:password entry
+Optional Postfix LMTP client lookup tables with one username:password entry
per host or domain. If a remote host or domain has no username:password
entry, then the Postfix LMTP client will not attempt to authenticate
to the remote host.
(default: no)</b></DT><DD>
<p>
-Send an XFORWARD command to the LMTP server when the LMTP LHLO
+Send an XFORWARD command to the remote LMTP server when the LMTP LHLO
server response announces XFORWARD support. This allows an <a href="lmtp.8.html">lmtp(8)</a>
delivery agent, used for content filter message injection, to
forward the name, address, protocol and HELO name of the original
(default: 300s)</b></DT><DD>
<p>
-The LMTP client time limit for sending the XFORWARD command, and
-for receiving the server response.
+The Postfix LMTP client time limit for sending the XFORWARD command,
+and for receiving the remote LMTP server response.
</p>
<p>
<dt><b><a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a> </b></dt>
<dd> Append the domain name in $<a href="postconf.5.html#myorigin">myorigin</a> or $<a href="postconf.5.html#mydomain">mydomain</a> when the
-client TLS certificate fingerprint is listed in $<a href="postconf.5.html#relay_clientcerts">relay_clientcerts</a>.
+remote SMTP client TLS certificate fingerprint or public key fingerprint
+(Postfix 2.9 and later) is listed in $<a href="postconf.5.html#relay_clientcerts">relay_clientcerts</a>.
The fingerprint digest algorithm is configurable via the
<a href="postconf.5.html#smtpd_tls_fingerprint_digest">smtpd_tls_fingerprint_digest</a> parameter (hard-coded as md5 prior to
Postfix version 2.5). </dd>
<dt><b><a href="postconf.5.html#permit_tls_all_clientcerts">permit_tls_all_clientcerts</a> </b></dt>
<dd> Append the domain name in $<a href="postconf.5.html#myorigin">myorigin</a> or $<a href="postconf.5.html#mydomain">mydomain</a> when the
-client TLS certificate is successfully verified, regardless of
+remote SMTP client TLS certificate is successfully verified, regardless of
whether it is listed on the server, and regardless of the certifying
authority. </dd>
(default: see "postconf -d" output)</b></DT><DD>
<p>
-The list of "trusted" SMTP clients that have more privileges than
+The list of "trusted" remote SMTP clients that have more privileges than
"strangers".
</p>
"trust" only the local machine. </p>
<li><p>Specify "<a href="postconf.5.html#mynetworks_style">mynetworks_style</a> = subnet" when Postfix
-should "trust" SMTP clients in the same IP subnetworks as the local
+should "trust" remote SMTP clients in the same IP subnetworks as the local
machine. On Linux, this works correctly only with interfaces
specified with the "ifconfig" command. </p>
<li><p>Specify "<a href="postconf.5.html#mynetworks_style">mynetworks_style</a> = class" when Postfix should
-"trust" SMTP clients in the same IP class A/B/C networks as the
+"trust" remote SMTP clients in the same IP class A/B/C networks as the
local machine. Don't do this with a dialup site - it would cause
Postfix to "trust" your entire provider's network. Instead, specify
an explicit <a href="postconf.5.html#mynetworks">mynetworks</a> list by hand, as described with the <a href="postconf.5.html#mynetworks">mynetworks</a>
<DT><b><a name="postscreen_bare_newline_action">postscreen_bare_newline_action</a>
(default: ignore)</b></DT><DD>
-<p> The action that <a href="postscreen.8.html">postscreen(8)</a> takes when an SMTP client sends
+<p> The action that <a href="postscreen.8.html">postscreen(8)</a> takes when a remote SMTP client sends
a bare newline character, that is, a newline not preceded by carriage
return. Specify one of the following: </p>
(default: no)</b></DT><DD>
<p> Enable "bare newline" SMTP protocol tests in the <a href="postscreen.8.html">postscreen(8)</a>
-server. These tests are expensive: a client must disconnect after
+server. These tests are expensive: a remote SMTP client must
+disconnect after
it passes the test, before it can talk to a real Postfix SMTP server.
</p>
<p> The amount of time that <a href="postscreen.8.html">postscreen(8)</a> will use the result from
a successful "bare newline" SMTP protocol test. During this
time, the client IP address is excluded from this test. The default
-is long because a client must disconnect after it passes the test,
+is long because a remote SMTP client must disconnect after it passes
+the test,
before it can talk to a real Postfix SMTP server. </p>
<p> Specify a non-zero time value (an integral value plus an optional
<DT><b><a name="postscreen_blacklist_action">postscreen_blacklist_action</a>
(default: ignore)</b></DT><DD>
-<p> The action that <a href="postscreen.8.html">postscreen(8)</a> takes when an SMTP client is
+<p> The action that <a href="postscreen.8.html">postscreen(8)</a> takes when a remote SMTP client is
permanently blacklisted with the <a href="postconf.5.html#postscreen_access_list">postscreen_access_list</a> parameter.
Specify one of the following: </p>
<DT><b><a name="postscreen_client_connection_count_limit">postscreen_client_connection_count_limit</a>
(default: $<a href="postconf.5.html#smtpd_client_connection_count_limit">smtpd_client_connection_count_limit</a>)</b></DT><DD>
-<p> How many simultaneous connections any client is allowed to have
+<p> How many simultaneous connections any remote SMTP client is
+allowed to have
with the <a href="postscreen.8.html">postscreen(8)</a> daemon. By default, this limit is the same
as with the Postfix SMTP server. Note that the triage process can
take several seconds, with the time spent in <a href="postconf.5.html#postscreen_greet_wait">postscreen_greet_wait</a>
<DT><b><a name="postscreen_dnsbl_action">postscreen_dnsbl_action</a>
(default: ignore)</b></DT><DD>
-<p>The action that <a href="postscreen.8.html">postscreen(8)</a> takes when an SMTP client's combined
+<p>The action that <a href="postscreen.8.html">postscreen(8)</a> takes when a remote SMTP client's combined
DNSBL score is equal to or greater than a threshold (as defined
with the <a href="postconf.5.html#postscreen_dnsbl_sites">postscreen_dnsbl_sites</a> and <a href="postconf.5.html#postscreen_dnsbl_threshold">postscreen_dnsbl_threshold</a>
parameters). Specify one of the following: </p>
<p> When a client's score is equal to or greater than the threshold
specified with <a href="postconf.5.html#postscreen_dnsbl_threshold">postscreen_dnsbl_threshold</a>, <a href="postscreen.8.html">postscreen(8)</a> can drop
-the connection with the SMTP client. </p>
+the connection with the remote SMTP client. </p>
<p> Specify a list of domain=filter*weight entries, separated by
comma or whitespace. </p>
or more ";"-separated numbers or number..number ranges. </p>
<li> <p> When no "*weight" is specified, <a href="postscreen.8.html">postscreen(8)</a> increments
-the SMTP client's DNSBL score by 1. Otherwise, the weight must be
+the remote SMTP client's DNSBL score by 1. Otherwise, the weight must be
an integral number, and <a href="postscreen.8.html">postscreen(8)</a> adds the specified weight to
-the SMTP client's DNSBL score. Specify a negative number for
+the remote SMTP client's DNSBL score. Specify a negative number for
whitelisting. </p>
<li> <p> When one <a href="postconf.5.html#postscreen_dnsbl_sites">postscreen_dnsbl_sites</a> entry produces multiple
<DT><b><a name="postscreen_dnsbl_threshold">postscreen_dnsbl_threshold</a>
(default: 1)</b></DT><DD>
-<p> The inclusive lower bound for blocking an SMTP client, based on
+<p> The inclusive lower bound for blocking a remote SMTP client, based on
its combined DNSBL score as defined with the <a href="postconf.5.html#postscreen_dnsbl_sites">postscreen_dnsbl_sites</a>
parameter. </p>
<DT><b><a name="postscreen_enforce_tls">postscreen_enforce_tls</a>
(default: $<a href="postconf.5.html#smtpd_enforce_tls">smtpd_enforce_tls</a>)</b></DT><DD>
-<p> Mandatory TLS: announce STARTTLS support to SMTP clients, and
+<p> Mandatory TLS: announce STARTTLS support to remote SMTP clients, and
require that clients use TLS encryption. See smtpd_postscreen_enforce_tls
for details. </p>
<DT><b><a name="postscreen_greet_action">postscreen_greet_action</a>
(default: ignore)</b></DT><DD>
-<p>The action that <a href="postscreen.8.html">postscreen(8)</a> takes when an SMTP client speaks
+<p>The action that <a href="postscreen.8.html">postscreen(8)</a> takes when a remote SMTP client speaks
before its turn within the time specified with the <a href="postconf.5.html#postscreen_greet_wait">postscreen_greet_wait</a>
parameter. Specify one of the following: </p>
</dl>
-<p> In either case, <a href="postscreen.8.html">postscreen(8)</a> will not whitelist the SMTP client
+<p> In either case, <a href="postscreen.8.html">postscreen(8)</a> will not whitelist the remote SMTP client
IP address. </p>
<p> This feature is available in Postfix 2.8. </p>
<DT><b><a name="postscreen_non_smtp_command_action">postscreen_non_smtp_command_action</a>
(default: drop)</b></DT><DD>
-<p> The action that <a href="postscreen.8.html">postscreen(8)</a> takes when an SMTP client sends
+<p> The action that <a href="postscreen.8.html">postscreen(8)</a> takes when a remote SMTP client sends
non-SMTP commands as specified with the <a href="postconf.5.html#postscreen_forbidden_commands">postscreen_forbidden_commands</a>
parameter. Specify one of the following: </p>
<DT><b><a name="postscreen_pipelining_action">postscreen_pipelining_action</a>
(default: enforce)</b></DT><DD>
-<p> The action that <a href="postscreen.8.html">postscreen(8)</a> takes when an SMTP client sends
+<p> The action that <a href="postscreen.8.html">postscreen(8)</a> takes when a remote SMTP client
+sends
multiple commands instead of sending one command and waiting for
the server to respond. Specify one of the following: </p>
(default: $<a href="postconf.5.html#default_process_limit">default_process_limit</a>)</b></DT><DD>
<p> The number of clients that can be waiting for service from a
-real SMTP server process. When this queue is full, all clients will
+real Postfix SMTP server process. When this queue is full, all
+clients will
receive a 421 reponse. </p>
<p> This feature is available in Postfix 2.8. </p>
(default: $<a href="postconf.5.html#default_process_limit">default_process_limit</a>)</b></DT><DD>
<p> The number of non-whitelisted clients that can be waiting for
-a decision whether they will receive service from a real SMTP server
+a decision whether they will receive service from a real Postfix
+SMTP server
process. When this queue is full, all non-whitelisted clients will
receive a 421 reponse. </p>
<DT><b><a name="postscreen_reject_footer">postscreen_reject_footer</a>
(default: $<a href="postconf.5.html#smtpd_reject_footer">smtpd_reject_footer</a>)</b></DT><DD>
-<p> Optional information that is appended after a 4XX or 5XX server
+<p> Optional information that is appended after a 4XX or 5XX
+<a href="postscreen.8.html">postscreen(8)</a> server
response. See <a href="postconf.5.html#smtpd_reject_footer">smtpd_reject_footer</a> for further details. </p>
<p> This feature is available in Postfix 2.8 and later. </p>
<DT><b><a name="postscreen_use_tls">postscreen_use_tls</a>
(default: $<a href="postconf.5.html#smtpd_use_tls">smtpd_use_tls</a>)</b></DT><DD>
-<p> Opportunistic TLS: announce STARTTLS support to SMTP clients,
+<p> Opportunistic TLS: announce STARTTLS support to remote SMTP clients,
but do not require that clients use TLS encryption. </p>
<p> This feature is available in Postfix 2.8 and later.
(default: 10s)</b></DT><DD>
<p> How much time a <a href="postscreen.8.html">postscreen(8)</a> process may take to respond to
-an SMTP client command or to perform a cache operation before it
+a remote SMTP client command or to perform a cache operation before it
is terminated by a built-in watchdog timer. This is a safety
mechanism that prevents <a href="postscreen.8.html">postscreen(8)</a> from becoming non-responsive
due to a bug in Postfix itself or in system software. To avoid
(default: <a href="DATABASE_README.html#types">static</a>:all)</b></DT><DD>
<p> A list of local <a href="postscreen.8.html">postscreen(8)</a> server IP addresses where a
-non-whitelisted SMTP client can obtain <a href="postscreen.8.html">postscreen(8)</a>'s temporary
+non-whitelisted
remote SMTP client can obtain <a href="postscreen.8.html">postscreen(8)</a>'s temporary
whitelist status. This status is required before the client can
talk to a Postfix SMTP server process. By default, a client can
obtain <a href="postscreen.8.html">postscreen(8)</a>'s whitelist status on any local <a href="postscreen.8.html">postscreen(8)</a>
(default: empty)</b></DT><DD>
<p>
-What clients are allowed to connect to the QMQP server port.
+What remote QMQP clients are allowed to connect to the Postfix QMQP
+server port.
</p>
<p>
(default: 1s)</b></DT><DD>
<p>
-How long the QMQP server will pause before sending a negative reply
-to the client. The purpose is to slow down confused or malicious
-clients.
+How long the Postfix QMQP server will pause before sending a negative
+reply to the remote QMQP client. The purpose is to slow down confused
+or malicious clients.
</p>
<p>
<p>
The time limit for sending or receiving information over the network.
If a read or write operation blocks for more than $<a href="postconf.5.html#qmqpd_timeout">qmqpd_timeout</a>
-seconds the QMQP server gives up and disconnects.
+seconds the Postfix QMQP server gives up and disconnects.
</p>
<p>
<p>
The minimal amount of free space in bytes in the queue file system
-that is needed to receive mail. This is currently used by the SMTP
-server to decide if it will accept any mail at all.
+that is needed to receive mail. This is currently used by the
+Postfix SMTP server to decide if it will accept any mail at all.
</p>
<p>
<DT><b><a name="relay_clientcerts">relay_clientcerts</a>
(default: empty)</b></DT><DD>
-<p> List of tables with remote SMTP client-certificate fingerprints
-for which the Postfix SMTP server will allow access with the
-<a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a> feature.
-The fingerprint digest algorithm is configurable via the
+<p> List of tables with remote SMTP client-certificate fingerprints or
+public key fingerprints (Postfix 2.9 and later) for which the Postfix
+SMTP server will allow access with the <a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a>
+feature. The fingerprint digest algorithm is configurable via the
<a href="postconf.5.html#smtpd_tls_fingerprint_digest">smtpd_tls_fingerprint_digest</a> parameter (hard-coded as md5 prior to
Postfix version 2.5). </p>
</p>
<p>
-With "<a href="postconf.5.html#smtp_always_send_ehlo">smtp_always_send_ehlo</a> = no", Postfix sends EHLO only when
+With "<a href="postconf.5.html#smtp_always_send_ehlo">smtp_always_send_ehlo</a> = no", the Postfix SMTP client sends
+EHLO only when
the word "ESMTP" appears in the server greeting banner (example:
220 spike.porcupine.org ESMTP Postfix).
</p>
(default: 30s)</b></DT><DD>
<p>
-The SMTP client time limit for completing a TCP connection, or
+The Postfix SMTP client time limit for completing a TCP connection, or
zero (use the operating system built-in time limit).
</p>
(default: 600s)</b></DT><DD>
<p>
-The SMTP client time limit for sending the SMTP ".", and for receiving
-the server response.
+The Postfix SMTP client time limit for sending the SMTP ".", and
+for receiving the remote SMTP server response.
</p>
<p>
(default: 120s)</b></DT><DD>
<p>
-The SMTP client time limit for sending the SMTP DATA command, and for
-receiving the server response.
+The Postfix SMTP client time limit for sending the SMTP DATA command,
+and for receiving the remote SMTP server response.
</p>
<p>
(default: 180s)</b></DT><DD>
<p>
-The SMTP client time limit for sending the SMTP message content.
+The Postfix SMTP client time limit for sending the SMTP message content.
When the connection makes no progress for more than $<a href="postconf.5.html#smtp_data_xfer_timeout">smtp_data_xfer_timeout</a>
seconds the Postfix SMTP client terminates the transfer.
</p>
</p>
<p>
-Note: Postfix always ignores MX records with equal or worse preference
+Note: the Postfix SMTP client always ignores MX records with equal
+or worse preference
than the local MTA itself.
</p>
(default: empty)</b></DT><DD>
<p> Optional lookup tables that perform address rewriting in the
-SMTP client, typically to transform a locally valid address into
+Postfix SMTP client, typically to transform a locally valid address into
a globally valid address when sending mail across the Internet.
This is needed when the local machine does not have its own Internet
domain name, but uses something like <i>localdomain.local</i>
(default: 300s)</b></DT><DD>
<p>
-The SMTP client time limit for sending the HELO or EHLO command,
-and for receiving the initial server response.
+The Postfix SMTP client time limit for sending the HELO or EHLO command,
+and for receiving the initial remote SMTP server response.
</p>
<p>
(default: 300s)</b></DT><DD>
<p>
-The SMTP client time limit for sending the MAIL FROM command, and
-for receiving the server response.
+The Postfix SMTP client time limit for sending the MAIL FROM command,
+and for receiving the remote SMTP server response.
</p>
<p>
<p>
The maximal number of MX (mail exchanger) IP addresses that can
-result from mail exchanger lookups, or zero (no limit). Prior to
+result from Postfix SMTP client mail exchanger lookups, or zero (no
+limit). Prior to
Postfix version 2.3, this limit was disabled by default.
</p>
(default: 2)</b></DT><DD>
<p> The maximal number of SMTP sessions per delivery request before
-giving up or delivering to a fall-back <a href="postconf.5.html#relayhost">relay host</a>, or zero (no
+the Postfix SMTP client
+gives up or delivers to a fall-back <a href="postconf.5.html#relayhost">relay host</a>, or zero (no
limit). This restriction ignores sessions that fail to complete the
SMTP initial handshake (Postfix version 2.2 and earlier) or that fail to
complete the EHLO and TLS handshake (Postfix version 2.3 and later). </p>
(default: 300s)</b></DT><DD>
<p>
-The SMTP client time limit for sending the QUIT command, and for
-receiving the server response.
+The Postfix SMTP client time limit for sending the QUIT command,
+and for receiving the remote SMTP server response.
</p>
<p>
(default: yes)</b></DT><DD>
<p>
-Quote addresses in SMTP MAIL FROM and RCPT TO commands as required
+Quote addresses in Postfix SMTP client MAIL FROM and RCPT TO commands
+as required
by <a href="http://tools.ietf.org/html/rfc2821">RFC 2821</a>. This includes putting quotes around an address localpart
that ends in ".".
</p>
(default: 300s)</b></DT><DD>
<p>
-The SMTP client time limit for sending the SMTP RCPT TO command, and
-for receiving the server response.
+The Postfix SMTP client time limit for sending the SMTP RCPT TO
+command, and for receiving the remote SMTP server response.
</p>
<p>
<DT><b><a name="smtp_rset_timeout">smtp_rset_timeout</a>
(default: 20s)</b></DT><DD>
-<p> The SMTP client time limit for sending the RSET command, and
-for receiving the server response. The SMTP client sends RSET in
+<p> The Postfix SMTP client time limit for sending the RSET command,
+and for receiving the remote SMTP server response. The SMTP client
+sends RSET in
order to finish a recipient address probe, or to verify that a
cached session is still usable. </p>
(default: empty)</b></DT><DD>
<p>
-Optional SMTP client lookup tables with one username:password entry
+Optional Postfix SMTP client lookup tables with one username:password
+entry
per remote hostname or domain, or sender address when sender-dependent
authentication is enabled. If no username:password entry is found,
then the Postfix SMTP client will not
</p>
<p>
-This allows an "smtp" delivery agent, used for injecting mail into
+This allows a Postfix SMTP delivery agent, used for injecting mail
+into
a content filter, to forward the name, address, protocol and HELO
name of the original client to the content filter and downstream
queuing SMTP server. This can produce more useful logging than
</p>
<p>
-By default, Postfix moves on the next mail exchanger. Specify
+By default, the Postfix SMTP client moves on the next mail exchanger.
+Specify
"<a href="postconf.5.html#smtp_skip_4xx_greeting">smtp_skip_4xx_greeting</a> = no" if Postfix should defer delivery
immediately.
</p>
<p> This feature is available in Postfix 2.0 and earlier.
-Later Postfix versions always skip SMTP servers that greet with a
+Later Postfix versions always skip remote SMTP servers that greet
+with a
4XX status code. </p>
(default: yes)</b></DT><DD>
<p>
-Skip SMTP servers that greet with a 5XX status code (go away, do
+Skip remote SMTP servers that greet with a 5XX status code (go away,
+do
not try again later).
</p>
<DT><b><a name="smtp_tls_fingerprint_cert_match">smtp_tls_fingerprint_cert_match</a>
(default: empty)</b></DT><DD>
-<p> List of acceptable remote SMTP server certificate fingerprints
-for the "fingerprint" TLS security level (<b><a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a></b> =
-fingerprint). At this security level, certificate authorities are
-not used, and certificate expiration times are ignored. Instead,
-server certificates are verified directly via their "fingerprint". The
-fingerprint is a message digest of the server certificate. The digest
-algorithm is selected via the <b><a href="postconf.5.html#smtp_tls_fingerprint_digest">smtp_tls_fingerprint_digest</a></b>
+<p> List of acceptable remote SMTP server certificate fingerprints for
+the "fingerprint" TLS security level (<b><a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a></b> =
+fingerprint). At this security level, certificate authorities are not
+used, and certificate expiration times are ignored. Instead, server
+certificates are verified directly via their certificate fingerprint
+or public key fingerprint (Postfix 2.9 and later). The fingerprint
+is a message digest of the server certificate (or public key). The
+digest algorithm is selected via the <b><a href="postconf.5.html#smtp_tls_fingerprint_digest">smtp_tls_fingerprint_digest</a></b>
parameter. </p>
<p> When an <b><a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a></b> table entry specifies the
<p> The message digest algorithm used to construct remote SMTP server
certificate fingerprints. At the "fingerprint" TLS security level
(<b><a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a></b> = fingerprint), the server certificate is
-verified by directly matching its <i>fingerprint</i>. The fingerprint
-is the message digest of the server certificate using the selected
+verified by directly matching its certificate fingerprint or its public
+key fingerprint (Postfix 2.9 and later). The fingerprint is the
+message digest of the server certificate (or its public key)
+using the selected
algorithm. With a digest algorithm resistant to "second pre-image"
attacks, it is not feasible to create a new public key and a matching
-certificate that has the same fingerprint. </p>
+certificate (or public/private key-pair) that has the same fingerprint. </p>
<p> The default algorithm is <b>md5</b>; this is consistent with
the backwards compatible setting of the digest used to verify client
</pre>
</blockquote>
+<p> Public key fingerprints are more difficult to extract, however,
+the SHA-1 public key fingerprint is often present as the value of the
+"Subject Key Identifier" extension in X.509v3 certificates. The Postfix
+SMTP server and client log the peer certificate fingerprint and public
+key fingerprint when TLS loglevel is 1 or higher. </p>
+
<p> This feature is available in Postfix 2.5 and later. </p>
<dl compact>
-<dt> </dt> <dd> 0 Disable logging of TLS activity. </dd>
+<dt> </dt> <dd> 0 Log only a summary message on TLS handshake completion
+— no logging of remote SMTP server certificate trust-chain
+verification errors if server certificate verification is not required.
+With Postfix 2.8 and earlier, disable logging of TLS activity. </dd>
-<dt> </dt> <dd> 1 Log TLS handshake and certificate information. </dd>
+<dt> </dt> <dd> 1 Also log remote SMTP server trust-chain verification
+errors and peer certificate summary information. With Postfix 2.8
+and earlier, log TLS handshake and certificate information. </dd>
-<dt> </dt> <dd> 2 Log levels during TLS negotiation. </dd>
+<dt> </dt> <dd> 2 Also log levels during TLS negotiation. </dd>
-<dt> </dt> <dd> 3 Log hexadecimal and ASCII dump of TLS negotiation
+<dt> </dt> <dd> 3 Also log hexadecimal and ASCII dump of TLS negotiation
process. </dd>
-<dt> </dt> <dd> 4 Log hexadecimal and ASCII dump of complete
+<dt> </dt> <dd> 4 Also log hexadecimal and ASCII dump of complete
transmission after STARTTLS. </dd>
</dl>
-<p> Use "<a href="postconf.5.html#smtp_tls_loglevel">smtp_tls_loglevel</a> = 3" only in case of problems. Use of
-loglevel 4 is strongly discouraged. </p>
+<p> Do not use "<a href="postconf.5.html#smtp_tls_loglevel">smtp_tls_loglevel</a> = 2" or higher except in case of
+problems. Use of loglevel 4 is strongly discouraged. </p>
<p> This feature is available in Postfix 2.2 and later. </p>
(default: empty)</b></DT><DD>
<p> Additional list of ciphers or cipher types to exclude from the
-SMTP client cipher list at mandatory TLS security levels. This list
+Postfix SMTP client cipher list at mandatory TLS security levels. This list
works in addition to the exclusions listed with <a href="postconf.5.html#smtp_tls_exclude_ciphers">smtp_tls_exclude_ciphers</a>
(see there for syntax details). </p>
level, there are no trusted certificate authorities. The certificate
trust chain, expiration date, ... are not checked. Instead,
the optional <b>match</b> attribute, or else the <a href="postconf.5.html">main.cf</a>
-<b><a href="postconf.5.html#smtp_tls_fingerprint_cert_match">smtp_tls_fingerprint_cert_match</a></b> parameter, lists the
-valid "fingerprints" of the server certificate. The digest
+<b><a href="postconf.5.html#smtp_tls_fingerprint_cert_match">smtp_tls_fingerprint_cert_match</a></b> parameter, lists the certificate
+fingerprints or the public key fingerprint (Postfix 2.9 and later)
+of the valid server certificate. The digest
algorithm used to calculate the fingerprint is selected by the
<b><a href="postconf.5.html#smtp_tls_fingerprint_digest">smtp_tls_fingerprint_digest</a></b> parameter. Multiple fingerprints can
be combined with a "|" delimiter in a single match attribute, or multiple
<DT><b><a name="smtp_tls_secure_cert_match">smtp_tls_secure_cert_match</a>
(default: nexthop, dot-nexthop)</b></DT><DD>
-<p> The server certificate peername verification method for the
+<p> How the Postfix SMTP client verifies the server certificate
+peername for the
"secure" TLS security level. In a "secure" TLS policy table
($<a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a>) entry the optional "match" attribute
overrides this <a href="postconf.5.html">main.cf</a> setting. </p>
<dt><b>fingerprint</b></dt> <dd>Certificate fingerprint
verification. Available with Postfix 2.5 and later. At this security
level, there are no trusted certificate authorities. The certificate
-trust chain, expiration date, ... are not checked. Instead,
-the <b><a href="postconf.5.html#smtp_tls_fingerprint_cert_match">smtp_tls_fingerprint_cert_match</a></b> parameter lists
-the valid "fingerprints" of the server certificate. The digest
+trust chain, expiration date, ... are not checked. Instead, the
+<b><a href="postconf.5.html#smtp_tls_fingerprint_cert_match">smtp_tls_fingerprint_cert_match</a></b> parameter lists the certificate
+fingerprint or public key fingerprint (Postfix 2.9 and later) of
+the valid server certificate. The digest
algorithm used to calculate the fingerprint is selected by the
<b><a href="postconf.5.html#smtp_tls_fingerprint_digest">smtp_tls_fingerprint_digest</a></b> parameter. </dd>
<DT><b><a name="smtp_tls_verify_cert_match">smtp_tls_verify_cert_match</a>
(default: hostname)</b></DT><DD>
-<p> The server certificate peername verification method for the
+<p> How the Postfix SMTP client verifies the server certificate
+peername for the
"verify" TLS security level. In a "verify" TLS policy table
($<a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a>) entry the optional "match" attribute
overrides this <a href="postconf.5.html">main.cf</a> setting. </p>
(default: 300s)</b></DT><DD>
<p>
-The SMTP client time limit for sending the XFORWARD command, and
-for receiving the server response.
+The Postfix SMTP client time limit for sending the XFORWARD command,
+and for receiving the remote SMTP server response.
</p>
<p>
<DT><b><a name="smtpd_authorized_verp_clients">smtpd_authorized_verp_clients</a>
(default: $<a href="postconf.5.html#authorized_verp_clients">authorized_verp_clients</a>)</b></DT><DD>
-<p> What SMTP clients are allowed to specify the XVERP command.
+<p> What remote SMTP clients are allowed to specify the XVERP command.
This command requests that mail be delivered one recipient at a
time with a per recipient return address. </p>
(default: empty)</b></DT><DD>
<p>
-What SMTP clients are allowed to use the XCLIENT feature. This
-command overrides SMTP client information that is used for access
+What remote SMTP clients are allowed to use the XCLIENT feature. This
+command overrides remote SMTP client information that is used for access
control. Typical use is for SMTP-based content filters, fetchmail-like
programs, or SMTP server access rule testing. See the <a href="XCLIENT_README.html">XCLIENT_README</a>
document for details.
(default: empty)</b></DT><DD>
<p>
-What SMTP clients are allowed to use the XFORWARD feature. This
+What remote SMTP clients are allowed to use the XFORWARD feature. This
command forwards information that is used to improve logging after
SMTP-based content filters. See the <a href="XFORWARD_README.html">XFORWARD_README</a> document for
details.
(default: empty)</b></DT><DD>
<p>
-Optional SMTP server access restrictions in the context of a client
-SMTP connection request.
+Optional Postfix SMTP server access restrictions in the context of
+a remote SMTP client connection request.
See <a href="SMTPD_ACCESS_README.html">SMTPD_ACCESS_README</a>, section "Delayed evaluation of SMTP access
restriction lists" for a discussion of evaluation context and time.
</p>
<dt><b><a name="check_ccert_access">check_ccert_access</a> <i><a href="DATABASE_README.html">type:table</a></i></b></dt>
-<dd> Use the client certificate fingerprint as lookup key for the
-specified <a href="access.5.html">access(5)</a> database; with Postfix version 2.2, also require that
-the SMTP client certificate is verified successfully.
+<dd> Use the remote SMTP client certificate fingerprint or the public key
+fingerprint (Postfix 2.9 and later) as lookup key for the specified
+<a href="access.5.html">access(5)</a> database; with Postfix version 2.2, also require that the
+remote SMTP client certificate is verified successfully.
The fingerprint digest algorithm is configurable via the
<a href="postconf.5.html#smtpd_tls_fingerprint_digest">smtpd_tls_fingerprint_digest</a> parameter (hard-coded as md5 prior to
Postfix version 2.5). This feature is available with Postfix version
<dt><b><a name="permit_tls_clientcerts">permit_tls_clientcerts</a></b></dt>
<dd>Permit the request when the remote SMTP client certificate
-fingerprint is listed in $<a href="postconf.5.html#relay_clientcerts">relay_clientcerts</a>.
+fingerprint or public key fingerprint (Postfix 2.9 and later) is
+listed in $<a href="postconf.5.html#relay_clientcerts">relay_clientcerts</a>.
The fingerprint digest algorithm is configurable via the
<a href="postconf.5.html#smtpd_tls_fingerprint_digest">smtpd_tls_fingerprint_digest</a> parameter (hard-coded as md5 prior to
Postfix version 2.5). This feature is available with Postfix version
<p> Postpone the start of an SMTP mail transaction until a valid
RCPT TO command is received. Specify "no" to create a mail transaction
-as soon as the SMTP server receives a valid MAIL FROM command. </p>
+as soon as the Postfix SMTP server receives a valid MAIL FROM
+command. </p>
<p> With sites that reject lots of mail, the default setting reduces
the use of
<p> Lookup tables, indexed by the remote SMTP client address, with
case insensitive lists of EHLO keywords (pipelining, starttls, auth,
-etc.) that the SMTP server will not send in the EHLO response to a
+etc.) that the Postfix SMTP server will not send in the EHLO response
+to a
remote SMTP client. See <a href="postconf.5.html#smtpd_discard_ehlo_keywords">smtpd_discard_ehlo_keywords</a> for details.
The table is not searched by hostname for robustness reasons. </p>
(default: empty)</b></DT><DD>
<p> A case insensitive list of EHLO keywords (pipelining, starttls,
-auth, etc.) that the SMTP server will not send in the EHLO response
+auth, etc.) that the Postfix SMTP server will not send in the EHLO
+response
to a remote SMTP client. </p>
<p> This feature is available in Postfix 2.2 and later. </p>
<DT><b><a name="smtpd_enforce_tls">smtpd_enforce_tls</a>
(default: no)</b></DT><DD>
-<p> Mandatory TLS: announce STARTTLS support to SMTP clients,
+<p> Mandatory TLS: announce STARTTLS support to remote SMTP clients,
and require that clients use TLS encryption. According to <a href="http://tools.ietf.org/html/rfc2487">RFC 2487</a>
this MUST NOT be applied in case of a publicly-referenced SMTP
server. This option is therefore off by default. </p>
<DT><b><a name="smtpd_reject_footer">smtpd_reject_footer</a>
(default: empty)</b></DT><DD>
-<p> Optional information that is appended after each SMTP server
+<p> Optional information that is appended after each Postfix SMTP
+server
4XX or 5XX response. </p>
<p> Example: </p>
<p> With Postfix 2.3 and later the Postfix SMTP server can disable
session id generation when TLS session caching is turned off. This
-keeps clients from caching sessions that almost certainly cannot
+keeps remote SMTP clients from caching sessions that almost certainly cannot
be re-used. </p>
<p> By default, the Postfix SMTP server always generates TLS session
<DT><b><a name="smtpd_tls_fingerprint_digest">smtpd_tls_fingerprint_digest</a>
(default: md5)</b></DT><DD>
-<p> The message digest algorithm used to construct client-certificate
-fingerprints for <b><a href="postconf.5.html#check_ccert_access">check_ccert_access</a></b> and
-<b><a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a></b>. The default algorithm is <b>md5</b>,
-for backwards compatibility with Postfix releases prior to 2.5.
-</p>
+<p> The message digest algorithm to construct remote SMTP
+client-certificate
+fingerprints or public key fingerprints (Postfix 2.9 and later)
+for <b><a href="postconf.5.html#check_ccert_access">check_ccert_access</a></b> and <b><a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a></b>. The
+default algorithm is <b>md5</b>, for backwards compatibility with Postfix
+releases prior to 2.5. </p>
<p> Advances in hash
function cryptanalysis have led to md5 being deprecated in favor of sha1.
</pre>
</blockquote>
+<p> Public key fingerprints are more difficult to extract, however,
+the SHA-1 public key fingerprint is often present as the value of the
+"Subject Key Identifier" extension in X.509v3 certificates. The Postfix
+SMTP server and client log the peer certificate fingerprint and public
+key fingerprint when TLS loglevel is 1 or higher. </p>
+
<p> Example: client-certificate access table, with sha1 fingerprints: </p>
<blockquote>
<dl compact>
-<dt> </dt> <dd> 0 Disable logging of TLS activity. </dd>
+<dt> </dt> <dd> 0 Log only a summary message on TLS handshake completion
+— no logging of remote SMTP client certificate trust-chain verification
+errors
+if client certificate verification is not required. With Postfix 2.8
+and earlier, disable logging of TLS activity. </dd>
-<dt> </dt> <dd> 1 Log TLS handshake and certificate information. </dd>
+<dt> </dt> <dd> 1 Also log trust-chain verification errors and peer
+certificate name and issuer. With Postfix 2.8 and earlier, log TLS
+handshake and certificate information. </dd>
-<dt> </dt> <dd> 2 Log levels during TLS negotiation. </dd>
+<dt> </dt> <dd> 2 Also log levels during TLS negotiation. </dd>
-<dt> </dt> <dd> 3 Log hexadecimal and ASCII dump of TLS negotiation
-process. </dd>
+<dt> </dt> <dd> 3 Also log hexadecimal and ASCII dump of TLS negotiation
+process. </dd>
<dt> </dt> <dd> 4 Also log hexadecimal and ASCII dump of complete
transmission after STARTTLS. </dd>
</dl>
-<p> Use "<a href="postconf.5.html#smtpd_tls_loglevel">smtpd_tls_loglevel</a> = 3" only in case of problems. Use of
-loglevel 4 is strongly discouraged. </p>
+<p> Do not use "<a href="postconf.5.html#smtpd_tls_loglevel">smtpd_tls_loglevel</a> = 2" or higher except in case
+of problems. Use of loglevel 4 is strongly discouraged. </p>
<p> This feature is available in Postfix 2.2 and later. </p>
<p> The underlying cipherlists for grades other than "null" include
anonymous ciphers, but these are automatically filtered out if the
-server is configured to ask for client certificates. You are very
+server is configured to ask for remote SMTP client certificates. You are very
unlikely to need to take any steps to exclude anonymous ciphers, they
are excluded automatically as required. If you must exclude anonymous
ciphers even when Postfix does not need or use peer certificates, set
(default: empty)</b></DT><DD>
<p> Additional list of ciphers or cipher types to exclude from the
-SMTP server cipher list at mandatory TLS security levels. This list
+Postfix SMTP server cipher list at mandatory TLS security levels.
+This list
works in addition to the exclusions listed with <a href="postconf.5.html#smtpd_tls_exclude_ciphers">smtpd_tls_exclude_ciphers</a>
(see there for syntax details). </p>
<p> Request that the Postfix SMTP server produces Received: message
headers that include information about the protocol and cipher used,
-as well as the client CommonName and client certificate issuer
+as well as the remote SMTP client CommonName and client certificate issuer
CommonName. This is disabled by default, as the information may
be modified in transit through other mail servers. Only information
that was recorded by the final destination can be trusted. </p>
<dt><b>none</b></dt> <dd> TLS will not be used. </dd>
<dt><b>may</b></dt> <dd> Opportunistic TLS: announce STARTTLS support
-to SMTP clients, but do not require that clients use TLS encryption.
+to remote SMTP clients, but do not require that clients use TLS encryption.
</dd>
<dt><b>encrypt</b></dt> <dd>Mandatory TLS encryption: announce
-STARTTLS support to SMTP clients, and require that clients use TLS
+STARTTLS support to remote SMTP clients, and require that clients use TLS
encryption. According to <a href="http://tools.ietf.org/html/rfc2487">RFC 2487</a> this MUST NOT be applied in case
of a publicly-referenced SMTP server. Instead, this option should
be used only on dedicated servers. </dd>
<p> Note 1: the "fingerprint", "verify" and "secure" levels are not
supported here.
The Postfix SMTP server logs a warning and uses "encrypt" instead.
-To verify SMTP client certificates, see <a href="TLS_README.html">TLS_README</a> for a discussion
+To verify
remote SMTP client certificates, see <a href="TLS_README.html">TLS_README</a> for a discussion
of the <a href="postconf.5.html#smtpd_tls_ask_ccert">smtpd_tls_ask_ccert</a>, <a href="postconf.5.html#smtpd_tls_req_ccert">smtpd_tls_req_ccert</a>, and <a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a>
features. </p>
<DT><b><a name="smtpd_use_tls">smtpd_use_tls</a>
(default: no)</b></DT><DD>
-<p> Opportunistic TLS: announce STARTTLS support to SMTP clients,
+<p> Opportunistic TLS: announce STARTTLS support to remote SMTP clients,
but do not require that clients use TLS encryption. </p>
<p> Note: when invoked via "<b>sendmail -bs</b>", Postfix will never offer
<DT><b><a name="tls_eecdh_strong_curve">tls_eecdh_strong_curve</a>
(default: prime256v1)</b></DT><DD>
-<p> The elliptic curve used by the SMTP server for sensibly strong
+<p> The elliptic curve used by the Postfix SMTP server for sensibly
+strong
ephemeral ECDH key exchange. This curve is used by the Postfix SMTP
server when "<a href="postconf.5.html#smtpd_tls_eecdh_grade">smtpd_tls_eecdh_grade</a> = strong". The phrase "sensibly
strong" means approximately 128-bit security based on best known
<DT><b><a name="tls_eecdh_ultra_curve">tls_eecdh_ultra_curve</a>
(default: secp384r1)</b></DT><DD>
-<p> The elliptic curve used by the SMTP server for maximally strong
+<p> The elliptic curve used by the Postfix SMTP server for maximally
+strong
ephemeral ECDH key exchange. This curve is used by the Postfix SMTP
server when "<a href="postconf.5.html#smtpd_tls_eecdh_grade">smtpd_tls_eecdh_grade</a> = ultra". The phrase "maximally
strong" means approximately 192-bit security based on best known attacks.
<DT><b><a name="tls_preempt_cipherlist">tls_preempt_cipherlist</a>
(default: no)</b></DT><DD>
-<p> With SSLv3 and later, use the server's cipher preference order
-instead of the client's cipher preference order. </p>
+<p> With SSLv3 and later, use the Postfix SMTP server's cipher
+preference order instead of the remote client's cipher preference
+order. </p>
<p> By default, the OpenSSL server selects the client's most preferred
cipher that the server supports. With SSLv3 and later, the server may
<DT><b><a name="tlsproxy_enforce_tls">tlsproxy_enforce_tls</a>
(default: $<a href="postconf.5.html#smtpd_enforce_tls">smtpd_enforce_tls</a>)</b></DT><DD>
-<p> Mandatory TLS: announce STARTTLS support to SMTP clients, and
+<p> Mandatory TLS: announce STARTTLS support to remote SMTP clients, and
require that clients use TLS encryption. See <a href="postconf.5.html#smtpd_enforce_tls">smtpd_enforce_tls</a> for
further details. </p>
<DT><b><a name="tlsproxy_tls_fingerprint_digest">tlsproxy_tls_fingerprint_digest</a>
(default: $<a href="postconf.5.html#smtpd_tls_fingerprint_digest">smtpd_tls_fingerprint_digest</a>)</b></DT><DD>
-<p> The message digest algorithm used to construct client-certificate
+<p> The message digest algorithm to construct remote SMTP
+client-certificate
fingerprints. See <a href="postconf.5.html#smtpd_tls_fingerprint_digest">smtpd_tls_fingerprint_digest</a> for further details.
</p>
<DT><b><a name="tlsproxy_use_tls">tlsproxy_use_tls</a>
(default: $<a href="postconf.5.html#smtpd_use_tls">smtpd_use_tls</a>)</b></DT><DD>
-<p> Opportunistic TLS: announce STARTTLS support to SMTP clients,
+<p> Opportunistic TLS: announce STARTTLS support to remote SMTP clients,
but do not require that clients use TLS encryption. See <a href="postconf.5.html#smtpd_use_tls">smtpd_use_tls</a>
for further details. </p>
(default: 550)</b></DT><DD>
<p>
-The SMTP server reply code when a recipient address matches
+The Postfix SMTP server reply code when a recipient address matches
$<a href="postconf.5.html#virtual_alias_domains">virtual_alias_domains</a>, and $<a href="postconf.5.html#virtual_alias_maps">virtual_alias_maps</a> specifies a list
of lookup tables that does not match the recipient address.
</p>
(default: 550)</b></DT><DD>
<p>
-The SMTP server reply code when a recipient address matches
+The Postfix SMTP server reply code when a recipient address matches
$<a href="postconf.5.html#virtual_mailbox_domains">virtual_mailbox_domains</a>, and $<a href="postconf.5.html#virtual_mailbox_maps">virtual_mailbox_maps</a> specifies a list
of lookup tables that does not match the recipient address.
</p>
<b><a href="postconf.5.html#postscreen_reject_footer">postscreen_reject_footer</a> ($<a href="postconf.5.html#smtpd_reject_footer">smtpd_reject_footer</a>)</b>
Optional information that is appended after a 4XX
- or 5XX server response.
+ or 5XX <a href="postscreen.8.html"><b>postscreen</b>(8)</a> server response.
<b><a href="postconf.5.html#soft_bounce">soft_bounce</a> (no)</b>
Safety net to keep mail queued that would otherwise
addresses.
<b><a href="postconf.5.html#postscreen_blacklist_action">postscreen_blacklist_action</a> (ignore)</b>
- The action that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> takes when an SMTP
- client is permanently blacklisted with the
+ The action that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> takes when a remote
+ SMTP client is permanently blacklisted with the
<a href="postconf.5.html#postscreen_access_list">postscreen_access_list</a> parameter.
<b>MAIL EXCHANGER POLICY TESTS</b>
<b><a href="postconf.5.html#postscreen_whitelist_interfaces">postscreen_whitelist_interfaces</a> (<a href="DATABASE_README.html#types">static</a>:all)</b>
A list of local <a href="postscreen.8.html"><b>postscreen</b>(8)</a> server IP addresses
- where a non-whitelisted SMTP client can obtain
- <a href="postscreen.8.html"><b>postscreen</b>(8)</a>'s temporary whitelist status to talk
- to a Postfix SMTP server process.
+ where a non-whitelisted remote SMTP client can
+ obtain <a href="postscreen.8.html"><b>postscreen</b>(8)</a>'s temporary whitelist status.
<b>BEFORE-GREETING TESTS</b>
These tests are executed before the remote SMTP client
ter.cf.
<b><a href="postconf.5.html#postscreen_dnsbl_action">postscreen_dnsbl_action</a> (ignore)</b>
- The action that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> takes when an SMTP
- client's combined DNSBL score is equal to or
+ The action that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> takes when a remote
+ SMTP client's combined DNSBL score is equal to or
greater than a threshold (as defined with the
<a href="postconf.5.html#postscreen_dnsbl_sites">postscreen_dnsbl_sites</a> and <a href="postconf.5.html#postscreen_dnsbl_threshold">postscreen_dnsbl_thresh</a>-
<a href="postconf.5.html#postscreen_dnsbl_threshold">old</a> parameters).
ters and weight factors.
<b><a href="postconf.5.html#postscreen_dnsbl_threshold">postscreen_dnsbl_threshold</a> (1)</b>
- The inclusive lower bound for blocking an SMTP
- client, based on its combined DNSBL score as
+ The inclusive lower bound for blocking a remote
+ SMTP client, based on its combined DNSBL score as
defined with the <a href="postconf.5.html#postscreen_dnsbl_sites">postscreen_dnsbl_sites</a> parameter.
<b><a href="postconf.5.html#postscreen_greet_action">postscreen_greet_action</a> (ignore)</b>
- The action that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> takes when an SMTP
- client speaks before its turn within the time spec-
- ified with the <a href="postconf.5.html#postscreen_greet_wait">postscreen_greet_wait</a> parameter.
+ The action that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> takes when a remote
+ SMTP client speaks before its turn within the time
+
specified with the <a href="postconf.5.html#postscreen_greet_wait">postscreen_greet_wait</a> parameter.
<b><a href="postconf.5.html#postscreen_greet_banner">postscreen_greet_banner</a> ($<a href="postconf.5.html#smtpd_banner">smtpd_banner</a>)</b>
The <i>text</i> in the optional "220-<i>text</i>..." server
response that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> sends ahead of the real
Postfix SMTP server's "220 text..." response, in an
- attempt to confuse bad SMTP clients so that they
+ attempt to confuse bad SMTP clients so that they
speak before their turn (pre-greet).
<b><a href="postconf.5.html#postscreen_greet_wait">postscreen_greet_wait</a> (${stress?2}${stress:6}s)</b>
The amount of time that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> will wait for
- an SMTP client to send a command before its turn,
- and for DNS blocklist lookup results to arrive
- (default: up to 2 seconds under stress, up to 6
+ an SMTP client to send a command before its turn,
+ and for DNS blocklist lookup results to arrive
+ (default: up to 2 seconds under stress, up to 6
seconds otherwise).
<b><a href="postconf.5.html#smtpd_service_name">smtpd_service_name</a> (smtpd)</b>
- The internal service that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> hands off
+ The internal service that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> hands off
allowed connections to.
<b>AFTER-GREETING TESTS</b>
- These tests are executed after the remote SMTP client
+ These tests are executed after the remote SMTP client
receives the "220 servername" greeting. If a client passes
- all tests during this phase, it will receive a 4XX
- response to RCPT TO commands until the client hangs up.
+ all tests during this phase, it will receive a 4XX
+ response to RCPT TO commands until the client hangs up.
After this, the client will be allowed to talk directly to
a Postfix SMTP server process.
<b><a href="postconf.5.html#postscreen_bare_newline_action">postscreen_bare_newline_action</a> (ignore)</b>
- The action that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> takes when an SMTP
- client sends a bare newline character, that is, a
- newline not preceded by carriage return.
+ The action that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> takes when a remote
+ SMTP client sends a bare newline character, that
+ is, a newline not preceded by carriage return.
<b><a href="postconf.5.html#postscreen_bare_newline_enable">postscreen_bare_newline_enable</a> (no)</b>
- Enable "bare newline" SMTP protocol tests in the
+ Enable "bare newline" SMTP protocol tests in the
<a href="postscreen.8.html"><b>postscreen</b>(8)</a> server.
<b><a href="postconf.5.html#postscreen_disable_vrfy_command">postscreen_disable_vrfy_command</a> ($<a href="postconf.5.html#disable_vrfy_command">disable_vrfy_command</a>)</b>
- Disable
the SMTP VRFY command in the <a href="postscreen.8.html"><b>postscreen</b>(8)</a>
+ Disable
the SMTP VRFY command in the <a href="postscreen.8.html"><b>postscreen</b>(8)</a>
daemon.
<b><a href="postconf.5.html#postscreen_forbidden_commands">postscreen_forbidden_commands</a> ($<a href="postconf.5.html#smtpd_forbidden_commands">smtpd_forbidden_commands</a>)</b>
siders in violation of the SMTP protocol.
<b><a href="postconf.5.html#postscreen_helo_required">postscreen_helo_required</a> ($<a href="postconf.5.html#smtpd_helo_required">smtpd_helo_required</a>)</b>
- Require that a remote SMTP client sends HELO or
+ Require that a remote SMTP client sends HELO or
EHLO before commencing a MAIL transaction.
<b><a href="postconf.5.html#postscreen_non_smtp_command_action">postscreen_non_smtp_command_action</a> (drop)</b>
- The action that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> takes when an SMTP
- client sends non-SMTP commands as specified with
- the <a href="postconf.5.html#postscreen_forbidden_commands">postscreen_forbidden_commands</a> parameter.
+ The action that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> takes when a remote
+ SMTP client sends non-SMTP commands as specified
+
with the <a href="postconf.5.html#postscreen_forbidden_commands">postscreen_forbidden_commands</a> parameter.
<b><a href="postconf.5.html#postscreen_non_smtp_command_enable">postscreen_non_smtp_command_enable</a> (no)</b>
- Enable "non-SMTP command" tests in the
+ Enable "non-SMTP command" tests in the
<a href="postscreen.8.html"><b>postscreen</b>(8)</a> server.
<b><a href="postconf.5.html#postscreen_pipelining_action">postscreen_pipelining_action</a> (enforce)</b>
- The action that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> takes when an SMTP
- client sends multiple commands instead of sending
- one command and waiting for the server to respond.
+ The action that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> takes when a remote
+ SMTP client sends multiple commands instead of
+ sending one command and waiting for the server to
+ respond.
<b><a href="postconf.5.html#postscreen_pipelining_enable">postscreen_pipelining_enable</a> (no)</b>
- Enable "pipelining" SMTP protocol tests in the
+ Enable "pipelining" SMTP protocol tests in the
<a href="postscreen.8.html"><b>postscreen</b>(8)</a> server.
<b>CACHE CONTROLS</b>
<b><a href="postconf.5.html#postscreen_cache_cleanup_interval">postscreen_cache_cleanup_interval</a> (12h)</b>
- The amount of time between <a href="postscreen.8.html"><b>postscreen</b>(8)</a> cache
+ The amount of time between <a href="postscreen.8.html"><b>postscreen</b>(8)</a> cache
cleanup runs.
<b><a href="postconf.5.html#postscreen_cache_map">postscreen_cache_map</a> (btree:$data_direc-</b>
<b>tory/postscreen_cache)</b>
- Persistent storage for the <a href="postscreen.8.html"><b>postscreen</b>(8)</a> server
+ Persistent storage for the <a href="postscreen.8.html"><b>postscreen</b>(8)</a> server
decisions.
<b><a href="postconf.5.html#postscreen_cache_retention_time">postscreen_cache_retention_time</a> (7d)</b>
The amount of time that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> will cache an
- expired temporary whitelist entry before it is
+ expired temporary whitelist entry before it is
removed.
<b><a href="postconf.5.html#postscreen_bare_newline_ttl">postscreen_bare_newline_ttl</a> (30d)</b>
- The amount of time that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> will use the
+ The amount of time that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> will use the
result from a successful "bare newline" SMTP proto-
col test.
<b><a href="postconf.5.html#postscreen_dnsbl_ttl">postscreen_dnsbl_ttl</a> (1h)</b>
- The amount of time that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> will use the
+ The amount of time that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> will use the
result from a successful DNS blocklist test.
<b><a href="postconf.5.html#postscreen_greet_ttl">postscreen_greet_ttl</a> (1d)</b>
- The amount of time that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> will use the
+ The amount of time that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> will use the
result from a successful PREGREET test.
<b><a href="postconf.5.html#postscreen_non_smtp_command_ttl">postscreen_non_smtp_command_ttl</a> (30d)</b>
- The amount of time that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> will use the
- result from a successful "non_smtp_command" SMTP
+ The amount of time that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> will use the
+ result from a successful "non_smtp_command" SMTP
protocol test.
<b><a href="postconf.5.html#postscreen_pipelining_ttl">postscreen_pipelining_ttl</a> (30d)</b>
- The amount of time that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> will use the
+ The amount of time that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> will use the
result from a successful "pipelining" SMTP protocol
test.
<b>RESOURCE CONTROLS</b>
<b><a href="postconf.5.html#line_length_limit">line_length_limit</a> (2048)</b>
- Upon input, long lines are chopped up into pieces
- of at most this length; upon delivery, long lines
+ Upon input, long lines are chopped up into pieces
+ of at most this length; upon delivery, long lines
are reconstructed.
<b><a href="postconf.5.html#postscreen_client_connection_count_limit">postscreen_client_connection_count_limit</a></b>
<b>($<a href="postconf.5.html#smtpd_client_connection_count_limit">smtpd_client_connection_count_limit</a>)</b>
- How many simultaneous connections any client is
- allowed to have with the <a href="postscreen.8.html"><b>postscreen</b>(8)</a> daemon.
+ How many simultaneous connections any remote SMTP
+ client is allowed to have with the <a href="postscreen.8.html"><b>postscreen</b>(8)</a>
+ daemon.
<b><a href="postconf.5.html#postscreen_command_count_limit">postscreen_command_count_limit</a> (20)</b>
The limit on the total number of commands per SMTP
<b><a href="postconf.5.html#postscreen_post_queue_limit">postscreen_post_queue_limit</a> ($<a href="postconf.5.html#default_process_limit">default_process_limit</a>)</b>
The number of clients that can be waiting for ser-
- vice from a real SMTP server process.
+ vice from a real Postfix SMTP server process.
<b><a href="postconf.5.html#postscreen_pre_queue_limit">postscreen_pre_queue_limit</a> ($<a href="postconf.5.html#default_process_limit">default_process_limit</a>)</b>
The number of non-whitelisted clients that can be
waiting for a decision whether they will receive
- service from a real SMTP server process.
+ service from a real Postfix SMTP server process.
<b><a href="postconf.5.html#postscreen_watchdog_timeout">postscreen_watchdog_timeout</a> (10s)</b>
How much time a <a href="postscreen.8.html"><b>postscreen</b>(8)</a> process may take to
- respond to an SMTP client command or to perform a
- cache operation before it is terminated by a built-
- in watchdog timer.
+ respond to a remote SMTP client command or to per-
+ form a cache operation before it is terminated by a
+ built-in watchdog timer.
<b>STARTTLS CONTROLS</b>
<b><a href="postconf.5.html#postscreen_tls_security_level">postscreen_tls_security_level</a> ($<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a>)</b>
<b><a href="postconf.5.html#postscreen_use_tls">postscreen_use_tls</a> ($<a href="postconf.5.html#smtpd_use_tls">smtpd_use_tls</a>)</b>
Opportunistic TLS: announce STARTTLS support to
- SMTP clients, but do not require that clients use
- TLS encryption.
+ remote SMTP clients, but do not require that
+ clients use TLS encryption.
<b><a href="postconf.5.html#postscreen_enforce_tls">postscreen_enforce_tls</a> ($<a href="postconf.5.html#smtpd_enforce_tls">smtpd_enforce_tls</a>)</b>
- Mandatory TLS: announce STARTTLS support to SMTP
- clients, and require that clients use TLS encryp-
- tion.
+ Mandatory TLS: announce STARTTLS support to remote
+ SMTP clients, and require that clients use TLS
+ encryption.
<b>MISCELLANEOUS CONTROLS</b>
<b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
PIX firewall bugs.
<b><a href="postconf.5.html#smtp_quote_rfc821_envelope">smtp_quote_rfc821_envelope</a> (yes)</b>
- Quote addresses in SMTP MAIL FROM and RCPT TO com-
- mands as required by <a href="http://tools.ietf.org/html/rfc2821">RFC 2821</a>.
+ Quote addresses in Postfix SMTP client MAIL FROM
+
and RCPT TO commands as required by <a href="http://tools.ietf.org/html/rfc2821">RFC 2821</a>.
<b><a href="postconf.5.html#smtp_reply_filter">smtp_reply_filter</a> (empty)</b>
A mechanism to transform replies from remote SMTP
servers one line at a time.
<b><a href="postconf.5.html#smtp_skip_5xx_greeting">smtp_skip_5xx_greeting</a> (yes)</b>
- Skip SMTP servers that greet with a 5XX status code
- (go away, do not try again later).
+ Skip remote SMTP servers that greet with a 5XX sta-
+ tus code (go away, do not try again later).
<b><a href="postconf.5.html#smtp_skip_quit_response">smtp_skip_quit_response</a> (yes)</b>
Do not wait for the response to the SMTP QUIT com-
<b><a href="postconf.5.html#smtp_generic_maps">smtp_generic_maps</a> (empty)</b>
Optional lookup tables that perform address rewrit-
- ing in the SMTP client, typically to transform a
- locally valid address into a globally valid address
- when sending mail across the Internet.
+ ing in the Postfix SMTP client, typically to trans-
+ form a locally valid address into a globally valid
+ address when sending mail across the Internet.
Available in Postfix version 2.2.9 and later:
Lookup tables, indexed by the remote LMTP server
address, with case insensitive lists of LHLO key-
words (pipelining, starttls, auth, etc.) that the
- LMTP client will ignore in the LHLO response from a
- remote LMTP server.
+ Postfix LMTP client will ignore in the LHLO
+ response from a remote LMTP server.
<b><a href="postconf.5.html#lmtp_discard_lhlo_keywords">lmtp_discard_lhlo_keywords</a> (empty)</b>
A case insensitive list of LHLO keywords (pipelin-
- ing, starttls, auth, etc.) that the LMTP client
- will ignore in the LHLO response from a remote LMTP
- server.
+ ing, starttls, auth, etc.) that the Postfix LMTP
+ client will ignore in the LHLO response from a
+ remote LMTP server.
Available in Postfix version 2.4.4 and later:
client.
<b><a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a> (empty)</b>
- Optional SMTP client lookup tables with one user-
- name:password entry per remote hostname or domain,
- or sender address when sender-dependent authentica-
- tion is enabled.
+ Optional Postfix SMTP client lookup tables with one
+ username:password entry per remote hostname or
+ domain, or sender address when sender-dependent
+ authentication is enabled.
<b><a href="postconf.5.html#smtp_sasl_security_options">smtp_sasl_security_options</a> (noplaintext, noanonymous)</b>
Postfix SMTP client SASL security options; as of
<b><a href="postconf.5.html#smtp_tls_mandatory_exclude_ciphers">smtp_tls_mandatory_exclude_ciphers</a> (empty)</b>
Additional list of ciphers or cipher types to
- exclude from the SMTP client cipher list at manda-
- tory TLS security levels.
+ exclude from the Postfix SMTP client cipher list at
+ mandatory TLS security levels.
<b><a href="postconf.5.html#smtp_tls_dcert_file">smtp_tls_dcert_file</a> (empty)</b>
File with the Postfix SMTP client DSA certificate
tificates.
<b><a href="postconf.5.html#smtp_tls_secure_cert_match">smtp_tls_secure_cert_match</a> (nexthop, dot-nexthop)</b>
- The server certificate peername verification method
- for the "secure" TLS security level.
+ How the Postfix SMTP client verifies the server
+ certificate peername for the "secure" TLS security
+ level.
<b><a href="postconf.5.html#smtp_tls_session_cache_database">smtp_tls_session_cache_database</a> (empty)</b>
- Name of the file containing the optional Postfix
+ Name of the file containing the optional Postfix
SMTP client TLS session cache.
<b><a href="postconf.5.html#smtp_tls_session_cache_timeout">smtp_tls_session_cache_timeout</a> (3600s)</b>
sion cache information.
<b><a href="postconf.5.html#smtp_tls_verify_cert_match">smtp_tls_verify_cert_match</a> (hostname)</b>
- The server certificate peername verification method
- for the "verify" TLS security level.
+ How the Postfix SMTP client verifies the server
+ certificate peername for the "verify" TLS security
+ level.
<b><a href="postconf.5.html#tls_daemon_random_bytes">tls_daemon_random_bytes</a> (32)</b>
The number of pseudo-random bytes that an <a href="smtp.8.html"><b>smtp</b>(8)</a>
the smtp message delivery transport.
<b><a href="postconf.5.html#smtp_connect_timeout">smtp_connect_timeout</a> (30s)</b>
- The SMTP client time limit for completing a TCP
- connection, or zero (use the operating system
+ The Postfix SMTP client time limit for completing a
+ TCP connection, or zero (use the operating system
built-in time limit).
<b><a href="postconf.5.html#smtp_helo_timeout">smtp_helo_timeout</a> (300s)</b>
- The SMTP client time limit for sending the HELO or
- EHLO command, and for receiving the initial server
- response.
+ The Postfix SMTP client time limit for sending the
+ HELO or EHLO command, and for receiving the initial
+ remote SMTP server response.
<b><a href="postconf.5.html#lmtp_lhlo_timeout">lmtp_lhlo_timeout</a> (300s)</b>
- The LMTP client time limit for sending the LHLO
- command, and for receiving the initial server
- response.
+ The Postfix LMTP client time limit for sending the
+ LHLO command, and for receiving the initial remote
+ LMTP server response.
<b><a href="postconf.5.html#smtp_xforward_timeout">smtp_xforward_timeout</a> (300s)</b>
- The SMTP client time limit for sending the XFORWARD
- command, and for receiving the server response.
+ The Postfix SMTP client time limit for sending the
+ XFORWARD command, and for receiving the remote SMTP
+ server response.
<b><a href="postconf.5.html#smtp_mail_timeout">smtp_mail_timeout</a> (300s)</b>
- The SMTP client time limit for sending the MAIL
- FROM command, and for receiving the server
- response.
+ The Postfix SMTP client time limit for sending the
+ MAIL FROM command, and for receiving the remote
+ SMTP server response.
<b><a href="postconf.5.html#smtp_rcpt_timeout">smtp_rcpt_timeout</a> (300s)</b>
- The SMTP client time limit for sending the SMTP
- RCPT TO command, and for receiving the server
- response.
+ The Postfix SMTP client time limit for sending the
+ SMTP RCPT TO command, and for receiving the remote
+ SMTP server response.
<b><a href="postconf.5.html#smtp_data_init_timeout">smtp_data_init_timeout</a> (120s)</b>
- The SMTP client time limit for sending the SMTP
- DATA command, and for receiving the server
- response.
+ The Postfix SMTP client time limit for sending the
+ SMTP DATA command, and for receiving the remote
+ SMTP server response.
<b><a href="postconf.5.html#smtp_data_xfer_timeout">smtp_data_xfer_timeout</a> (180s)</b>
- The SMTP client time limit for sending the SMTP
- message content.
+ The Postfix SMTP client time limit for sending the
+ SMTP message content.
<b><a href="postconf.5.html#smtp_data_done_timeout">smtp_data_done_timeout</a> (600s)</b>
- The SMTP client time limit for sending the SMTP
- ".", and for receiving the server response.
+ The Postfix SMTP client time limit for sending the
+ SMTP ".", and for receiving the remote SMTP server
+ response.
<b><a href="postconf.5.html#smtp_quit_timeout">smtp_quit_timeout</a> (300s)</b>
- The SMTP client time limit for sending the QUIT
- command, and for receiving the server response.
+ The Postfix SMTP client time limit for sending the
+ QUIT command, and for receiving the remote SMTP
+ server response.
Available in Postfix version 2.1 and later:
<b><a href="postconf.5.html#smtp_mx_address_limit">smtp_mx_address_limit</a> (5)</b>
The maximal number of MX (mail exchanger) IP
- addresses that can result from mail exchanger
- lookups, or zero (no limit).
+ addresses that can result from Postfix SMTP client
+ mail exchanger lookups, or zero (no limit).
<b><a href="postconf.5.html#smtp_mx_session_limit">smtp_mx_session_limit</a> (2)</b>
- The maximal number of SMTP sessions per delivery
- request before giving up or delivering to a fall-
- back <a href="postconf.5.html#relayhost">relay host</a>, or zero (no limit).
+ The maximal number of SMTP sessions per delivery
+ request before the Postfix SMTP client gives up or
+ delivers to a fall-back <a href="postconf.5.html#relayhost">relay host</a>, or zero (no
+ limit).
<b><a href="postconf.5.html#smtp_rset_timeout">smtp_rset_timeout</a> (20s)</b>
- The SMTP client time limit for sending the RSET
- command, and for receiving the server response.
+ The Postfix SMTP client time limit for sending the
+ RSET command, and for receiving the remote SMTP
+ server response.
Available in Postfix version 2.2 and earlier:
Available in Postfix version 2.2 and later:
<b><a href="postconf.5.html#smtp_connection_cache_destinations">smtp_connection_cache_destinations</a> (empty)</b>
- Permanently enable SMTP connection caching for the
+ Permanently enable SMTP connection caching for the
specified destinations.
<b><a href="postconf.5.html#smtp_connection_cache_on_demand">smtp_connection_cache_on_demand</a> (yes)</b>
- Temporarily enable SMTP connection caching while a
+ Temporarily enable SMTP connection caching while a
destination has a high volume of mail in the active
queue.
<b><a href="postconf.5.html#smtp_connection_cache_time_limit">smtp_connection_cache_time_limit</a> (2s)</b>
When SMTP connection caching is enabled, the amount
- of time that an unused SMTP client socket is kept
+ of time that an unused SMTP client socket is kept
open before it is closed.
Available in Postfix version 2.3 and later:
<b><a href="postconf.5.html#connection_cache_protocol_timeout">connection_cache_protocol_timeout</a> (5s)</b>
- Time limit for connection cache connect, send or
+ Time limit for connection cache connect, send or
receive operations.
Available in Postfix version 2.9 and later:
<b><a href="postconf.5.html#smtp_per_record_deadline">smtp_per_record_deadline</a> (no)</b>
Change the behavior of the smtp_*_timeout time lim-
- its, from a time limit per read or write system
+ its, from a time limit per read or write system
call, to a time limit to send or receive a complete
- record (an SMTP command line, SMTP response line,
- SMTP message content line, or TLS protocol mes-
+ record (an SMTP command line, SMTP response line,
+ SMTP message content line, or TLS protocol mes-
sage).
<b>TROUBLE SHOOTING CONTROLS</b>
<b><a href="postconf.5.html#debug_peer_level">debug_peer_level</a> (2)</b>
- The increment in verbose logging level when a
- remote client or server matches a pattern in the
+ The increment in verbose logging level when a
+ remote client or server matches a pattern in the
<a href="postconf.5.html#debug_peer_list">debug_peer_list</a> parameter.
<b><a href="postconf.5.html#debug_peer_list">debug_peer_list</a> (empty)</b>
- Optional list of remote client or server hostname
- or network address patterns that cause the verbose
- logging level to increase by the amount specified
+ Optional list of remote client or server hostname
+ or network address patterns that cause the verbose
+ logging level to increase by the amount specified
in $<a href="postconf.5.html#debug_peer_level">debug_peer_level</a>.
<b><a href="postconf.5.html#error_notice_recipient">error_notice_recipient</a> (postmaster)</b>
- The recipient of postmaster notifications about
- mail delivery problems that are caused by policy,
+ The recipient of postmaster notifications about
+ mail delivery problems that are caused by policy,
resource, software or protocol errors.
<b><a href="postconf.5.html#internal_mail_filter_classes">internal_mail_filter_classes</a> (empty)</b>
- What categories of Postfix-generated mail are sub-
- ject to before-queue content inspection by
+ What categories of Postfix-generated mail are sub-
+ ject to before-queue content inspection by
<a href="postconf.5.html#non_smtpd_milters">non_smtpd_milters</a>, <a href="postconf.5.html#header_checks">header_checks</a> and <a href="postconf.5.html#body_checks">body_checks</a>.
<b><a href="postconf.5.html#notify_classes">notify_classes</a> (resource, software)</b>
- The list of error classes that are reported to the
+ The list of error classes that are reported to the
postmaster.
<b>MISCELLANEOUS CONTROLS</b>
<b><a href="postconf.5.html#best_mx_transport">best_mx_transport</a> (empty)</b>
- Where the Postfix SMTP client should deliver mail
+ Where the Postfix SMTP client should deliver mail
when it detects a "mail loops back to myself" error
condition.
<b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
- The default location of the Postfix <a href="postconf.5.html">main.cf</a> and
+ The default location of the Postfix <a href="postconf.5.html">main.cf</a> and
<a href="master.5.html">master.cf</a> configuration files.
<b><a href="postconf.5.html#daemon_timeout">daemon_timeout</a> (18000s)</b>
- How much time a Postfix daemon process may take to
- handle a request before it is terminated by a
+ How much time a Postfix daemon process may take to
+ handle a request before it is terminated by a
built-in watchdog timer.
<b><a href="postconf.5.html#delay_logging_resolution_limit">delay_logging_resolution_limit</a> (2)</b>
- The maximal number of digits after the decimal
+ The maximal number of digits after the decimal
point when logging sub-second delay values.
<b><a href="postconf.5.html#disable_dns_lookups">disable_dns_lookups</a> (no)</b>
- Disable DNS lookups in the Postfix SMTP and LMTP
+ Disable DNS lookups in the Postfix SMTP and LMTP
clients.
<b><a href="postconf.5.html#inet_interfaces">inet_interfaces</a> (all)</b>
tem receives mail on.
<b><a href="postconf.5.html#inet_protocols">inet_protocols</a> (all)</b>
- The Internet protocols Postfix will attempt to use
+ The Internet protocols Postfix will attempt to use
when making or accepting connections.
<b><a href="postconf.5.html#ipc_timeout">ipc_timeout</a> (3600s)</b>
over an internal communication channel.
<b><a href="postconf.5.html#lmtp_assume_final">lmtp_assume_final</a> (no)</b>
- When an LMTP server announces no DSN support,
+ When a remote LMTP server announces no DSN support,
assume that the server performs final delivery, and
- send "delivered" delivery status notifications
+ send "delivered" delivery status notifications
instead of "relayed".
<b><a href="postconf.5.html#lmtp_tcp_port">lmtp_tcp_port</a> (24)</b>
- The default TCP port that the Postfix LMTP client
+ The default TCP port that the Postfix LMTP client
connects to.
<b><a href="postconf.5.html#max_idle">max_idle</a> (100s)</b>
- The maximum amount of time that an idle Postfix
- daemon process waits for an incoming connection
+ The maximum amount of time that an idle Postfix
+ daemon process waits for an incoming connection
before terminating voluntarily.
<b><a href="postconf.5.html#max_use">max_use</a> (100)</b>
- The maximal number of incoming connections that a
- Postfix daemon process will service before termi-
+ The maximal number of incoming connections that a
+ Postfix daemon process will service before termi-
nating voluntarily.
<b><a href="postconf.5.html#process_id">process_id</a> (read-only)</b>
- The process ID of a Postfix command or daemon
+ The process ID of a Postfix command or daemon
process.
<b><a href="postconf.5.html#process_name">process_name</a> (read-only)</b>
- The process name of a Postfix command or daemon
+ The process name of a Postfix command or daemon
process.
<b><a href="postconf.5.html#proxy_interfaces">proxy_interfaces</a> (empty)</b>
The network interface addresses that this mail sys-
- tem receives mail on by way of a proxy or network
+ tem receives mail on by way of a proxy or network
address translation unit.
<b><a href="postconf.5.html#smtp_address_preference">smtp_address_preference</a> (any)</b>
The address type ("ipv6", "ipv4" or "any") that the
Postfix SMTP client will try first, when a destina-
- tion has IPv6 and IPv4 addresses with equal MX
+ tion has IPv6 and IPv4 addresses with equal MX
preference.
<b><a href="postconf.5.html#smtp_bind_address">smtp_bind_address</a> (empty)</b>
- An optional numerical network address that the
- Postfix SMTP client should bind to when making an
+ An optional numerical network address that the
+ Postfix SMTP client should bind to when making an
IPv4 connection.
<b><a href="postconf.5.html#smtp_bind_address6">smtp_bind_address6</a> (empty)</b>
- An optional numerical network address that the
- Postfix SMTP client should bind to when making an
+ An optional numerical network address that the
+ Postfix SMTP client should bind to when making an
IPv6 connection.
<b><a href="postconf.5.html#smtp_helo_name">smtp_helo_name</a> ($<a href="postconf.5.html#myhostname">myhostname</a>)</b>
- The hostname to send in the SMTP EHLO or HELO com-
+ The hostname to send in the SMTP EHLO or HELO com-
mand.
<b><a href="postconf.5.html#lmtp_lhlo_name">lmtp_lhlo_name</a> ($<a href="postconf.5.html#myhostname">myhostname</a>)</b>
The hostname to send in the LMTP LHLO command.
<b><a href="postconf.5.html#smtp_host_lookup">smtp_host_lookup</a> (dns)</b>
- What mechanisms the Postfix SMTP client uses to
+ What mechanisms the Postfix SMTP client uses to
look up a host's IP address.
<b><a href="postconf.5.html#smtp_randomize_addresses">smtp_randomize_addresses</a> (yes)</b>
- Randomize the order of equal-preference MX host
+ Randomize the order of equal-preference MX host
addresses.
<b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b>
The syslog facility of Postfix logging.
<b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b>
- The mail system name that is prepended to the
- process name in syslog records, so that "smtpd"
+ The mail system name that is prepended to the
+ process name in syslog records, so that "smtpd"
becomes, for example, "postfix/smtpd".
Available with Postfix 2.2 and earlier:
<b><a href="postconf.5.html#fallback_relay">fallback_relay</a> (empty)</b>
- Optional list of relay hosts for SMTP destinations
+ Optional list of relay hosts for SMTP destinations
that can't be found or that are unreachable.
Available with Postfix 2.3 and later:
<b><a href="postconf.5.html#smtp_fallback_relay">smtp_fallback_relay</a> ($<a href="postconf.5.html#fallback_relay">fallback_relay</a>)</b>
- Optional list of relay hosts for SMTP destinations
+ Optional list of relay hosts for SMTP destinations
that can't be found or that are unreachable.
<b>SEE ALSO</b>
<a href="TLS_README.html">TLS_README</a>, Postfix STARTTLS howto
<b>LICENSE</b>
- The Secure Mailer license must be distributed with this
+ The Secure Mailer license must be distributed with this
software.
<b>AUTHOR(S)</b>
in order to prevent undesirable use.
<b><a href="postconf.5.html#broken_sasl_auth_clients">broken_sasl_auth_clients</a> (no)</b>
- Enable inter-operability with SMTP clients that
- implement an obsolete version of the AUTH command
- (<a href="http://tools.ietf.org/html/rfc4954">RFC 4954</a>).
+ Enable inter-operability with remote SMTP clients
+ that implement an obsolete version of the AUTH com-
+
mand (<a href="http://tools.ietf.org/html/rfc4954">RFC 4954</a>).
<b><a href="postconf.5.html#disable_vrfy_command">disable_vrfy_command</a> (no)</b>
Disable the SMTP VRFY command.
Lookup tables, indexed by the remote SMTP client
address, with case insensitive lists of EHLO key-
words (pipelining, starttls, auth, etc.) that the
- SMTP server will not send in the EHLO response to a
- remote SMTP client.
+ Postfix SMTP server will not send in the EHLO
+ response to a remote SMTP client.
<b><a href="postconf.5.html#smtpd_discard_ehlo_keywords">smtpd_discard_ehlo_keywords</a> (empty)</b>
A case insensitive list of EHLO keywords (pipelin-
- ing, starttls, auth, etc.) that the SMTP server
- will not send in the EHLO response to a remote SMTP
- client.
+ ing, starttls, auth, etc.) that the Postfix SMTP
+ server will not send in the EHLO response to a
+ remote SMTP client.
<b><a href="postconf.5.html#smtpd_delay_open_until_valid_rcpt">smtpd_delay_open_until_valid_rcpt</a> (yes)</b>
Postpone the start of an SMTP mail transaction
Available in Postfix version 2.1 and later:
<b><a href="postconf.5.html#smtpd_authorized_xforward_hosts">smtpd_authorized_xforward_hosts</a> (empty)</b>
- What SMTP clients are allowed to use the XFORWARD
- feature.
+ What remote SMTP clients are allowed to use the
+ XFORWARD feature.
<b>SASL AUTHENTICATION CONTROLS</b>
Postfix SASL support (<a href="http://tools.ietf.org/html/rfc4954">RFC 4954</a>) can be used to authenti-
server. See the <a href="SASL_README.html">SASL_README</a> document for details.
<b><a href="postconf.5.html#broken_sasl_auth_clients">broken_sasl_auth_clients</a> (no)</b>
- Enable inter-operability with SMTP clients that
- implement an obsolete version of the AUTH command
- (<a href="http://tools.ietf.org/html/rfc4954">RFC 4954</a>).
+ Enable inter-operability with remote SMTP clients
+ that implement an obsolete version of the AUTH com-
+
mand (<a href="http://tools.ietf.org/html/rfc4954">RFC 4954</a>).
<b><a href="postconf.5.html#smtpd_sasl_auth_enable">smtpd_sasl_auth_enable</a> (no)</b>
Enable SASL authentication in the Postfix SMTP
<b><a href="postconf.5.html#smtpd_tls_mandatory_exclude_ciphers">smtpd_tls_mandatory_exclude_ciphers</a> (empty)</b>
Additional list of ciphers or cipher types to
- exclude from the SMTP server cipher list at manda-
- tory TLS security levels.
+ exclude from the Postfix SMTP server cipher list at
+ mandatory TLS security levels.
<b><a href="postconf.5.html#smtpd_tls_mandatory_protocols">smtpd_tls_mandatory_protocols</a> (SSLv3, TLSv1)</b>
The SSL/TLS protocols accepted by the Postfix SMTP
Request that the Postfix SMTP server produces
Received: message headers that include information
about the protocol and cipher used, as well as the
- client CommonName and client certificate issuer
- CommonName.
+ remote SMTP client CommonName and client certifi-
+ cate issuer CommonName.
<b><a href="postconf.5.html#smtpd_tls_req_ccert">smtpd_tls_req_ccert</a> (no)</b>
With mandatory TLS encryption, require a trusted
Available in Postfix version 2.5 and later:
<b><a href="postconf.5.html#smtpd_tls_fingerprint_digest">smtpd_tls_fingerprint_digest</a> (md5)</b>
- The message digest algorithm used to construct
- client-certificate fingerprints for
+ The message digest algorithm to construct remote
+ SMTP client-certificate fingerprints or public key
+ fingerprints (Postfix 2.9 and later) for
<b><a href="postconf.5.html#check_ccert_access">check_ccert_access</a></b> and <b><a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a></b>.
Available in Postfix version 2.6 and later:
<b><a href="postconf.5.html#smtpd_tls_protocols">smtpd_tls_protocols</a> (empty)</b>
- List of TLS protocols that the Postfix SMTP server
- will exclude or include with opportunistic TLS
+ List of TLS protocols that the Postfix SMTP server
+ will exclude or include with opportunistic TLS
encryption.
<b><a href="postconf.5.html#smtpd_tls_ciphers">smtpd_tls_ciphers</a> (export)</b>
- The minimum TLS cipher grade that the Postfix SMTP
- server will use with opportunistic TLS encryption.
+ The minimum TLS cipher grade that the Postfix SMTP
+ server will use with opportunistic TLS encryption.
<b><a href="postconf.5.html#smtpd_tls_eccert_file">smtpd_tls_eccert_file</a> (empty)</b>
File with the Postfix SMTP server ECDSA certificate
in PEM format.
<b><a href="postconf.5.html#smtpd_tls_eecdh_grade">smtpd_tls_eecdh_grade</a> (see 'postconf -d' output)</b>
- The Postfix SMTP server security grade for
+ The Postfix SMTP server security grade for
ephemeral elliptic-curve Diffie-Hellman (EECDH) key
exchange.
<b><a href="postconf.5.html#tls_eecdh_strong_curve">tls_eecdh_strong_curve</a> (prime256v1)</b>
- The elliptic curve used by the SMTP server for sen-
- sibly strong ephemeral ECDH key exchange.
+ The elliptic curve used by the Postfix SMTP server
+ for sensibly strong ephemeral ECDH key exchange.
<b><a href="postconf.5.html#tls_eecdh_ultra_curve">tls_eecdh_ultra_curve</a> (secp384r1)</b>
- The elliptic curve used by the SMTP server for max-
- imally strong ephemeral ECDH key exchange.
+ The elliptic curve used by the Postfix SMTP server
+ for maximally strong ephemeral ECDH key exchange.
Available in Postfix version 2.8 and later:
<b><a href="postconf.5.html#tls_preempt_cipherlist">tls_preempt_cipherlist</a> (no)</b>
- With SSLv3 and later, use the server's cipher pref-
- erence order instead of the client's cipher prefer-
- ence order.
+ With SSLv3 and later, use the Postfix SMTP server's
+ cipher preference order instead of the remote
+ client's cipher preference order.
<b><a href="postconf.5.html#tls_disable_workarounds">tls_disable_workarounds</a> (see 'postconf -d' output)</b>
- List or bit-mask of OpenSSL bug work-arounds to
+ List or bit-mask of OpenSSL bug work-arounds to
disable.
<b>OBSOLETE STARTTLS CONTROLS</b>
- The following configuration parameters exist for compati-
+ The following configuration parameters exist for compati-
bility with Postfix versions before 2.3. Support for these
will be removed in a future release.
<b><a href="postconf.5.html#smtpd_use_tls">smtpd_use_tls</a> (no)</b>
- Opportunistic TLS: announce STARTTLS support to
- SMTP clients, but do not require that clients use
- TLS encryption.
+ Opportunistic TLS: announce STARTTLS support to
+ remote SMTP clients, but do not require that
+ clients use TLS encryption.
<b><a href="postconf.5.html#smtpd_enforce_tls">smtpd_enforce_tls</a> (no)</b>
- Mandatory TLS: announce STARTTLS support to SMTP
- clients, and require that clients use TLS encryp-
- tion.
+ Mandatory TLS: announce STARTTLS support to remote
+ SMTP clients, and require that clients use TLS
+ encryption.
<b><a href="postconf.5.html#smtpd_tls_cipherlist">smtpd_tls_cipherlist</a> (empty)</b>
Obsolete Postfix < 2.3 control for the Postfix SMTP
server TLS cipher list.
<b>VERP SUPPORT CONTROLS</b>
- With VERP style delivery, each recipient of a message
+ With VERP style delivery, each recipient of a message
receives a customized copy of the message with his/her own
- recipient address encoded in the envelope sender address.
+ recipient address encoded in the envelope sender address.
The <a href="VERP_README.html">VERP_README</a> file describes configuration and operation
- details of Postfix support for variable envelope return
+ details of Postfix support for variable envelope return
path addresses. VERP style delivery is requested with the
- SMTP XVERP command or with the "sendmail -V" command-line
- option and is available in Postfix version 1.1 and later.
+ SMTP XVERP command or with the "sendmail -V" command-line
+ option and is available in Postfix version 1.1 and later.
<b><a href="postconf.5.html#default_verp_delimiters">default_verp_delimiters</a> (+=)</b>
The two default VERP delimiter characters.
<b><a href="postconf.5.html#verp_delimiter_filter">verp_delimiter_filter</a> (-=+)</b>
- The characters Postfix accepts as VERP delimiter
- characters on the Postfix <a href="sendmail.1.html"><b>sendmail</b>(1)</a> command line
+ The characters Postfix accepts as VERP delimiter
+ characters on the Postfix <a href="sendmail.1.html"><b>sendmail</b>(1)</a> command line
and in SMTP commands.
Available in Postfix version 1.1 and 2.0:
<b><a href="postconf.5.html#authorized_verp_clients">authorized_verp_clients</a> ($<a href="postconf.5.html#mynetworks">mynetworks</a>)</b>
- What SMTP clients are allowed to specify the XVERP
- command.
+ What remote SMTP clients are allowed to specify the
+ XVERP command.
Available in Postfix version 2.1 and later:
<b><a href="postconf.5.html#smtpd_authorized_verp_clients">smtpd_authorized_verp_clients</a> ($<a href="postconf.5.html#authorized_verp_clients">authorized_verp_clients</a>)</b>
- What SMTP clients are allowed to specify the XVERP
- command.
+ What remote SMTP clients are allowed to specify the
+ XVERP command.
<b>TROUBLE SHOOTING CONTROLS</b>
- The <a href="DEBUG_README.html">DEBUG_README</a> document describes how to debug parts of
- the Postfix mail system. The methods vary from making the
- software log a lot of detail, to running some daemon pro-
+ The <a href="DEBUG_README.html">DEBUG_README</a> document describes how to debug parts of
+ the Postfix mail system. The methods vary from making the
+ software log a lot of detail, to running some daemon pro-
cesses under control of a call tracer or debugger.
<b><a href="postconf.5.html#debug_peer_level">debug_peer_level</a> (2)</b>
- The increment in verbose logging level when a
- remote client or server matches a pattern in the
+ The increment in verbose logging level when a
+ remote client or server matches a pattern in the
<a href="postconf.5.html#debug_peer_list">debug_peer_list</a> parameter.
<b><a href="postconf.5.html#debug_peer_list">debug_peer_list</a> (empty)</b>
- Optional list of remote client or server hostname
- or network address patterns that cause the verbose
- logging level to increase by the amount specified
+ Optional list of remote client or server hostname
+ or network address patterns that cause the verbose
+ logging level to increase by the amount specified
in $<a href="postconf.5.html#debug_peer_level">debug_peer_level</a>.
<b><a href="postconf.5.html#error_notice_recipient">error_notice_recipient</a> (postmaster)</b>
- The recipient of postmaster notifications about
- mail delivery problems that are caused by policy,
+ The recipient of postmaster notifications about
+ mail delivery problems that are caused by policy,
resource, software or protocol errors.
<b><a href="postconf.5.html#internal_mail_filter_classes">internal_mail_filter_classes</a> (empty)</b>
- What categories of Postfix-generated mail are sub-
- ject to before-queue content inspection by
+ What categories of Postfix-generated mail are sub-
+ ject to before-queue content inspection by
<a href="postconf.5.html#non_smtpd_milters">non_smtpd_milters</a>, <a href="postconf.5.html#header_checks">header_checks</a> and <a href="postconf.5.html#body_checks">body_checks</a>.
<b><a href="postconf.5.html#notify_classes">notify_classes</a> (resource, software)</b>
- The list of error classes that are reported to the
+ The list of error classes that are reported to the
postmaster.
<b><a href="postconf.5.html#smtpd_reject_footer">smtpd_reject_footer</a> (empty)</b>
- Optional information that is appended after each
- SMTP server 4XX or 5XX response.
+ Optional information that is appended after each
+ Postfix SMTP server 4XX or 5XX response.
<b><a href="postconf.5.html#soft_bounce">soft_bounce</a> (no)</b>
Safety net to keep mail queued that would otherwise
Available in Postfix version 2.1 and later:
<b><a href="postconf.5.html#smtpd_authorized_xclient_hosts">smtpd_authorized_xclient_hosts</a> (empty)</b>
- What SMTP clients are allowed to use the XCLIENT
- feature.
+ What remote SMTP clients are allowed to use the
+ XCLIENT feature.
<b>KNOWN VERSUS UNKNOWN RECIPIENT CONTROLS</b>
- As of Postfix version 2.0, the SMTP server rejects mail
- for unknown recipients. This prevents the mail queue from
- clogging up with undeliverable MAILER-DAEMON messages.
- Additional information on this topic is in the
+ As of Postfix version 2.0, the SMTP server rejects mail
+ for unknown recipients. This prevents the mail queue from
+ clogging up with undeliverable MAILER-DAEMON messages.
+ Additional information on this topic is in the
<a href="LOCAL_RECIPIENT_README.html">LOCAL_RECIPIENT_README</a> and <a href="ADDRESS_CLASS_README.html">ADDRESS_CLASS_README</a> documents.
<b><a href="postconf.5.html#show_user_unknown_table_name">show_user_unknown_table_name</a> (yes)</b>
- Display the name of the recipient table in the
+ Display the name of the recipient table in the
"User unknown" responses.
<b><a href="postconf.5.html#canonical_maps">canonical_maps</a> (empty)</b>
- Optional address mapping lookup tables for message
+ Optional address mapping lookup tables for message
headers and envelopes.
<b><a href="postconf.5.html#recipient_canonical_maps">recipient_canonical_maps</a> (empty)</b>
<b><a href="postconf.5.html#mydestination">mydestination</a> ($<a href="postconf.5.html#myhostname">myhostname</a>, localhost.$<a href="postconf.5.html#mydomain">mydomain</a>, local-</b>
<b>host)</b>
- The list of domains that are delivered via the
+ The list of domains that are delivered via the
$<a href="postconf.5.html#local_transport">local_transport</a> mail delivery transport.
<b><a href="postconf.5.html#inet_interfaces">inet_interfaces</a> (all)</b>
<b><a href="postconf.5.html#proxy_interfaces">proxy_interfaces</a> (empty)</b>
The network interface addresses that this mail sys-
- tem receives mail on by way of a proxy or network
+ tem receives mail on by way of a proxy or network
address translation unit.
<b><a href="postconf.5.html#inet_protocols">inet_protocols</a> (all)</b>
- The Internet protocols Postfix will attempt to use
+ The Internet protocols Postfix will attempt to use
when making or accepting connections.
<b><a href="postconf.5.html#local_recipient_maps">local_recipient_maps</a> (<a href="proxymap.8.html">proxy</a>:unix:passwd.byname</b>
<b>$<a href="postconf.5.html#alias_maps">alias_maps</a>)</b>
- Lookup tables with all names or addresses of local
- recipients: a recipient address is local when its
- domain matches $<a href="postconf.5.html#mydestination">mydestination</a>, $<a href="postconf.5.html#inet_interfaces">inet_interfaces</a> or
+ Lookup tables with all names or addresses of local
+ recipients: a recipient address is local when its
+ domain matches $<a href="postconf.5.html#mydestination">mydestination</a>, $<a href="postconf.5.html#inet_interfaces">inet_interfaces</a> or
$<a href="postconf.5.html#proxy_interfaces">proxy_interfaces</a>.
<b><a href="postconf.5.html#unknown_local_recipient_reject_code">unknown_local_recipient_reject_code</a> (550)</b>
- The numerical Postfix SMTP server response code
- when a recipient address is local, and
- $<a href="postconf.5.html#local_recipient_maps">local_recipient_maps</a> specifies a list of lookup
+ The numerical Postfix SMTP server response code
+ when a recipient address is local, and
+ $<a href="postconf.5.html#local_recipient_maps">local_recipient_maps</a> specifies a list of lookup
tables that does not match the recipient.
- Parameters concerning known/unknown recipients of relay
+ Parameters concerning known/unknown recipients of relay
destinations:
<b><a href="postconf.5.html#relay_domains">relay_domains</a> ($<a href="postconf.5.html#mydestination">mydestination</a>)</b>
- What destination domains (and subdomains thereof)
+ What destination domains (and subdomains thereof)
this system will relay mail to.
<b><a href="postconf.5.html#relay_recipient_maps">relay_recipient_maps</a> (empty)</b>
- Optional lookup tables with all valid addresses in
+ Optional lookup tables with all valid addresses in
the domains that match $<a href="postconf.5.html#relay_domains">relay_domains</a>.
<b><a href="postconf.5.html#unknown_relay_recipient_reject_code">unknown_relay_recipient_reject_code</a> (550)</b>
The numerical Postfix SMTP server reply code when a
- recipient address matches $<a href="postconf.5.html#relay_domains">relay_domains</a>, and
- <a href="postconf.5.html#relay_recipient_maps">relay_recipient_maps</a> specifies a list of lookup
+ recipient address matches $<a href="postconf.5.html#relay_domains">relay_domains</a>, and
+ <a href="postconf.5.html#relay_recipient_maps">relay_recipient_maps</a> specifies a list of lookup
tables that does not match the recipient address.
- Parameters concerning known/unknown recipients in virtual
+ Parameters concerning known/unknown recipients in virtual
alias domains:
<b><a href="postconf.5.html#virtual_alias_domains">virtual_alias_domains</a> ($<a href="postconf.5.html#virtual_alias_maps">virtual_alias_maps</a>)</b>
Postfix is final destination for the specified list
- of virtual alias domains, that is, domains for
- which all addresses are aliased to addresses in
+ of virtual alias domains, that is, domains for
+ which all addresses are aliased to addresses in
other local or remote domains.
<b><a href="postconf.5.html#virtual_alias_maps">virtual_alias_maps</a> ($<a href="postconf.5.html#virtual_maps">virtual_maps</a>)</b>
- Optional lookup tables that alias specific mail
- addresses or domains to other local or remote
+ Optional lookup tables that alias specific mail
+ addresses or domains to other local or remote
address.
<b><a href="postconf.5.html#unknown_virtual_alias_reject_code">unknown_virtual_alias_reject_code</a> (550)</b>
- The SMTP server reply code when a recipient address
-
matches $<a href="postconf.5.html#virtual_alias_domains">virtual_alias_domains</a>, and $<a href="postconf.5.html#virtual_alias_maps">vir</a>-
- <a href="postconf.5.html#virtual_alias_maps">tual_alias_maps</a> specifies a list of lookup tables
+ The Postfix SMTP server reply code when a recipient
+
address matches $<a href="postconf.5.html#virtual_alias_domains">virtual_alias_domains</a>, and $<a href="postconf.5.html#virtual_alias_maps">vir</a>-
+ <a href="postconf.5.html#virtual_alias_maps">tual_alias_maps</a> specifies a list of lookup tables
that does not match the recipient address.
- Parameters concerning known/unknown recipients in virtual
+ Parameters concerning known/unknown recipients in virtual
mailbox domains:
<b><a href="postconf.5.html#virtual_mailbox_domains">virtual_mailbox_domains</a> ($<a href="postconf.5.html#virtual_mailbox_maps">virtual_mailbox_maps</a>)</b>
Postfix is final destination for the specified list
- of
domains; mail is delivered via the $<a href="postconf.5.html#virtual_transport">vir</a>-
+ of
domains; mail is delivered via the $<a href="postconf.5.html#virtual_transport">vir</a>-
<a href="postconf.5.html#virtual_transport">tual_transport</a> mail delivery transport.
<b><a href="postconf.5.html#virtual_mailbox_maps">virtual_mailbox_maps</a> (empty)</b>
- Optional lookup tables with all valid addresses in
+ Optional lookup tables with all valid addresses in
the domains that match $<a href="postconf.5.html#virtual_mailbox_domains">virtual_mailbox_domains</a>.
<b><a href="postconf.5.html#unknown_virtual_mailbox_reject_code">unknown_virtual_mailbox_reject_code</a> (550)</b>
- The SMTP server reply code when a recipient address
-
matches $<a href="postconf.5.html#virtual_mailbox_domains">virtual_mailbox_domains</a>, and $<a href="postconf.5.html#virtual_mailbox_maps">vir</a>-
+ The Postfix SMTP server reply code when a recipient
+
address matches $<a href="postconf.5.html#virtual_mailbox_domains">virtual_mailbox_domains</a>, and $<a href="postconf.5.html#virtual_mailbox_maps">vir</a>-
<a href="postconf.5.html#virtual_mailbox_maps">tual_mailbox_maps</a> specifies a list of lookup tables
that does not match the recipient address.
<b>RESOURCE AND RATE CONTROLS</b>
- The following parameters limit resource usage by the SMTP
+ The following parameters limit resource usage by the SMTP
server and/or control client request rates.
<b><a href="postconf.5.html#line_length_limit">line_length_limit</a> (2048)</b>
- Upon input, long lines are chopped up into pieces
- of at most this length; upon delivery, long lines
+ Upon input, long lines are chopped up into pieces
+ of at most this length; upon delivery, long lines
are reconstructed.
<b><a href="postconf.5.html#queue_minfree">queue_minfree</a> (0)</b>
- The minimal amount of free space in bytes in the
+ The minimal amount of free space in bytes in the
queue file system that is needed to receive mail.
<b><a href="postconf.5.html#message_size_limit">message_size_limit</a> (10240000)</b>
- The maximal size in bytes of a message, including
+ The maximal size in bytes of a message, including
envelope information.
<b><a href="postconf.5.html#smtpd_recipient_limit">smtpd_recipient_limit</a> (1000)</b>
- The maximal number of recipients that the Postfix
+ The maximal number of recipients that the Postfix
SMTP server accepts per message delivery request.
<b><a href="postconf.5.html#smtpd_timeout">smtpd_timeout</a> (normal: 300s, overload: 10s)</b>
- The time limit for sending a Postfix SMTP server
- response and for receiving a remote SMTP client
+ The time limit for sending a Postfix SMTP server
+ response and for receiving a remote SMTP client
request.
<b><a href="postconf.5.html#smtpd_history_flush_threshold">smtpd_history_flush_threshold</a> (100)</b>
- The maximal number of lines in the Postfix SMTP
- server command history before it is flushed upon
+ The maximal number of lines in the Postfix SMTP
+ server command history before it is flushed upon
receipt of EHLO, RSET, or end of DATA.
Available in Postfix version 2.3 and later:
<b><a href="postconf.5.html#smtpd_peername_lookup">smtpd_peername_lookup</a> (yes)</b>
Attempt to look up the remote SMTP client hostname,
- and verify that the name matches the client IP
+ and verify that the name matches the client IP
address.
The per SMTP client connection count and request rate lim-
its are implemented in co-operation with the <a href="anvil.8.html"><b>anvil</b>(8)</a> ser-
- vice, and are available in Postfix version 2.2 and later.
+ vice, and are available in Postfix version 2.2 and later.
<b><a href="postconf.5.html#smtpd_client_connection_count_limit">smtpd_client_connection_count_limit</a> (50)</b>
- How many simultaneous connections any client is
+ How many simultaneous connections any client is
allowed to make to this service.
<b><a href="postconf.5.html#smtpd_client_connection_rate_limit">smtpd_client_connection_rate_limit</a> (0)</b>
The maximal number of connection attempts any
- client is allowed to make to this service per time
+ client is allowed to make to this service per time
unit.
<b><a href="postconf.5.html#smtpd_client_message_rate_limit">smtpd_client_message_rate_limit</a> (0)</b>
- The maximal number of message delivery requests
- that any client is allowed to make to this service
+ The maximal number of message delivery requests
+ that any client is allowed to make to this service
per time unit, regardless of whether or not Postfix
actually accepts those messages.
<b><a href="postconf.5.html#smtpd_client_recipient_rate_limit">smtpd_client_recipient_rate_limit</a> (0)</b>
- The maximal number of recipient addresses that any
- client is allowed to send to this service per time
+ The maximal number of recipient addresses that any
+ client is allowed to send to this service per time
unit, regardless of whether or not Postfix actually
accepts those recipients.
<b><a href="postconf.5.html#smtpd_client_event_limit_exceptions">smtpd_client_event_limit_exceptions</a> ($<a href="postconf.5.html#mynetworks">mynetworks</a>)</b>
- Clients that are excluded from
+ Clients that are excluded from
smtpd_client_*_count/rate_limit restrictions.
Available in Postfix version 2.3 and later:
<b><a href="postconf.5.html#smtpd_per_record_deadline">smtpd_per_record_deadline</a> (normal: no, overload: yes)</b>
Change the behavior of the <a href="postconf.5.html#smtpd_timeout">smtpd_timeout</a> time
- limit, from a time limit per read or write system
+ limit, from a time limit per read or write system
call, to a time limit to send or receive a complete
- record (an SMTP command line, SMTP response line,
- SMTP message content line, or TLS protocol mes-
+ record (an SMTP command line, SMTP response line,
+ SMTP message content line, or TLS protocol mes-
sage).
<b>TARPIT CONTROLS</b>
- When a remote SMTP client makes errors, the Postfix SMTP
- server can insert delays before responding. This can help
- to slow down run-away software. The behavior is con-
- trolled by an error counter that counts the number of
- errors within an SMTP session that a client makes without
+ When a remote SMTP client makes errors, the Postfix SMTP
+ server can insert delays before responding. This can help
+ to slow down run-away software. The behavior is con-
+ trolled by an error counter that counts the number of
+ errors within an SMTP session that a client makes without
delivering mail.
<b><a href="postconf.5.html#smtpd_error_sleep_time">smtpd_error_sleep_time</a> (1s)</b>
With Postfix version 2.1 and later: the SMTP server
- response delay after a client has made more than
- $<a href="postconf.5.html#smtpd_soft_error_limit">smtpd_soft_error_limit</a> errors, and fewer than
- $<a href="postconf.5.html#smtpd_hard_error_limit">smtpd_hard_error_limit</a> errors, without delivering
+ response delay after a client has made more than
+ $<a href="postconf.5.html#smtpd_soft_error_limit">smtpd_soft_error_limit</a> errors, and fewer than
+ $<a href="postconf.5.html#smtpd_hard_error_limit">smtpd_hard_error_limit</a> errors, without delivering
mail.
<b><a href="postconf.5.html#smtpd_soft_error_limit">smtpd_soft_error_limit</a> (10)</b>
- The number of errors a remote SMTP client is
- allowed to make without delivering mail before the
+ The number of errors a remote SMTP client is
+ allowed to make without delivering mail before the
Postfix SMTP server slows down all its responses.
<b><a href="postconf.5.html#smtpd_hard_error_limit">smtpd_hard_error_limit</a> (normal: 20, overload: 1)</b>
- The maximal number of errors a remote SMTP client
+ The maximal number of errors a remote SMTP client
is allowed to make without delivering mail.
<b><a href="postconf.5.html#smtpd_junk_command_limit">smtpd_junk_command_limit</a> (normal: 100, overload: 1)</b>
- The number of junk commands (NOOP, VRFY, ETRN or
+ The number of junk commands (NOOP, VRFY, ETRN or
RSET) that a remote SMTP client can send before the
- Postfix SMTP server starts to increment the error
+ Postfix SMTP server starts to increment the error
counter with each junk command.
Available in Postfix version 2.1 and later:
<b><a href="postconf.5.html#smtpd_recipient_overshoot_limit">smtpd_recipient_overshoot_limit</a> (1000)</b>
- The number of recipients that a remote SMTP client
- can send in excess of the limit specified with
+ The number of recipients that a remote SMTP client
+ can send in excess of the limit specified with
$<a href="postconf.5.html#smtpd_recipient_limit">smtpd_recipient_limit</a>, before the Postfix SMTP
- server increments the per-session error count for
+ server increments the per-session error count for
each excess recipient.
<b>ACCESS POLICY DELEGATION CONTROLS</b>
- As of version 2.1, Postfix can be configured to delegate
- access policy decisions to an external server that runs
- outside Postfix. See the file <a href="SMTPD_POLICY_README.html">SMTPD_POLICY_README</a> for
+ As of version 2.1, Postfix can be configured to delegate
+ access policy decisions to an external server that runs
+ outside Postfix. See the file <a href="SMTPD_POLICY_README.html">SMTPD_POLICY_README</a> for
more information.
<b><a href="postconf.5.html#smtpd_policy_service_max_idle">smtpd_policy_service_max_idle</a> (300s)</b>
- The time after which an idle SMTPD policy service
+ The time after which an idle SMTPD policy service
connection is closed.
<b><a href="postconf.5.html#smtpd_policy_service_max_ttl">smtpd_policy_service_max_ttl</a> (1000s)</b>
connection is closed.
<b><a href="postconf.5.html#smtpd_policy_service_timeout">smtpd_policy_service_timeout</a> (100s)</b>
- The time limit for connecting to, writing to or
+ The time limit for connecting to, writing to or
receiving from a delegated SMTPD policy server.
<b>ACCESS CONTROLS</b>
- The <a href="SMTPD_ACCESS_README.html">SMTPD_ACCESS_README</a> document gives an introduction to
+ The <a href="SMTPD_ACCESS_README.html">SMTPD_ACCESS_README</a> document gives an introduction to
all the SMTP server access control features.
<b><a href="postconf.5.html#smtpd_delay_reject">smtpd_delay_reject</a> (yes)</b>
- Wait until the RCPT TO command before evaluating
+ Wait until the RCPT TO command before evaluating
$<a href="postconf.5.html#smtpd_client_restrictions">smtpd_client_restrictions</a>, $smtpd_helo_restric-
tions and $<a href="postconf.5.html#smtpd_sender_restrictions">smtpd_sender_restrictions</a>, or wait until
- the ETRN command before evaluating
+ the ETRN command before evaluating
$<a href="postconf.5.html#smtpd_client_restrictions">smtpd_client_restrictions</a> and $smtpd_helo_restric-
tions.
- <b><a href="postconf.5.html#parent_domain_matches_subdomains">parent_domain_matches_subdomains</a> (see 'postconf -d' out-</b>
+ <b><a href="postconf.5.html#parent_domain_matches_subdomains">parent_domain_matches_subdomains</a> (see 'postconf -d' out-</b>
<b>put)</b>
What Postfix features match subdomains of
"domain.tld" automatically, instead of requiring an
explicit ".domain.tld" pattern.
<b><a href="postconf.5.html#smtpd_client_restrictions">smtpd_client_restrictions</a> (empty)</b>
- Optional SMTP server access restrictions in the
- context of a client SMTP connection request.
+ Optional Postfix SMTP server access restrictions in
+ the context of a remote SMTP client connection
+ request.
<b><a href="postconf.5.html#smtpd_helo_required">smtpd_helo_required</a> (no)</b>
Require that a remote SMTP client introduces itself
Available in Postfix version 2.0 and later:
<b><a href="postconf.5.html#default_rbl_reply">default_rbl_reply</a> (see 'postconf -d' output)</b>
- The default SMTP server response template for a
- request that is rejected by an RBL-based restric-
- tion.
+ The default Postfix SMTP server response template
+ for a request that is rejected by an RBL-based
+ restriction.
<b><a href="postconf.5.html#multi_recipient_bounce_reject_code">multi_recipient_bounce_reject_code</a> (550)</b>
The numerical Postfix SMTP server response code
The internet hostname of this mail system.
<b><a href="postconf.5.html#mynetworks">mynetworks</a> (see 'postconf -d' output)</b>
- The list of "trusted" SMTP clients that have more
- privileges than "strangers".
+ The list of "trusted" remote SMTP clients that have
+ more privileges than "strangers".
<b><a href="postconf.5.html#myorigin">myorigin</a> ($<a href="postconf.5.html#myhostname">myhostname</a>)</b>
The domain name that locally-posted mail appears to
<b><a href="postconf.5.html#tlsproxy_tls_fingerprint_digest">tlsproxy_tls_fingerprint_digest</a> ($<a href="postconf.5.html#smtpd_tls_fingerprint_digest">smtpd_tls_finger</a>-</b>
<b><a href="postconf.5.html#smtpd_tls_fingerprint_digest">print_digest</a>)</b>
- The message digest algorithm used to construct
- client-certificate fingerprints.
+ The message digest algorithm to construct remote
+ SMTP client-certificate fingerprints.
<b><a href="postconf.5.html#tlsproxy_tls_key_file">tlsproxy_tls_key_file</a> ($<a href="postconf.5.html#smtpd_tls_key_file">smtpd_tls_key_file</a>)</b>
File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server RSA pri-
<b><a href="postconf.5.html#tlsproxy_use_tls">tlsproxy_use_tls</a> ($<a href="postconf.5.html#smtpd_use_tls">smtpd_use_tls</a>)</b>
Opportunistic TLS: announce STARTTLS support to
- SMTP clients, but do not require that clients use
- TLS encryption.
+ remote SMTP clients, but do not require that
+ clients use TLS encryption.
<b><a href="postconf.5.html#tlsproxy_enforce_tls">tlsproxy_enforce_tls</a> ($<a href="postconf.5.html#smtpd_enforce_tls">smtpd_enforce_tls</a>)</b>
- Mandatory TLS: announce STARTTLS support to SMTP
- clients, and require that clients use TLS encryp-
- tion.
+ Mandatory TLS: announce STARTTLS support to remote
+ SMTP clients, and require that clients use TLS
+ encryption.
<b>RESOURCE CONTROLS</b>
<b><a href="postconf.5.html#tlsproxy_watchdog_timeout">tlsproxy_watchdog_timeout</a> (10s)</b>
a \fBmaster.cf\fR entry plus a Postfix-defined suffix).
.IP \fBuser\fR
Parameters with user-defined names.
+.IP \fBall\fR
+All the above classes.
.RE
.IP
-The default is as if "\fB-C builtin,service,user\fR" is
+The default is as if "\fB-C all\fR" is
specified.
.IP \fB-d\fR
Print \fBmain.cf\fR default parameter settings instead of
"local_header_rewrite_clients = static:all".
.SH application_event_drain_time (default: 100s)
How long the \fBpostkick\fR(1) command waits for a request to enter the
-server's input buffer before giving up.
+Postfix daemon process input buffer before giving up.
.PP
Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
The default time unit is s (seconds).
.PP
This feature is available in Postfix 2.2 and later.
.SH authorized_verp_clients (default: $mynetworks)
-What SMTP clients are allowed to specify the XVERP command.
+What remote SMTP clients are allowed to specify the XVERP command.
This command requests that mail be delivered one recipient at a
time with a per recipient return address.
.PP
.PP
This feature is available in Postfix 2.3 and later.
.SH broken_sasl_auth_clients (default: no)
-Enable inter-operability with SMTP clients that implement an obsolete
+Enable inter-operability with remote SMTP clients that implement an obsolete
version of the AUTH command (RFC 4954). Examples of such clients
are MicroSoft Outlook Express version 4 and MicroSoft Exchange
version 5.0.
a given service. This limit can be overruled for specific services
in the master.cf file.
.SH default_rbl_reply (default: see "postconf -d" output)
-The default SMTP server response template for a request that is
+The default Postfix SMTP server response template for a request that is
rejected by an RBL-based restriction. This template can be overruled
by specific entries in the optional rbl_reply_maps lookup table.
.PP
arrival rate exceeds the message delivery rate. This feature is
turned on by default (it's disabled on SCO UNIX due to an SCO bug).
.PP
-With the default 100 SMTP server process limit, "in_flow_delay
+With the default 100 Postfix SMTP server process limit, "in_flow_delay
= 1s" limits the mail inflow to 100 messages per second above the
number of messages delivered per second.
.PP
.PP
On a multi-homed firewall with separate Postfix instances listening on the
"inside" and "outside" interfaces, this can prevent each instance from
-being able to reach servers on the "other side" of the firewall. Setting
+being able to reach remote SMTP servers on the "other side" of the
+firewall. Setting
smtp_bind_address to 0.0.0.0 avoids the potential problem for
IPv4, and setting smtp_bind_address6 to :: solves the problem
for IPv6.
Do not change this unless you have a complete understanding of RFC 2821.
.SH ipc_idle (default: version dependent)
The time after which a client closes an idle internal communication
-channel. The purpose is to allow servers to terminate voluntarily
-after they become idle. This is used, for example, by the address
-resolving and rewriting clients.
+channel. The purpose is to allow Postfix daemon processes to
+terminate voluntarily after they become idle. This is used, for
+example, by the Postfix address resolving and rewriting clients.
.PP
With Postfix 2.4 the default value was reduced from 100s to 5s.
.PP
The default time unit is s (seconds).
.SH ipc_ttl (default: 1000s)
The time after which a client closes an active internal communication
-channel. The purpose is to allow servers to terminate voluntarily
+channel. The purpose is to allow Postfix daemon processes to
+terminate voluntarily
after reaching their client limit. This is used, for example, by
-the address resolving and rewriting clients.
+the Postfix address resolving and rewriting clients.
.PP
Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
The default time unit is s (seconds).
.PP
This feature is available in Postfix 2.8 and later.
.SH lmtp_assume_final (default: no)
-When an LMTP server announces no DSN support, assume that the
+When a remote LMTP server announces no DSN support, assume that
+the
server performs final delivery, and send "delivered" delivery status
notifications instead of "relayed". The default setting is backwards
compatible to avoid the infinetisimal possibility of breaking
lmtp_connection_cache_destinations, or lmtp_connection_reuse_time_limit.
.PP
The effectiveness of cached connections will be determined by the
-number of LMTP servers in use, and the concurrency limit specified
-for the LMTP client. Cached connections are closed under any of
+number of remote LMTP servers in use, and the concurrency limit specified
+for the Postfix LMTP client. Cached connections are closed under any of
the following conditions:
.IP \(bu
-The LMTP client idle time limit is reached. This limit is
+The Postfix LMTP client idle time limit is reached. This limit is
specified with the Postfix max_idle configuration parameter.
.IP \(bu
A delivery request specifies a different destination than the
reached. This limit is specified with the Postfix max_use
configuration parameter.
.IP \(bu
-Upon the onset of another delivery request, the LMTP server
+Upon the onset of another delivery request, the remote LMTP server
associated with the current session does not respond to the RSET
command.
.PP
-Most of these limitations will be removed after Postfix implements
+Most of these limitations have been with the Postfix
a connection cache that is shared among multiple LMTP client
programs.
.SH lmtp_cname_overrides_servername (default: yes)
.PP
This feature is available in Postfix 2.3 and later.
.SH lmtp_connect_timeout (default: 0s)
-The LMTP client time limit for completing a TCP connection, or
+The Postfix LMTP client time limit for completing a TCP connection, or
zero (use the operating system built-in time limit). When no
connection can be made within the deadline, the LMTP client tries
the next address on the mail exchanger list.
.PP
This feature is available in Postfix 2.3 and later.
.SH lmtp_data_done_timeout (default: 600s)
-The LMTP client time limit for sending the LMTP ".", and for
-receiving the server response. When no response is received within
-the deadline, a warning is logged that the mail may be delivered
-multiple times.
+The Postfix LMTP client time limit for sending the LMTP ".",
+and for receiving the remote LMTP server response. When no response
+is received within the deadline, a warning is logged that the mail
+may be delivered multiple times.
.PP
Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
The default time unit is s (seconds).
.SH lmtp_data_init_timeout (default: 120s)
-The LMTP client time limit for sending the LMTP DATA command, and
-for receiving the server response.
+The Postfix LMTP client time limit for sending the LMTP DATA command,
+and
+for receiving the remote LMTP server response.
.PP
Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
The default time unit is s (seconds).
.SH lmtp_data_xfer_timeout (default: 180s)
-The LMTP client time limit for sending the LMTP message content.
+The Postfix LMTP client time limit for sending the LMTP message
+content.
When the connection stalls for more than $lmtp_data_xfer_timeout
the LMTP client terminates the transfer.
.PP
.SH lmtp_discard_lhlo_keyword_address_maps (default: empty)
Lookup tables, indexed by the remote LMTP server address, with
case insensitive lists of LHLO keywords (pipelining, starttls,
-auth, etc.) that the LMTP client will ignore in the LHLO response
+auth, etc.) that the Postfix LMTP client will ignore in the LHLO
+response
from a remote LMTP server. See lmtp_discard_lhlo_keywords for
details. The table is not indexed by hostname for consistency with
smtpd_discard_ehlo_keyword_address_maps.
This feature is available in Postfix 2.3 and later.
.SH lmtp_discard_lhlo_keywords (default: empty)
A case insensitive list of LHLO keywords (pipelining, starttls,
-auth, etc.) that the LMTP client will ignore in the LHLO response
+auth, etc.) that the Postfix LMTP client will ignore in the LHLO
+response
from a remote LMTP server.
.PP
This feature is available in Postfix 2.3 and later.
.PP
This feature is available in Postfix 2.3 and later.
.SH lmtp_lhlo_timeout (default: 300s)
-The LMTP client time limit for sending the LHLO command, and
-for receiving the initial server response.
+The Postfix LMTP client time limit for sending the LHLO command,
+and for receiving the initial remote LMTP server response.
.PP
Time units: s (seconds), m (minutes), h (hours), d (days), w
(weeks). The default time unit is s (seconds).
.PP
This feature is available in Postfix 2.3 and later.
.SH lmtp_mail_timeout (default: 300s)
-The LMTP client time limit for sending the MAIL FROM command, and
-for receiving the server response.
+The Postfix LMTP client time limit for sending the MAIL FROM command,
+and for receiving the remote LMTP server response.
.PP
Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
The default time unit is s (seconds).
.PP
This feature is available in Postfix 2.4 and later.
.SH lmtp_quit_timeout (default: 300s)
-The LMTP client time limit for sending the QUIT command, and for
-receiving the server response.
+The Postfix LMTP client time limit for sending the QUIT command,
+and for receiving the remote LMTP server response.
.PP
Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
The default time unit is s (seconds).
.PP
This feature is available in Postfix 2.3 and later.
.SH lmtp_rcpt_timeout (default: 300s)
-The LMTP client time limit for sending the RCPT TO command, and
-for receiving the server response.
+The Postfix LMTP client time limit for sending the RCPT TO command,
+and for receiving the remote LMTP server response.
.PP
Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
The default time unit is s (seconds).
.PP
This feature is available in Postfix 2.7 and later.
.SH lmtp_rset_timeout (default: 20s)
-The LMTP client time limit for sending the RSET command, and
-for receiving the server response. The LMTP client sends RSET in
+The Postfix LMTP client time limit for sending the RSET command,
+and for receiving the remote LMTP server response. The LMTP client
+sends RSET in
order to finish a recipient address probe, or to verify that a
cached connection is still alive.
.PP
.PP
This feature is available in Postfix 2.3 and later.
.SH lmtp_sasl_password_maps (default: empty)
-Optional LMTP client lookup tables with one username:password entry
+Optional Postfix LMTP client lookup tables with one username:password entry
per host or domain. If a remote host or domain has no username:password
entry, then the Postfix LMTP client will not attempt to authenticate
to the remote host.
.PP
This feature is available in Postfix 2.9 and later.
.SH lmtp_send_xforward_command (default: no)
-Send an XFORWARD command to the LMTP server when the LMTP LHLO
+Send an XFORWARD command to the remote LMTP server when the LMTP LHLO
server response announces XFORWARD support. This allows an \fBlmtp\fR(8)
delivery agent, used for content filter message injection, to
forward the name, address, protocol and HELO name of the original
.PP
This feature is available in Postfix 2.3 and later.
.SH lmtp_xforward_timeout (default: 300s)
-The LMTP client time limit for sending the XFORWARD command, and
-for receiving the server response.
+The Postfix LMTP client time limit for sending the XFORWARD command,
+and for receiving the remote LMTP server response.
.PP
In case of problems the client does NOT try the next address on
the mail exchanger list.
protocol.
.IP "\fBpermit_tls_clientcerts \fR"
Append the domain name in $myorigin or $mydomain when the
-client TLS certificate fingerprint is listed in $relay_clientcerts.
+remote SMTP client TLS certificate fingerprint or public key fingerprint
+(Postfix 2.9 and later) is listed in $relay_clientcerts.
The fingerprint digest algorithm is configurable via the
smtpd_tls_fingerprint_digest parameter (hard-coded as md5 prior to
Postfix version 2.5).
.IP "\fBpermit_tls_all_clientcerts \fR"
Append the domain name in $myorigin or $mydomain when the
-client TLS certificate is successfully verified, regardless of
+remote SMTP client TLS certificate is successfully verified, regardless of
whether it is listed on the server, and regardless of the certifying
authority.
.IP "\fBcheck_address_map \fItype:table\fR \fR"
.ad
.ft R
.SH mynetworks (default: see "postconf -d" output)
-The list of "trusted" SMTP clients that have more privileges than
+The list of "trusted" remote SMTP clients that have more privileges than
"strangers".
.PP
In particular, "trusted" SMTP clients are allowed to relay mail
"trust" only the local machine.
.IP \(bu
Specify "mynetworks_style = subnet" when Postfix
-should "trust" SMTP clients in the same IP subnetworks as the local
+should "trust" remote SMTP clients in the same IP subnetworks as the local
machine. On Linux, this works correctly only with interfaces
specified with the "ifconfig" command.
.IP \(bu
Specify "mynetworks_style = class" when Postfix should
-"trust" SMTP clients in the same IP class A/B/C networks as the
+"trust" remote SMTP clients in the same IP class A/B/C networks as the
local machine. Don't do this with a dialup site - it would cause
Postfix to "trust" your entire provider's network. Instead, specify
an explicit mynetworks list by hand, as described with the mynetworks
.PP
This feature is available in Postfix 2.8.
.SH postscreen_bare_newline_action (default: ignore)
-The action that \fBpostscreen\fR(8) takes when an SMTP client sends
+The action that \fBpostscreen\fR(8) takes when a remote SMTP client sends
a bare newline character, that is, a newline not preceded by carriage
return. Specify one of the following:
.IP "\fBignore\fR"
This feature is available in Postfix 2.8.
.SH postscreen_bare_newline_enable (default: no)
Enable "bare newline" SMTP protocol tests in the \fBpostscreen\fR(8)
-server. These tests are expensive: a client must disconnect after
+server. These tests are expensive: a remote SMTP client must
+disconnect after
it passes the test, before it can talk to a real Postfix SMTP server.
.PP
This feature is available in Postfix 2.8.
The amount of time that \fBpostscreen\fR(8) will use the result from
a successful "bare newline" SMTP protocol test. During this
time, the client IP address is excluded from this test. The default
-is long because a client must disconnect after it passes the test,
+is long because a remote SMTP client must disconnect after it passes
+the test,
before it can talk to a real Postfix SMTP server.
.PP
Specify a non-zero time value (an integral value plus an optional
.PP
This feature is available in Postfix 2.8.
.SH postscreen_blacklist_action (default: ignore)
-The action that \fBpostscreen\fR(8) takes when an SMTP client is
+The action that \fBpostscreen\fR(8) takes when a remote SMTP client is
permanently blacklisted with the postscreen_access_list parameter.
Specify one of the following:
.IP "\fBignore\fR (default)"
.PP
This feature is available in Postfix 2.8.
.SH postscreen_client_connection_count_limit (default: $smtpd_client_connection_count_limit)
-How many simultaneous connections any client is allowed to have
+How many simultaneous connections any remote SMTP client is
+allowed to have
with the \fBpostscreen\fR(8) daemon. By default, this limit is the same
as with the Postfix SMTP server. Note that the triage process can
take several seconds, with the time spent in postscreen_greet_wait
.PP
This feature is available in Postfix 2.8 and later.
.SH postscreen_dnsbl_action (default: ignore)
-The action that \fBpostscreen\fR(8) takes when an SMTP client's combined
+The action that \fBpostscreen\fR(8) takes when a remote SMTP client's combined
DNSBL score is equal to or greater than a threshold (as defined
with the postscreen_dnsbl_sites and postscreen_dnsbl_threshold
parameters). Specify one of the following:
.PP
When a client's score is equal to or greater than the threshold
specified with postscreen_dnsbl_threshold, \fBpostscreen\fR(8) can drop
-the connection with the SMTP client.
+the connection with the remote SMTP client.
.PP
Specify a list of domain=filter*weight entries, separated by
comma or whitespace.
or more ";"-separated numbers or number..number ranges.
.IP \(bu
When no "*weight" is specified, \fBpostscreen\fR(8) increments
-the SMTP client's DNSBL score by 1. Otherwise, the weight must be
+the remote SMTP client's DNSBL score by 1. Otherwise, the weight must be
an integral number, and \fBpostscreen\fR(8) adds the specified weight to
-the SMTP client's DNSBL score. Specify a negative number for
+the remote SMTP client's DNSBL score. Specify a negative number for
whitelisting.
.IP \(bu
When one postscreen_dnsbl_sites entry produces multiple
.PP
This feature is available in Postfix 2.8.
.SH postscreen_dnsbl_threshold (default: 1)
-The inclusive lower bound for blocking an SMTP client, based on
+The inclusive lower bound for blocking a remote SMTP client, based on
its combined DNSBL score as defined with the postscreen_dnsbl_sites
parameter.
.PP
.PP
This feature is available in Postfix 2.8.
.SH postscreen_enforce_tls (default: $smtpd_enforce_tls)
-Mandatory TLS: announce STARTTLS support to SMTP clients, and
+Mandatory TLS: announce STARTTLS support to remote SMTP clients, and
require that clients use TLS encryption. See smtpd_postscreen_enforce_tls
for details.
.PP
.PP
This feature is available in Postfix 2.8.
.SH postscreen_greet_action (default: ignore)
-The action that \fBpostscreen\fR(8) takes when an SMTP client speaks
+The action that \fBpostscreen\fR(8) takes when a remote SMTP client speaks
before its turn within the time specified with the postscreen_greet_wait
parameter. Specify one of the following:
.IP "\fBignore\fR (default)"
Drop the connection immediately with a 521 SMTP reply. Repeat
this test the next time the client connects.
.PP
-In either case, \fBpostscreen\fR(8) will not whitelist the SMTP client
+In either case, \fBpostscreen\fR(8) will not whitelist the remote SMTP client
IP address.
.PP
This feature is available in Postfix 2.8.
.PP
This feature is available in Postfix 2.8.
.SH postscreen_non_smtp_command_action (default: drop)
-The action that \fBpostscreen\fR(8) takes when an SMTP client sends
+The action that \fBpostscreen\fR(8) takes when a remote SMTP client sends
non-SMTP commands as specified with the postscreen_forbidden_commands
parameter. Specify one of the following:
.IP "\fBignore\fR"
.PP
This feature is available in Postfix 2.8.
.SH postscreen_pipelining_action (default: enforce)
-The action that \fBpostscreen\fR(8) takes when an SMTP client sends
+The action that \fBpostscreen\fR(8) takes when a remote SMTP client
+sends
multiple commands instead of sending one command and waiting for
the server to respond. Specify one of the following:
.IP "\fBignore\fR"
This feature is available in Postfix 2.8.
.SH postscreen_post_queue_limit (default: $default_process_limit)
The number of clients that can be waiting for service from a
-real SMTP server process. When this queue is full, all clients will
+real Postfix SMTP server process. When this queue is full, all
+clients will
receive a 421 reponse.
.PP
This feature is available in Postfix 2.8.
.SH postscreen_pre_queue_limit (default: $default_process_limit)
The number of non-whitelisted clients that can be waiting for
-a decision whether they will receive service from a real SMTP server
+a decision whether they will receive service from a real Postfix
+SMTP server
process. When this queue is full, all non-whitelisted clients will
receive a 421 reponse.
.PP
This feature is available in Postfix 2.8.
.SH postscreen_reject_footer (default: $smtpd_reject_footer)
-Optional information that is appended after a 4XX or 5XX server
+Optional information that is appended after a 4XX or 5XX
+\fBpostscreen\fR(8) server
response. See smtpd_reject_footer for further details.
.PP
This feature is available in Postfix 2.8 and later.
.PP
This feature is available in Postfix 2.8 and later.
.SH postscreen_use_tls (default: $smtpd_use_tls)
-Opportunistic TLS: announce STARTTLS support to SMTP clients,
+Opportunistic TLS: announce STARTTLS support to remote SMTP clients,
but do not require that clients use TLS encryption.
.PP
This feature is available in Postfix 2.8 and later.
Preferably, use postscreen_tls_security_level instead.
.SH postscreen_watchdog_timeout (default: 10s)
How much time a \fBpostscreen\fR(8) process may take to respond to
-an SMTP client command or to perform a cache operation before it
+a remote SMTP client command or to perform a cache operation before it
is terminated by a built-in watchdog timer. This is a safety
mechanism that prevents \fBpostscreen\fR(8) from becoming non-responsive
due to a bug in Postfix itself or in system software. To avoid
This feature is available in Postfix 2.8.
.SH postscreen_whitelist_interfaces (default: static:all)
A list of local \fBpostscreen\fR(8) server IP addresses where a
-non-whitelisted SMTP client can obtain \fBpostscreen\fR(8)'s temporary
+non-whitelisted remote SMTP client can obtain \fBpostscreen\fR(8)'s temporary
whitelist status. This status is required before the client can
talk to a Postfix SMTP server process. By default, a client can
obtain \fBpostscreen\fR(8)'s whitelist status on any local \fBpostscreen\fR(8)
_recipient_limit) if necessary. The minimum value allowed for this
parameter is 1.
.SH qmqpd_authorized_clients (default: empty)
-What clients are allowed to connect to the QMQP server port.
+What remote QMQP clients are allowed to connect to the Postfix QMQP
+server port.
.PP
By default, no client is allowed to use the service. This is
because the QMQP server will relay mail to any destination.
.PP
This feature is available in Postfix 2.5 and later.
.SH qmqpd_error_delay (default: 1s)
-How long the QMQP server will pause before sending a negative reply
-to the client. The purpose is to slow down confused or malicious
-clients.
+How long the Postfix QMQP server will pause before sending a negative
+reply to the remote QMQP client. The purpose is to slow down confused
+or malicious clients.
.PP
Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
The default time unit is s (seconds).
.SH qmqpd_timeout (default: 300s)
The time limit for sending or receiving information over the network.
If a read or write operation blocks for more than $qmqpd_timeout
-seconds the QMQP server gives up and disconnects.
+seconds the Postfix QMQP server gives up and disconnects.
.PP
Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
The default time unit is s (seconds).
This feature is available in Postfix 2.0 and later.
.SH queue_minfree (default: 0)
The minimal amount of free space in bytes in the queue file system
-that is needed to receive mail. This is currently used by the SMTP
-server to decide if it will accept any mail at all.
+that is needed to receive mail. This is currently used by the
+Postfix SMTP server to decide if it will accept any mail at all.
.PP
By default, the Postfix SMTP server rejects MAIL FROM commands when
the amount of free space is less than 1.5*$message_size_limit
.PP
This feature is available in Postfix 2.6 and later.
.SH relay_clientcerts (default: empty)
-List of tables with remote SMTP client-certificate fingerprints
-for which the Postfix SMTP server will allow access with the
-permit_tls_clientcerts feature.
-The fingerprint digest algorithm is configurable via the
+List of tables with remote SMTP client-certificate fingerprints or
+public key fingerprints (Postfix 2.9 and later) for which the Postfix
+SMTP server will allow access with the permit_tls_clientcerts
+feature. The fingerprint digest algorithm is configurable via the
smtpd_tls_fingerprint_digest parameter (hard-coded as md5 prior to
Postfix version 2.5).
.PP
.SH smtp_always_send_ehlo (default: yes)
Always send EHLO at the start of an SMTP session.
.PP
-With "smtp_always_send_ehlo = no", Postfix sends EHLO only when
+With "smtp_always_send_ehlo = no", the Postfix SMTP client sends
+EHLO only when
the word "ESMTP" appears in the server greeting banner (example:
220 spike.porcupine.org ESMTP Postfix).
.SH smtp_bind_address (default: empty)
.PP
This feature is available in Postfix 2.2.9 and later.
.SH smtp_connect_timeout (default: 30s)
-The SMTP client time limit for completing a TCP connection, or
+The Postfix SMTP client time limit for completing a TCP connection, or
zero (use the operating system built-in time limit).
.PP
When no connection can be made within the deadline, the Postfix
.PP
This feature is available in Postfix 2.3 and later.
.SH smtp_data_done_timeout (default: 600s)
-The SMTP client time limit for sending the SMTP ".", and for receiving
-the server response.
+The Postfix SMTP client time limit for sending the SMTP ".", and
+for receiving the remote SMTP server response.
.PP
When no response is received within the deadline, a warning is
logged that the mail may be delivered multiple times.
Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
The default time unit is s (seconds).
.SH smtp_data_init_timeout (default: 120s)
-The SMTP client time limit for sending the SMTP DATA command, and for
-receiving the server response.
+The Postfix SMTP client time limit for sending the SMTP DATA command,
+and for receiving the remote SMTP server response.
.PP
Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
The default time unit is s (seconds).
.SH smtp_data_xfer_timeout (default: 180s)
-The SMTP client time limit for sending the SMTP message content.
+The Postfix SMTP client time limit for sending the SMTP message content.
When the connection makes no progress for more than $smtp_data_xfer_timeout
seconds the Postfix SMTP client terminates the transfer.
.PP
Postfix versions the default was to keep trying to deliver the mail
until someone fixed the MX record or until the mail was too old.
.PP
-Note: Postfix always ignores MX records with equal or worse preference
+Note: the Postfix SMTP client always ignores MX records with equal
+or worse preference
than the local MTA itself.
.PP
This feature is available in Postfix 2.1 and later.
destinations that it is MX host for (assuming DNS lookup is turned on).
.SH smtp_generic_maps (default: empty)
Optional lookup tables that perform address rewriting in the
-SMTP client, typically to transform a locally valid address into
+Postfix SMTP client, typically to transform a locally valid address into
a globally valid address when sending mail across the Internet.
This is needed when the local machine does not have its own Internet
domain name, but uses something like \fIlocaldomain.local\fR
.PP
This feature is available in Postfix 2.0 and later.
.SH smtp_helo_timeout (default: 300s)
-The SMTP client time limit for sending the HELO or EHLO command,
-and for receiving the initial server response.
+The Postfix SMTP client time limit for sending the HELO or EHLO command,
+and for receiving the initial remote SMTP server response.
.PP
Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
The default time unit is s (seconds).
<CR><LF>. The Postfix limit was 990 with Postfix 2.8
and earlier.
.SH smtp_mail_timeout (default: 300s)
-The SMTP client time limit for sending the MAIL FROM command, and
-for receiving the server response.
+The Postfix SMTP client time limit for sending the MAIL FROM command,
+and for receiving the remote SMTP server response.
.PP
Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
The default time unit is s (seconds).
This feature is available in Postfix 2.5 and later.
.SH smtp_mx_address_limit (default: 5)
The maximal number of MX (mail exchanger) IP addresses that can
-result from mail exchanger lookups, or zero (no limit). Prior to
+result from Postfix SMTP client mail exchanger lookups, or zero (no
+limit). Prior to
Postfix version 2.3, this limit was disabled by default.
.PP
This feature is available in Postfix 2.1 and later.
.SH smtp_mx_session_limit (default: 2)
The maximal number of SMTP sessions per delivery request before
-giving up or delivering to a fall-back relay host, or zero (no
+the Postfix SMTP client
+gives up or delivers to a fall-back relay host, or zero (no
limit). This restriction ignores sessions that fail to complete the
SMTP initial handshake (Postfix version 2.2 and earlier) or that fail to
complete the EHLO and TLS handshake (Postfix version 2.3 and later).
This feature is available in Postfix 2.4 and later. The default
settings are backwards compatible with earlier Postfix versions.
.SH smtp_quit_timeout (default: 300s)
-The SMTP client time limit for sending the QUIT command, and for
-receiving the server response.
+The Postfix SMTP client time limit for sending the QUIT command,
+and for receiving the remote SMTP server response.
.PP
Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
The default time unit is s (seconds).
.SH smtp_quote_rfc821_envelope (default: yes)
-Quote addresses in SMTP MAIL FROM and RCPT TO commands as required
+Quote addresses in Postfix SMTP client MAIL FROM and RCPT TO commands
+as required
by RFC 2821. This includes putting quotes around an address localpart
that ends in ".".
.PP
Randomize the order of equal-preference MX host addresses. This
is a performance feature of the Postfix SMTP client.
.SH smtp_rcpt_timeout (default: 300s)
-The SMTP client time limit for sending the SMTP RCPT TO command, and
-for receiving the server response.
+The Postfix SMTP client time limit for sending the SMTP RCPT TO
+command, and for receiving the remote SMTP server response.
.PP
Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
The default time unit is s (seconds).
.PP
This feature is available in Postfix 2.7.
.SH smtp_rset_timeout (default: 20s)
-The SMTP client time limit for sending the RSET command, and
-for receiving the server response. The SMTP client sends RSET in
+The Postfix SMTP client time limit for sending the RSET command,
+and for receiving the remote SMTP server response. The SMTP client
+sends RSET in
order to finish a recipient address probe, or to verify that a
cached session is still usable.
.PP
.ad
.ft R
.SH smtp_sasl_password_maps (default: empty)
-Optional SMTP client lookup tables with one username:password entry
+Optional Postfix SMTP client lookup tables with one username:password
+entry
per remote hostname or domain, or sender address when sender-dependent
authentication is enabled. If no username:password entry is found,
then the Postfix SMTP client will not
Send the non-standard XFORWARD command when the Postfix SMTP server
EHLO response announces XFORWARD support.
.PP
-This allows an "smtp" delivery agent, used for injecting mail into
+This allows a Postfix SMTP delivery agent, used for injecting mail
+into
a content filter, to forward the name, address, protocol and HELO
name of the original client to the content filter and downstream
queuing SMTP server. This can produce more useful logging than
Skip SMTP servers that greet with a 4XX status code (go away, try
again later).
.PP
-By default, Postfix moves on the next mail exchanger. Specify
+By default, the Postfix SMTP client moves on the next mail exchanger.
+Specify
"smtp_skip_4xx_greeting = no" if Postfix should defer delivery
immediately.
.PP
This feature is available in Postfix 2.0 and earlier.
-Later Postfix versions always skip SMTP servers that greet with a
+Later Postfix versions always skip remote SMTP servers that greet
+with a
4XX status code.
.SH smtp_skip_5xx_greeting (default: yes)
-Skip SMTP servers that greet with a 5XX status code (go away, do
+Skip remote SMTP servers that greet with a 5XX status code (go away,
+do
not try again later).
.PP
By default, the Postfix SMTP client moves on the next mail
.PP
This feature is available in Postfix 2.3 and later.
.SH smtp_tls_fingerprint_cert_match (default: empty)
-List of acceptable remote SMTP server certificate fingerprints
-for the "fingerprint" TLS security level (\fBsmtp_tls_security_level\fR =
-fingerprint). At this security level, certificate authorities are
-not used, and certificate expiration times are ignored. Instead,
-server certificates are verified directly via their "fingerprint". The
-fingerprint is a message digest of the server certificate. The digest
-algorithm is selected via the \fBsmtp_tls_fingerprint_digest\fR
+List of acceptable remote SMTP server certificate fingerprints for
+the "fingerprint" TLS security level (\fBsmtp_tls_security_level\fR =
+fingerprint). At this security level, certificate authorities are not
+used, and certificate expiration times are ignored. Instead, server
+certificates are verified directly via their certificate fingerprint
+or public key fingerprint (Postfix 2.9 and later). The fingerprint
+is a message digest of the server certificate (or public key). The
+digest algorithm is selected via the \fBsmtp_tls_fingerprint_digest\fR
parameter.
.PP
When an \fBsmtp_tls_policy_maps\fR table entry specifies the
The message digest algorithm used to construct remote SMTP server
certificate fingerprints. At the "fingerprint" TLS security level
(\fBsmtp_tls_security_level\fR = fingerprint), the server certificate is
-verified by directly matching its \fIfingerprint\fR. The fingerprint
-is the message digest of the server certificate using the selected
+verified by directly matching its certificate fingerprint or its public
+key fingerprint (Postfix 2.9 and later). The fingerprint is the
+message digest of the server certificate (or its public key)
+using the selected
algorithm. With a digest algorithm resistant to "second pre-image"
attacks, it is not feasible to create a new public key and a matching
-certificate that has the same fingerprint.
+certificate (or public/private key-pair) that has the same fingerprint.
.PP
The default algorithm is \fBmd5\fR; this is consistent with
the backwards compatible setting of the digest used to verify client
.ft R
.in -4
.PP
+Public key fingerprints are more difficult to extract, however,
+the SHA-1 public key fingerprint is often present as the value of the
+"Subject Key Identifier" extension in X.509v3 certificates. The Postfix
+SMTP server and client log the peer certificate fingerprint and public
+key fingerprint when TLS loglevel is 1 or higher.
+.PP
This feature is available in Postfix 2.5 and later.
.SH smtp_tls_key_file (default: $smtp_tls_cert_file)
File with the Postfix SMTP client RSA private key in PEM format.
Each logging level also includes the information that is logged at
a lower logging level.
.IP ""
-0 Disable logging of TLS activity.
+0 Log only a summary message on TLS handshake completion
+— no logging of remote SMTP server certificate trust-chain
+verification errors if server certificate verification is not required.
+With Postfix 2.8 and earlier, disable logging of TLS activity.
.IP ""
-1 Log TLS handshake and certificate information.
+1 Also log remote SMTP server trust-chain verification
+errors and peer certificate summary information. With Postfix 2.8
+and earlier, log TLS handshake and certificate information.
.IP ""
-2 Log levels during TLS negotiation.
+2 Also log levels during TLS negotiation.
.IP ""
-3 Log hexadecimal and ASCII dump of TLS negotiation
+3 Also log hexadecimal and ASCII dump of TLS negotiation
process.
.IP ""
-4 Log hexadecimal and ASCII dump of complete
+4 Also log hexadecimal and ASCII dump of complete
transmission after STARTTLS.
.PP
-Use "smtp_tls_loglevel = 3" only in case of problems. Use of
-loglevel 4 is strongly discouraged.
+Do not use "smtp_tls_loglevel = 2" or higher except in case of
+problems. Use of loglevel 4 is strongly discouraged.
.PP
This feature is available in Postfix 2.2 and later.
.SH smtp_tls_mandatory_ciphers (default: medium)
This feature is available in Postfix 2.3 and later.
.SH smtp_tls_mandatory_exclude_ciphers (default: empty)
Additional list of ciphers or cipher types to exclude from the
-SMTP client cipher list at mandatory TLS security levels. This list
+Postfix SMTP client cipher list at mandatory TLS security levels. This list
works in addition to the exclusions listed with smtp_tls_exclude_ciphers
(see there for syntax details).
.PP
level, there are no trusted certificate authorities. The certificate
trust chain, expiration date, ... are not checked. Instead,
the optional \fBmatch\fR attribute, or else the main.cf
-\fBsmtp_tls_fingerprint_cert_match\fR parameter, lists the
-valid "fingerprints" of the server certificate. The digest
+\fBsmtp_tls_fingerprint_cert_match\fR parameter, lists the certificate
+fingerprints or the public key fingerprint (Postfix 2.9 and later)
+of the valid server certificate. The digest
algorithm used to calculate the fingerprint is selected by the
\fBsmtp_tls_fingerprint_digest\fR parameter. Multiple fingerprints can
be combined with a "|" delimiter in a single match attribute, or multiple
.PP
This feature is available in Postfix 2.2 and later.
.SH smtp_tls_secure_cert_match (default: nexthop, dot-nexthop)
-The server certificate peername verification method for the
+How the Postfix SMTP client verifies the server certificate
+peername for the
"secure" TLS security level. In a "secure" TLS policy table
($smtp_tls_policy_maps) entry the optional "match" attribute
overrides this main.cf setting.
Certificate fingerprint
verification. Available with Postfix 2.5 and later. At this security
level, there are no trusted certificate authorities. The certificate
-trust chain, expiration date, ... are not checked. Instead,
-the \fBsmtp_tls_fingerprint_cert_match\fR parameter lists
-the valid "fingerprints" of the server certificate. The digest
+trust chain, expiration date, ... are not checked. Instead, the
+\fBsmtp_tls_fingerprint_cert_match\fR parameter lists the certificate
+fingerprint or public key fingerprint (Postfix 2.9 and later) of
+the valid server certificate. The digest
algorithm used to calculate the fingerprint is selected by the
\fBsmtp_tls_fingerprint_digest\fR parameter.
.IP "\fBverify\fR"
.PP
This feature is available in Postfix 2.2 and later.
.SH smtp_tls_verify_cert_match (default: hostname)
-The server certificate peername verification method for the
+How the Postfix SMTP client verifies the server certificate
+peername for the
"verify" TLS security level. In a "verify" TLS policy table
($smtp_tls_policy_maps) entry the optional "match" attribute
overrides this main.cf setting.
This feature is available in Postfix 2.2 and later. With
Postfix 2.3 and later use smtp_tls_security_level instead.
.SH smtp_xforward_timeout (default: 300s)
-The SMTP client time limit for sending the XFORWARD command, and
-for receiving the server response.
+The Postfix SMTP client time limit for sending the XFORWARD command,
+and for receiving the remote SMTP server response.
.PP
Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
The default time unit is s (seconds).
.PP
This feature is available in Postfix 2.1 and later.
.SH smtpd_authorized_verp_clients (default: $authorized_verp_clients)
-What SMTP clients are allowed to specify the XVERP command.
+What remote SMTP clients are allowed to specify the XVERP command.
This command requests that mail be delivered one recipient at a
time with a per recipient return address.
.PP
the ":" character, and would otherwise be confused with a "type:table"
pattern.
.SH smtpd_authorized_xclient_hosts (default: empty)
-What SMTP clients are allowed to use the XCLIENT feature. This
-command overrides SMTP client information that is used for access
+What remote SMTP clients are allowed to use the XCLIENT feature. This
+command overrides remote SMTP client information that is used for access
control. Typical use is for SMTP-based content filters, fetchmail-like
programs, or SMTP server access rule testing. See the XCLIENT_README
document for details.
the ":" character, and would otherwise be confused with a "type:table"
pattern.
.SH smtpd_authorized_xforward_hosts (default: empty)
-What SMTP clients are allowed to use the XFORWARD feature. This
+What remote SMTP clients are allowed to use the XFORWARD feature. This
command forwards information that is used to improve logging after
SMTP-based content filters. See the XFORWARD_README document for
details.
.ad
.ft R
.SH smtpd_client_restrictions (default: empty)
-Optional SMTP server access restrictions in the context of a client
-SMTP connection request.
+Optional Postfix SMTP server access restrictions in the context of
+a remote SMTP client connection request.
See SMTPD_ACCESS_README, section "Delayed evaluation of SMTP access
restriction lists" for a discussion of evaluation context and time.
.PP
The following restrictions are specific to client hostname or
client network address information.
.IP "\fBcheck_ccert_access \fItype:table\fR\fR"
-Use the client certificate fingerprint as lookup key for the
-specified \fBaccess\fR(5) database; with Postfix version 2.2, also require that
-the SMTP client certificate is verified successfully.
+Use the remote SMTP client certificate fingerprint or the public key
+fingerprint (Postfix 2.9 and later) as lookup key for the specified
+\fBaccess\fR(5) database; with Postfix version 2.2, also require that the
+remote SMTP client certificate is verified successfully.
The fingerprint digest algorithm is configurable via the
smtpd_tls_fingerprint_digest parameter (hard-coded as md5 prior to
Postfix version 2.5). This feature is available with Postfix version
This feature is available with Postfix version 2.2.
.IP "\fBpermit_tls_clientcerts\fR"
Permit the request when the remote SMTP client certificate
-fingerprint is listed in $relay_clientcerts.
+fingerprint or public key fingerprint (Postfix 2.9 and later) is
+listed in $relay_clientcerts.
The fingerprint digest algorithm is configurable via the
smtpd_tls_fingerprint_digest parameter (hard-coded as md5 prior to
Postfix version 2.5). This feature is available with Postfix version
.SH smtpd_delay_open_until_valid_rcpt (default: yes)
Postpone the start of an SMTP mail transaction until a valid
RCPT TO command is received. Specify "no" to create a mail transaction
-as soon as the SMTP server receives a valid MAIL FROM command.
+as soon as the Postfix SMTP server receives a valid MAIL FROM
+command.
.PP
With sites that reject lots of mail, the default setting reduces
the use of
.SH smtpd_discard_ehlo_keyword_address_maps (default: empty)
Lookup tables, indexed by the remote SMTP client address, with
case insensitive lists of EHLO keywords (pipelining, starttls, auth,
-etc.) that the SMTP server will not send in the EHLO response to a
+etc.) that the Postfix SMTP server will not send in the EHLO response
+to a
remote SMTP client. See smtpd_discard_ehlo_keywords for details.
The table is not searched by hostname for robustness reasons.
.PP
This feature is available in Postfix 2.2 and later.
.SH smtpd_discard_ehlo_keywords (default: empty)
A case insensitive list of EHLO keywords (pipelining, starttls,
-auth, etc.) that the SMTP server will not send in the EHLO response
+auth, etc.) that the Postfix SMTP server will not send in the EHLO
+response
to a remote SMTP client.
.PP
This feature is available in Postfix 2.2 and later.
.PP
See smtpd_data_restrictions for details and limitations.
.SH smtpd_enforce_tls (default: no)
-Mandatory TLS: announce STARTTLS support to SMTP clients,
+Mandatory TLS: announce STARTTLS support to remote SMTP clients,
and require that clients use TLS encryption. According to RFC 2487
this MUST NOT be applied in case of a publicly-referenced SMTP
server. This option is therefore off by default.
.ad
.ft R
.SH smtpd_reject_footer (default: empty)
-Optional information that is appended after each SMTP server
+Optional information that is appended after each Postfix SMTP
+server
4XX or 5XX response.
.PP
Example:
.PP
With Postfix 2.3 and later the Postfix SMTP server can disable
session id generation when TLS session caching is turned off. This
-keeps clients from caching sessions that almost certainly cannot
+keeps remote SMTP clients from caching sessions that almost certainly cannot
be re-used.
.PP
By default, the Postfix SMTP server always generates TLS session
.PP
This feature is available in Postfix 2.3 and later.
.SH smtpd_tls_fingerprint_digest (default: md5)
-The message digest algorithm used to construct client-certificate
-fingerprints for \fBcheck_ccert_access\fR and
-\fBpermit_tls_clientcerts\fR. The default algorithm is \fBmd5\fR,
-for backwards compatibility with Postfix releases prior to 2.5.
+The message digest algorithm to construct remote SMTP
+client-certificate
+fingerprints or public key fingerprints (Postfix 2.9 and later)
+for \fBcheck_ccert_access\fR and \fBpermit_tls_clientcerts\fR. The
+default algorithm is \fBmd5\fR, for backwards compatibility with Postfix
+releases prior to 2.5.
.PP
Advances in hash
function cryptanalysis have led to md5 being deprecated in favor of sha1.
.ft R
.in -4
.PP
+Public key fingerprints are more difficult to extract, however,
+the SHA-1 public key fingerprint is often present as the value of the
+"Subject Key Identifier" extension in X.509v3 certificates. The Postfix
+SMTP server and client log the peer certificate fingerprint and public
+key fingerprint when TLS loglevel is 1 or higher.
+.PP
Example: client-certificate access table, with sha1 fingerprints:
.sp
.in +4
Each logging level also includes the information that is logged at
a lower logging level.
.IP ""
-0 Disable logging of TLS activity.
+0 Log only a summary message on TLS handshake completion
+— no logging of remote SMTP client certificate trust-chain verification
+errors
+if client certificate verification is not required. With Postfix 2.8
+and earlier, disable logging of TLS activity.
.IP ""
-1 Log TLS handshake and certificate information.
+1 Also log trust-chain verification errors and peer
+certificate name and issuer. With Postfix 2.8 and earlier, log TLS
+handshake and certificate information.
.IP ""
-2 Log levels during TLS negotiation.
+2 Also log levels during TLS negotiation.
.IP ""
-3 Log hexadecimal and ASCII dump of TLS negotiation
+3 Also log hexadecimal and ASCII dump of TLS negotiation
process.
.IP ""
4 Also log hexadecimal and ASCII dump of complete
transmission after STARTTLS.
.PP
-Use "smtpd_tls_loglevel = 3" only in case of problems. Use of
-loglevel 4 is strongly discouraged.
+Do not use "smtpd_tls_loglevel = 2" or higher except in case
+of problems. Use of loglevel 4 is strongly discouraged.
.PP
This feature is available in Postfix 2.2 and later.
.SH smtpd_tls_mandatory_ciphers (default: medium)
.PP
The underlying cipherlists for grades other than "null" include
anonymous ciphers, but these are automatically filtered out if the
-server is configured to ask for client certificates. You are very
+server is configured to ask for remote SMTP client certificates. You are very
unlikely to need to take any steps to exclude anonymous ciphers, they
are excluded automatically as required. If you must exclude anonymous
ciphers even when Postfix does not need or use peer certificates, set
This feature is available in Postfix 2.3 and later.
.SH smtpd_tls_mandatory_exclude_ciphers (default: empty)
Additional list of ciphers or cipher types to exclude from the
-SMTP server cipher list at mandatory TLS security levels. This list
+Postfix SMTP server cipher list at mandatory TLS security levels.
+This list
works in addition to the exclusions listed with smtpd_tls_exclude_ciphers
(see there for syntax details).
.PP
.SH smtpd_tls_received_header (default: no)
Request that the Postfix SMTP server produces Received: message
headers that include information about the protocol and cipher used,
-as well as the client CommonName and client certificate issuer
+as well as the remote SMTP client CommonName and client certificate issuer
CommonName. This is disabled by default, as the information may
be modified in transit through other mail servers. Only information
that was recorded by the final destination can be trusted.
TLS will not be used.
.IP "\fBmay\fR"
Opportunistic TLS: announce STARTTLS support
-to SMTP clients, but do not require that clients use TLS encryption.
+to remote SMTP clients, but do not require that clients use TLS encryption.
.IP "\fBencrypt\fR"
Mandatory TLS encryption: announce
-STARTTLS support to SMTP clients, and require that clients use TLS
+STARTTLS support to remote SMTP clients, and require that clients use TLS
encryption. According to RFC 2487 this MUST NOT be applied in case
of a publicly-referenced SMTP server. Instead, this option should
be used only on dedicated servers.
Note 1: the "fingerprint", "verify" and "secure" levels are not
supported here.
The Postfix SMTP server logs a warning and uses "encrypt" instead.
-To verify SMTP client certificates, see TLS_README for a discussion
+To verify remote SMTP client certificates, see TLS_README for a discussion
of the smtpd_tls_ask_ccert, smtpd_tls_req_ccert, and permit_tls_clientcerts
features.
.PP
.PP
This feature is available in Postfix 2.2 and later.
.SH smtpd_use_tls (default: no)
-Opportunistic TLS: announce STARTTLS support to SMTP clients,
+Opportunistic TLS: announce STARTTLS support to remote SMTP clients,
but do not require that clients use TLS encryption.
.PP
Note: when invoked via "\fBsendmail -bs\fR", Postfix will never offer
.PP
This feature is available in Postfix 2.8 and later.
.SH tls_eecdh_strong_curve (default: prime256v1)
-The elliptic curve used by the SMTP server for sensibly strong
+The elliptic curve used by the Postfix SMTP server for sensibly
+strong
ephemeral ECDH key exchange. This curve is used by the Postfix SMTP
server when "smtpd_tls_eecdh_grade = strong". The phrase "sensibly
strong" means approximately 128-bit security based on best known
This feature is available in Postfix 2.6 and later, when it is
compiled and linked with OpenSSL 1.0.0 or later.
.SH tls_eecdh_ultra_curve (default: secp384r1)
-The elliptic curve used by the SMTP server for maximally strong
+The elliptic curve used by the Postfix SMTP server for maximally
+strong
ephemeral ECDH key exchange. This curve is used by the Postfix SMTP
server when "smtpd_tls_eecdh_grade = ultra". The phrase "maximally
strong" means approximately 192-bit security based on best known attacks.
.PP
This feature is available in Postfix 2.3 and later.
.SH tls_preempt_cipherlist (default: no)
-With SSLv3 and later, use the server's cipher preference order
-instead of the client's cipher preference order.
+With SSLv3 and later, use the Postfix SMTP server's cipher
+preference order instead of the remote client's cipher preference
+order.
.PP
By default, the OpenSSL server selects the client's most preferred
cipher that the server supports. With SSLv3 and later, the server may
.PP
This feature is available in Postfix 2.2 and later.
.SH tlsproxy_enforce_tls (default: $smtpd_enforce_tls)
-Mandatory TLS: announce STARTTLS support to SMTP clients, and
+Mandatory TLS: announce STARTTLS support to remote SMTP clients, and
require that clients use TLS encryption. See smtpd_enforce_tls for
further details.
.PP
.PP
This feature is available in Postfix 2.8 and later.
.SH tlsproxy_tls_fingerprint_digest (default: $smtpd_tls_fingerprint_digest)
-The message digest algorithm used to construct client-certificate
+The message digest algorithm to construct remote SMTP
+client-certificate
fingerprints. See smtpd_tls_fingerprint_digest for further details.
.PP
This feature is available in Postfix 2.8 and later.
.PP
This feature is available in Postfix 2.8 and later.
.SH tlsproxy_use_tls (default: $smtpd_use_tls)
-Opportunistic TLS: announce STARTTLS support to SMTP clients,
+Opportunistic TLS: announce STARTTLS support to remote SMTP clients,
but do not require that clients use TLS encryption. See smtpd_use_tls
for further details.
.PP
.PP
This feature is available in Postfix 2.0 and later.
.SH unknown_virtual_alias_reject_code (default: 550)
-The SMTP server reply code when a recipient address matches
+The Postfix SMTP server reply code when a recipient address matches
$virtual_alias_domains, and $virtual_alias_maps specifies a list
of lookup tables that does not match the recipient address.
.PP
This feature is available in Postfix 2.0 and later.
.SH unknown_virtual_mailbox_reject_code (default: 550)
-The SMTP server reply code when a recipient address matches
+The Postfix SMTP server reply code when a recipient address matches
$virtual_mailbox_domains, and $virtual_mailbox_maps specifies a list
of lookup tables that does not match the recipient address.
.PP
List of characters that are permitted in postscreen_reject_footer
attribute expansions.
.IP "\fBpostscreen_reject_footer ($smtpd_reject_footer)\fR"
-Optional information that is appended after a 4XX or 5XX server
+Optional information that is appended after a 4XX or 5XX
+\fBpostscreen\fR(8) server
response.
.IP "\fBsoft_bounce (no)\fR"
Safety net to keep mail queued that would otherwise be returned to
.IP "\fBpostscreen_access_list (permit_mynetworks)\fR"
Permanent white/blacklist for remote SMTP client IP addresses.
.IP "\fBpostscreen_blacklist_action (ignore)\fR"
-The action that \fBpostscreen\fR(8) takes when an SMTP client is
+The action that \fBpostscreen\fR(8) takes when a remote SMTP client is
permanently blacklisted with the postscreen_access_list parameter.
.SH "MAIL EXCHANGER POLICY TESTS"
.na
to clients that connect only to backup MX hosts.
.IP "\fBpostscreen_whitelist_interfaces (static:all)\fR"
A list of local \fBpostscreen\fR(8) server IP addresses where a
-non-whitelisted SMTP client can obtain \fBpostscreen\fR(8)'s temporary
-whitelist status to talk to a Postfix SMTP server process.
+non-whitelisted remote SMTP client can obtain \fBpostscreen\fR(8)'s temporary
+whitelist status.
.SH "BEFORE-GREETING TESTS"
.na
.nf
.IP "\fBdnsblog_service_name (dnsblog)\fR"
The name of the \fBdnsblog\fR(8) service entry in master.cf.
.IP "\fBpostscreen_dnsbl_action (ignore)\fR"
-The action that \fBpostscreen\fR(8) takes when an SMTP client's combined
+The action that \fBpostscreen\fR(8) takes when a remote SMTP client's combined
DNSBL score is equal to or greater than a threshold (as defined
with the postscreen_dnsbl_sites and postscreen_dnsbl_threshold
parameters).
Optional list of DNS white/blacklist domains, filters and weight
factors.
.IP "\fBpostscreen_dnsbl_threshold (1)\fR"
-The inclusive lower bound for blocking an SMTP client, based on
+The inclusive lower bound for blocking a remote SMTP client, based on
its combined DNSBL score as defined with the postscreen_dnsbl_sites
parameter.
.IP "\fBpostscreen_greet_action (ignore)\fR"
-The action that \fBpostscreen\fR(8) takes when an SMTP client speaks
+The action that \fBpostscreen\fR(8) takes when a remote SMTP client speaks
before its turn within the time specified with the postscreen_greet_wait
parameter.
.IP "\fBpostscreen_greet_banner ($smtpd_banner)\fR"
the client will be allowed to talk directly to a Postfix
SMTP server process.
.IP "\fBpostscreen_bare_newline_action (ignore)\fR"
-The action that \fBpostscreen\fR(8) takes when an SMTP client sends
+The action that \fBpostscreen\fR(8) takes when a remote SMTP client sends
a bare newline character, that is, a newline not preceded by carriage
return.
.IP "\fBpostscreen_bare_newline_enable (no)\fR"
Require that a remote SMTP client sends HELO or EHLO before
commencing a MAIL transaction.
.IP "\fBpostscreen_non_smtp_command_action (drop)\fR"
-The action that \fBpostscreen\fR(8) takes when an SMTP client sends
+The action that \fBpostscreen\fR(8) takes when a remote SMTP client sends
non-SMTP commands as specified with the postscreen_forbidden_commands
parameter.
.IP "\fBpostscreen_non_smtp_command_enable (no)\fR"
Enable "non-SMTP command" tests in the \fBpostscreen\fR(8) server.
.IP "\fBpostscreen_pipelining_action (enforce)\fR"
-The action that \fBpostscreen\fR(8) takes when an SMTP client sends
+The action that \fBpostscreen\fR(8) takes when a remote SMTP client
+sends
multiple commands instead of sending one command and waiting for
the server to respond.
.IP "\fBpostscreen_pipelining_enable (no)\fR"
Upon input, long lines are chopped up into pieces of at most
this length; upon delivery, long lines are reconstructed.
.IP "\fBpostscreen_client_connection_count_limit ($smtpd_client_connection_count_limit)\fR"
-How many simultaneous connections any client is allowed to have
+How many simultaneous connections any remote SMTP client is
+allowed to have
with the \fBpostscreen\fR(8) daemon.
.IP "\fBpostscreen_command_count_limit (20)\fR"
The limit on the total number of commands per SMTP session for
built-in SMTP protocol engine.
.IP "\fBpostscreen_post_queue_limit ($default_process_limit)\fR"
The number of clients that can be waiting for service from a
-real SMTP server process.
+real Postfix SMTP server process.
.IP "\fBpostscreen_pre_queue_limit ($default_process_limit)\fR"
The number of non-whitelisted clients that can be waiting for
-a decision whether they will receive service from a real SMTP server
+a decision whether they will receive service from a real Postfix
+SMTP server
process.
.IP "\fBpostscreen_watchdog_timeout (10s)\fR"
How much time a \fBpostscreen\fR(8) process may take to respond to
-an SMTP client command or to perform a cache operation before it
+a remote SMTP client command or to perform a cache operation before it
is terminated by a built-in watchdog timer.
.SH "STARTTLS CONTROLS"
.na
These parameters are supported for compatibility with
\fBsmtpd\fR(8) legacy parameters.
.IP "\fBpostscreen_use_tls ($smtpd_use_tls)\fR"
-Opportunistic TLS: announce STARTTLS support to SMTP clients,
+Opportunistic TLS: announce STARTTLS support to remote SMTP clients,
but do not require that clients use TLS encryption.
.IP "\fBpostscreen_enforce_tls ($smtpd_enforce_tls)\fR"
-Mandatory TLS: announce STARTTLS support to SMTP clients, and
+Mandatory TLS: announce STARTTLS support to remote SMTP clients, and
require that clients use TLS encryption.
.SH "MISCELLANEOUS CONTROLS"
.na
Lookup tables, indexed by the remote SMTP server address, with
per-destination workarounds for CISCO PIX firewall bugs.
.IP "\fBsmtp_quote_rfc821_envelope (yes)\fR"
-Quote addresses in SMTP MAIL FROM and RCPT TO commands as required
+Quote addresses in Postfix SMTP client MAIL FROM and RCPT TO commands
+as required
by RFC 2821.
.IP "\fBsmtp_reply_filter (empty)\fR"
A mechanism to transform replies from remote SMTP servers one
line at a time.
.IP "\fBsmtp_skip_5xx_greeting (yes)\fR"
-Skip SMTP servers that greet with a 5XX status code (go away, do
+Skip remote SMTP servers that greet with a 5XX status code (go away,
+do
not try again later).
.IP "\fBsmtp_skip_quit_response (yes)\fR"
Do not wait for the response to the SMTP QUIT command.
response from a remote SMTP server.
.IP "\fBsmtp_generic_maps (empty)\fR"
Optional lookup tables that perform address rewriting in the
-SMTP client, typically to transform a locally valid address into
+Postfix SMTP client, typically to transform a locally valid address into
a globally valid address when sending mail across the Internet.
.PP
Available in Postfix version 2.2.9 and later:
.IP "\fBlmtp_discard_lhlo_keyword_address_maps (empty)\fR"
Lookup tables, indexed by the remote LMTP server address, with
case insensitive lists of LHLO keywords (pipelining, starttls,
-auth, etc.) that the LMTP client will ignore in the LHLO response
+auth, etc.) that the Postfix LMTP client will ignore in the LHLO
+response
from a remote LMTP server.
.IP "\fBlmtp_discard_lhlo_keywords (empty)\fR"
A case insensitive list of LHLO keywords (pipelining, starttls,
-auth, etc.) that the LMTP client will ignore in the LHLO response
+auth, etc.) that the Postfix LMTP client will ignore in the LHLO
+response
from a remote LMTP server.
.PP
Available in Postfix version 2.4.4 and later:
.IP "\fBsmtp_sasl_auth_enable (no)\fR"
Enable SASL authentication in the Postfix SMTP client.
.IP "\fBsmtp_sasl_password_maps (empty)\fR"
-Optional SMTP client lookup tables with one username:password entry
+Optional Postfix SMTP client lookup tables with one username:password
+entry
per remote hostname or domain, or sender address when sender-dependent
authentication is enabled.
.IP "\fBsmtp_sasl_security_options (noplaintext, noanonymous)\fR"
list at all TLS security levels.
.IP "\fBsmtp_tls_mandatory_exclude_ciphers (empty)\fR"
Additional list of ciphers or cipher types to exclude from the
-SMTP client cipher list at mandatory TLS security levels.
+Postfix SMTP client cipher list at mandatory TLS security levels.
.IP "\fBsmtp_tls_dcert_file (empty)\fR"
File with the Postfix SMTP client DSA certificate in PEM format.
.IP "\fBsmtp_tls_dkey_file ($smtp_tls_dcert_file)\fR"
.IP "\fBsmtp_tls_scert_verifydepth (9)\fR"
The verification depth for remote SMTP server certificates.
.IP "\fBsmtp_tls_secure_cert_match (nexthop, dot-nexthop)\fR"
-The server certificate peername verification method for the
+How the Postfix SMTP client verifies the server certificate
+peername for the
"secure" TLS security level.
.IP "\fBsmtp_tls_session_cache_database (empty)\fR"
Name of the file containing the optional Postfix SMTP client
The expiration time of Postfix SMTP client TLS session cache
information.
.IP "\fBsmtp_tls_verify_cert_match (hostname)\fR"
-The server certificate peername verification method for the
+How the Postfix SMTP client verifies the server certificate
+peername for the
"verify" TLS security level.
.IP "\fBtls_daemon_random_bytes (32)\fR"
The number of pseudo-random bytes that an \fBsmtp\fR(8) or \fBsmtpd\fR(8)
.PP
Available in Postfix version 2.5 and later:
.IP "\fBsmtp_tls_fingerprint_cert_match (empty)\fR"
-List of acceptable remote SMTP server certificate fingerprints
-for the "fingerprint" TLS security level (\fBsmtp_tls_security_level\fR =
+List of acceptable remote SMTP server certificate fingerprints for
+the "fingerprint" TLS security level (\fBsmtp_tls_security_level\fR =
fingerprint).
.IP "\fBsmtp_tls_fingerprint_digest (md5)\fR"
The message digest algorithm used to construct remote SMTP server
The maximal number of recipients per message for the smtp
message delivery transport.
.IP "\fBsmtp_connect_timeout (30s)\fR"
-The SMTP client time limit for completing a TCP connection, or
+The Postfix SMTP client time limit for completing a TCP connection, or
zero (use the operating system built-in time limit).
.IP "\fBsmtp_helo_timeout (300s)\fR"
-The SMTP client time limit for sending the HELO or EHLO command,
-and for receiving the initial server response.
+The Postfix SMTP client time limit for sending the HELO or EHLO command,
+and for receiving the initial remote SMTP server response.
.IP "\fBlmtp_lhlo_timeout (300s)\fR"
-The LMTP client time limit for sending the LHLO command, and
-for receiving the initial server response.
+The Postfix LMTP client time limit for sending the LHLO command,
+and for receiving the initial remote LMTP server response.
.IP "\fBsmtp_xforward_timeout (300s)\fR"
-The SMTP client time limit for sending the XFORWARD command, and
-for receiving the server response.
+The Postfix SMTP client time limit for sending the XFORWARD command,
+and for receiving the remote SMTP server response.
.IP "\fBsmtp_mail_timeout (300s)\fR"
-The SMTP client time limit for sending the MAIL FROM command, and
-for receiving the server response.
+The Postfix SMTP client time limit for sending the MAIL FROM command,
+and for receiving the remote SMTP server response.
.IP "\fBsmtp_rcpt_timeout (300s)\fR"
-The SMTP client time limit for sending the SMTP RCPT TO command, and
-for receiving the server response.
+The Postfix SMTP client time limit for sending the SMTP RCPT TO
+command, and for receiving the remote SMTP server response.
.IP "\fBsmtp_data_init_timeout (120s)\fR"
-The SMTP client time limit for sending the SMTP DATA command, and for
-receiving the server response.
+The Postfix SMTP client time limit for sending the SMTP DATA command,
+and for receiving the remote SMTP server response.
.IP "\fBsmtp_data_xfer_timeout (180s)\fR"
-The SMTP client time limit for sending the SMTP message content.
+The Postfix SMTP client time limit for sending the SMTP message content.
.IP "\fBsmtp_data_done_timeout (600s)\fR"
-The SMTP client time limit for sending the SMTP ".", and for receiving
-the server response.
+The Postfix SMTP client time limit for sending the SMTP ".", and
+for receiving the remote SMTP server response.
.IP "\fBsmtp_quit_timeout (300s)\fR"
-The SMTP client time limit for sending the QUIT command, and for
-receiving the server response.
+The Postfix SMTP client time limit for sending the QUIT command,
+and for receiving the remote SMTP server response.
.PP
Available in Postfix version 2.1 and later:
.IP "\fBsmtp_mx_address_limit (5)\fR"
The maximal number of MX (mail exchanger) IP addresses that can
-result from mail exchanger lookups, or zero (no limit).
+result from Postfix SMTP client mail exchanger lookups, or zero (no
+limit).
.IP "\fBsmtp_mx_session_limit (2)\fR"
The maximal number of SMTP sessions per delivery request before
-giving up or delivering to a fall-back relay host, or zero (no
+the Postfix SMTP client
+gives up or delivers to a fall-back relay host, or zero (no
limit).
.IP "\fBsmtp_rset_timeout (20s)\fR"
-The SMTP client time limit for sending the RSET command, and
-for receiving the server response.
+The Postfix SMTP client time limit for sending the RSET command,
+and for receiving the remote SMTP server response.
.PP
Available in Postfix version 2.2 and earlier:
.IP "\fBlmtp_cache_connection (yes)\fR"
The time limit for sending or receiving information over an internal
communication channel.
.IP "\fBlmtp_assume_final (no)\fR"
-When an LMTP server announces no DSN support, assume that the
+When a remote LMTP server announces no DSN support, assume that
+the
server performs final delivery, and send "delivered" delivery status
notifications instead of "relayed".
.IP "\fBlmtp_tcp_port (24)\fR"
.ad
.fi
.IP "\fBbroken_sasl_auth_clients (no)\fR"
-Enable inter-operability with SMTP clients that implement an obsolete
+Enable inter-operability with remote SMTP clients that implement an obsolete
version of the AUTH command (RFC 4954).
.IP "\fBdisable_vrfy_command (no)\fR"
Disable the SMTP VRFY command.
.IP "\fBsmtpd_discard_ehlo_keyword_address_maps (empty)\fR"
Lookup tables, indexed by the remote SMTP client address, with
case insensitive lists of EHLO keywords (pipelining, starttls, auth,
-etc.) that the SMTP server will not send in the EHLO response to a
+etc.) that the Postfix SMTP server will not send in the EHLO response
+to a
remote SMTP client.
.IP "\fBsmtpd_discard_ehlo_keywords (empty)\fR"
A case insensitive list of EHLO keywords (pipelining, starttls,
-auth, etc.) that the SMTP server will not send in the EHLO response
+auth, etc.) that the Postfix SMTP server will not send in the EHLO
+response
to a remote SMTP client.
.IP "\fBsmtpd_delay_open_until_valid_rcpt (yes)\fR"
Postpone the start of an SMTP mail transaction until a valid
.PP
Available in Postfix version 2.1 and later:
.IP "\fBsmtpd_authorized_xforward_hosts (empty)\fR"
-What SMTP clients are allowed to use the XFORWARD feature.
+What remote SMTP clients are allowed to use the XFORWARD feature.
.SH "SASL AUTHENTICATION CONTROLS"
.na
.nf
Postfix SMTP client to a remote SMTP server.
See the SASL_README document for details.
.IP "\fBbroken_sasl_auth_clients (no)\fR"
-Enable inter-operability with SMTP clients that implement an obsolete
+Enable inter-operability with remote SMTP clients that implement an obsolete
version of the AUTH command (RFC 4954).
.IP "\fBsmtpd_sasl_auth_enable (no)\fR"
Enable SASL authentication in the Postfix SMTP server.
use with mandatory TLS encryption.
.IP "\fBsmtpd_tls_mandatory_exclude_ciphers (empty)\fR"
Additional list of ciphers or cipher types to exclude from the
-SMTP server cipher list at mandatory TLS security levels.
+Postfix SMTP server cipher list at mandatory TLS security levels.
.IP "\fBsmtpd_tls_mandatory_protocols (SSLv3, TLSv1)\fR"
The SSL/TLS protocols accepted by the Postfix SMTP server with
mandatory TLS encryption.
.IP "\fBsmtpd_tls_received_header (no)\fR"
Request that the Postfix SMTP server produces Received: message
headers that include information about the protocol and cipher used,
-as well as the client CommonName and client certificate issuer
+as well as the remote SMTP client CommonName and client certificate issuer
CommonName.
.IP "\fBsmtpd_tls_req_ccert (no)\fR"
With mandatory TLS encryption, require a trusted remote SMTP client
.PP
Available in Postfix version 2.5 and later:
.IP "\fBsmtpd_tls_fingerprint_digest (md5)\fR"
-The message digest algorithm used to construct client-certificate
-fingerprints for \fBcheck_ccert_access\fR and
-\fBpermit_tls_clientcerts\fR.
+The message digest algorithm to construct remote SMTP
+client-certificate
+fingerprints or public key fingerprints (Postfix 2.9 and later)
+for \fBcheck_ccert_access\fR and \fBpermit_tls_clientcerts\fR.
.PP
Available in Postfix version 2.6 and later:
.IP "\fBsmtpd_tls_protocols (empty)\fR"
The Postfix SMTP server security grade for ephemeral elliptic-curve
Diffie-Hellman (EECDH) key exchange.
.IP "\fBtls_eecdh_strong_curve (prime256v1)\fR"
-The elliptic curve used by the SMTP server for sensibly strong
+The elliptic curve used by the Postfix SMTP server for sensibly
+strong
ephemeral ECDH key exchange.
.IP "\fBtls_eecdh_ultra_curve (secp384r1)\fR"
-The elliptic curve used by the SMTP server for maximally strong
+The elliptic curve used by the Postfix SMTP server for maximally
+strong
ephemeral ECDH key exchange.
.PP
Available in Postfix version 2.8 and later:
.IP "\fBtls_preempt_cipherlist (no)\fR"
-With SSLv3 and later, use the server's cipher preference order
-instead of the client's cipher preference order.
+With SSLv3 and later, use the Postfix SMTP server's cipher
+preference order instead of the remote client's cipher preference
+order.
.IP "\fBtls_disable_workarounds (see 'postconf -d' output)\fR"
List or bit-mask of OpenSSL bug work-arounds to disable.
.SH "OBSOLETE STARTTLS CONTROLS"
with Postfix versions before 2.3. Support for these will
be removed in a future release.
.IP "\fBsmtpd_use_tls (no)\fR"
-Opportunistic TLS: announce STARTTLS support to SMTP clients,
+Opportunistic TLS: announce STARTTLS support to remote SMTP clients,
but do not require that clients use TLS encryption.
.IP "\fBsmtpd_enforce_tls (no)\fR"
-Mandatory TLS: announce STARTTLS support to SMTP clients,
+Mandatory TLS: announce STARTTLS support to remote SMTP clients,
and require that clients use TLS encryption.
.IP "\fBsmtpd_tls_cipherlist (empty)\fR"
Obsolete Postfix < 2.3 control for the Postfix SMTP server TLS
.PP
Available in Postfix version 1.1 and 2.0:
.IP "\fBauthorized_verp_clients ($mynetworks)\fR"
-What SMTP clients are allowed to specify the XVERP command.
+What remote SMTP clients are allowed to specify the XVERP command.
.PP
Available in Postfix version 2.1 and later:
.IP "\fBsmtpd_authorized_verp_clients ($authorized_verp_clients)\fR"
-What SMTP clients are allowed to specify the XVERP command.
+What remote SMTP clients are allowed to specify the XVERP command.
.SH "TROUBLE SHOOTING CONTROLS"
.na
.nf
.IP "\fBnotify_classes (resource, software)\fR"
The list of error classes that are reported to the postmaster.
.IP "\fBsmtpd_reject_footer (empty)\fR"
-Optional information that is appended after each SMTP server
+Optional information that is appended after each Postfix SMTP
+server
4XX or 5XX response.
.IP "\fBsoft_bounce (no)\fR"
Safety net to keep mail queued that would otherwise be returned to
.PP
Available in Postfix version 2.1 and later:
.IP "\fBsmtpd_authorized_xclient_hosts (empty)\fR"
-What SMTP clients are allowed to use the XCLIENT feature.
+What remote SMTP clients are allowed to use the XCLIENT feature.
.SH "KNOWN VERSUS UNKNOWN RECIPIENT CONTROLS"
.na
.nf
Optional lookup tables that alias specific mail addresses or domains
to other local or remote address.
.IP "\fBunknown_virtual_alias_reject_code (550)\fR"
-The SMTP server reply code when a recipient address matches
+The Postfix SMTP server reply code when a recipient address matches
$virtual_alias_domains, and $virtual_alias_maps specifies a list
of lookup tables that does not match the recipient address.
.PP
Optional lookup tables with all valid addresses in the domains that
match $virtual_mailbox_domains.
.IP "\fBunknown_virtual_mailbox_reject_code (550)\fR"
-The SMTP server reply code when a recipient address matches
+The Postfix SMTP server reply code when a recipient address matches
$virtual_mailbox_domains, and $virtual_mailbox_maps specifies a list
of lookup tables that does not match the recipient address.
.SH "RESOURCE AND RATE CONTROLS"
What Postfix features match subdomains of "domain.tld" automatically,
instead of requiring an explicit ".domain.tld" pattern.
.IP "\fBsmtpd_client_restrictions (empty)\fR"
-Optional SMTP server access restrictions in the context of a client
-SMTP connection request.
+Optional Postfix SMTP server access restrictions in the context of
+a remote SMTP client connection request.
.IP "\fBsmtpd_helo_required (no)\fR"
Require that a remote SMTP client introduces itself with the HELO
or EHLO command before sending the MAIL command or other commands
.PP
Available in Postfix version 2.0 and later:
.IP "\fBdefault_rbl_reply (see 'postconf -d' output)\fR"
-The default SMTP server response template for a request that is
+The default Postfix SMTP server response template for a request that is
rejected by an RBL-based restriction.
.IP "\fBmulti_recipient_bounce_reject_code (550)\fR"
The numerical Postfix SMTP server response code when a remote SMTP
.IP "\fBmyhostname (see 'postconf -d' output)\fR"
The internet hostname of this mail system.
.IP "\fBmynetworks (see 'postconf -d' output)\fR"
-The list of "trusted" SMTP clients that have more privileges than
+The list of "trusted" remote SMTP clients that have more privileges than
"strangers".
.IP "\fBmyorigin ($myhostname)\fR"
The domain name that locally-posted mail appears to come
List of ciphers or cipher types to exclude from the \fBtlsproxy\fR(8)
server cipher list at all TLS security levels.
.IP "\fBtlsproxy_tls_fingerprint_digest ($smtpd_tls_fingerprint_digest)\fR"
-The message digest algorithm used to construct client-certificate
+The message digest algorithm to construct remote SMTP
+client-certificate
fingerprints.
.IP "\fBtlsproxy_tls_key_file ($smtpd_tls_key_file)\fR"
File with the Postfix \fBtlsproxy\fR(8) server RSA private key in PEM
These parameters are supported for compatibility with
\fBsmtpd\fR(8) legacy parameters.
.IP "\fBtlsproxy_use_tls ($smtpd_use_tls)\fR"
-Opportunistic TLS: announce STARTTLS support to SMTP clients,
+Opportunistic TLS: announce STARTTLS support to remote SMTP clients,
but do not require that clients use TLS encryption.
.IP "\fBtlsproxy_enforce_tls ($smtpd_enforce_tls)\fR"
-Mandatory TLS: announce STARTTLS support to SMTP clients, and
+Mandatory TLS: announce STARTTLS support to remote SMTP clients, and
require that clients use TLS encryption.
.SH "RESOURCE CONTROLS"
.na
+++ /dev/null
-This patch adds support for logfiles with conn_use, delays, and dsn
-attributes.
-
---- pflogsumm.pl.orig 2005-04-09 12:54:44.000000000 +0200
-+++ pflogsumm.pl 2005-11-07 21:50:05.483199193 +0100
-@@ -696,7 +696,7 @@
- }
- }
- elsif((($addr, $relay, $delay, $status, $toRmdr) = $logRmdr =~
-- /to=<([^>]*)>, (?:orig_to=<[^>]*>, )?relay=([^,]+), delay=([^,]+), status=(\S+)(.*)$/o) >= 4)
-+ /to=<([^>]*)>, (?:orig_to=<[^>]*>, )?relay=([^,]+), (?:conn_use=[^,]+, )?delay=([^,]+), (?:delays=[^,]+, )?(?:dsn=[^,]+, )?status=(\S+)(.*)$/o) >= 4)
- {
-
- if($opts{'m'} && $addr =~ /^(.*!)*([^!]+)!([^!@]+)@([^\.]+)$/o) {
etrn_domain=
<b>Postfix version 2.5 and later:</b>
stress=
+<b>Postfix version 2.9 and later:</b>
+ccert_pubkey_fingerprint=68:B3:29:DA:98:93:E3:40:99:C7:D8:AD:5C:B9:C9:40
[empty line]
</pre>
</blockquote>
<li><a href="#how">How Postfix TLS support works</a>
-<li><a href="#build_tls">Building Postfix with TLS support</a>
-
<li><a href="#server_tls">SMTP Server specific settings</a>
<li> <a href="#client_tls">SMTP Client specific settings</a>
<li><a href="#tlsmgr_controls"> TLS manager specific settings </a>
+<li><a href="#build_tls">Building Postfix with TLS support</a>
+
<li><a href="#problems"> Reporting problems </a>
<li><a href="#credits"> Credits </a>
</table>
-<h2><a name="build_tls">Building Postfix with TLS support</a></h2>
-
-<p> 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. </p>
-
-<p> To build Postfix with TLS support, first we need to generate
-the <tt>make(1)</tt> files with the necessary definitions. This is
-done by invoking the command "<tt>make makefiles</tt>" in the Postfix
-top-level directory and with arguments as shown next. </p>
-
-<p> <b> NOTE: Do not use Gnu TLS. It will spontaneously terminate
-a Postfix daemon process with exit status code 2, instead of allowing
-Postfix to 1) report the error to the maillog file, and to 2) provide
-plaintext service where this is appropriate. </b> </p>
-
-<ul>
-
-<li> <p> If the OpenSSL include files (such as <tt>ssl.h</tt>) are
-in directory <tt>/usr/include/openssl</tt>, and the OpenSSL libraries
-(such as <tt>libssl.so</tt> and <tt>libcrypto.so</tt>) are in
-directory <tt>/usr/lib</tt>: </p>
-
-<blockquote>
-<pre>
-% <b>make tidy</b> # if you have left-over files from a previous build
-% <b>make makefiles CCARGS="-DUSE_TLS" AUXLIBS="-lssl -lcrypto"</b>
-</pre>
-</blockquote>
-
-<li> <p> If the OpenSSL include files (such as <tt>ssl.h</tt>) are
-in directory <tt>/usr/local/include/openssl</tt>, and the OpenSSL
-libraries (such as <tt>libssl.so</tt> and <tt>libcrypto.so</tt>)
-are in directory <tt>/usr/local/lib</tt>: </p>
-
-<blockquote>
-<pre>
-% <b>make tidy</b> # if you have left-over files from a previous build
-% <b>make makefiles CCARGS="-DUSE_TLS -I/usr/local/include" \
- AUXLIBS="-L/usr/local/lib -lssl -lcrypto" </b>
-</pre>
-</blockquote>
-
-<p> On Solaris, specify the <tt>-R</tt> option as shown below:
-
-<blockquote>
-<pre>
-% <b>make tidy</b> # if you have left-over files from a previous build
-% <b>make makefiles CCARGS="-DUSE_TLS -I/usr/local/include" \
- AUXLIBS="-R/usr/local/lib -L/usr/local/lib -lssl -lcrypto" </b>
-</pre>
-</blockquote>
-
-</ul>
-
-<p> 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 "<tt>make makefiles</tt>"
-instructions with the instructions above: </p>
-
-<blockquote>
-<pre>
-% <b>make tidy</b> # if you have left-over files from a previous build
-% <b>make makefiles CCARGS="-DUSE_TLS \
- <i>(other -D or -I options)</i>" \
- AUXLIBS="-lssl -lcrypto \
- <i>(other -l options for libraries in /usr/lib)</i> \
- <i>(-L/path/name + -l options for other libraries)</i>"</b>
-</pre>
-</blockquote>
-
-<p> 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. </p>
-
<h2><a name="server_tls">SMTP Server specific settings</a></h2>
<p> Topics covered in this section: </p>
<blockquote>
-<table>
+<table border="1">
+
+<tr> <th> Level </th> <th> Postfix 2.9 and later</th> <th> Earlier
+releases. </th> </tr>
-<tr> <td> 0 </td> <td> Disable logging of TLS activity.</td> </tr>
+<tr> <td valign="top"> 0 </td> <td valign="top"> Log only a summary
+message on TLS handshake completion — no logging of client
+certificate trust-chain verification errors if client certificate
+verification is not required. </td> <td valign="top"> Disable logging
+of TLS activity.</td> </tr>
-<tr> <td> 1 </td> <td> Log TLS handshake and certificate information.
+<tr> <td valign="top"> 1 </td> <td valign="top"> Also log trust-chain
+verification errors and peer certificate summary information. </td>
+<td valign="top"> Also log TLS handshake and certificate information.
</td> </tr>
-<tr> <td> 2 </td> <td> Log levels during TLS negotiation. </td>
-</tr>
+<tr> <td valign="top"> 2 </td> <td valign="top" colspan="2"> Also
+log levels during TLS negotiation. </td> </tr>
-<tr> <td> 3 </td> <td> Log hexadecimal and ASCII dump of TLS
-negotiation process </td> </tr>
+<tr> <td valign="top"> 3 </td> <td valign="top" colspan="2"> Also
+log hexadecimal and ASCII dump of TLS negotiation process. </td>
+</tr>
-<tr> <td> 4 </td> <td> Log hexadecimal and ASCII dump of complete
-transmission after STARTTLS </td> </tr>
+<tr> <td valign="top"> 4 </td> <td valign="top" colspan="2"> Also
+log hexadecimal and ASCII dump of complete transmission after
+STARTTLS. </td></tr>
</table>
<dl>
-<dt> permit_tls_clientcerts </dt> <dd> <p> Allow the remote SMTP client
-request if the client certificate fingerprint is listed in the
-client certificate table (see relay_clientcerts discussion below). </p>
-</dd>
+<dt> permit_tls_clientcerts </dt> <dd> <p> 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).
+</p> </dd>
<dt> permit_tls_all_clientcerts </dt> <dd> <p> 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). </p> </dd>
-<dt> check_ccert_access type:table</dt> <dd> <p> Use the remote SMTP
-client
-certificate fingerprint as the lookup key for the specified access(5)
+<dt> check_ccert_access type:table</dt> <dd> <p> 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. </p> </dd>
</dl>
</blockquote>
-<p> The digest algorithm used to construct the client certificate
+<p> 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. </p>
<ul>
-<li><a href="#client_lmtp_tls"> TLS support in the LMTP delivery agent </a>
+<li><a href="#client_tls_levels"> Configuring TLS in the SMTP/LMTP client </a>
+
+<li><a href="#client_logging"> Client-side TLS activity logging </a>
<li><a href="#client_cert_key">Client-side certificate and private
key configuration </a>
-<li><a href="#client_logging"> Client-side TLS activity logging
-</a>
-
<li><a href="#client_tls_cache">Client-side TLS session cache</a>
<li><a href="#client_tls_limits"> Client TLS limitations </a>
-<li><a href="#client_tls_levels"> Configuring TLS in the SMTP/LMTP client </a>
-
<li><a href="#client_tls_policy"> Per-destination TLS policy </a>
<li><a href="#client_tls_obs"> Obsolete per-site TLS policy support </a>
</ul>
-<h3><a name="client_lmtp_tls"> TLS support in the LMTP delivery agent </a>
+<h3><a name="client_tls_levels"> Configuring TLS in the SMTP/LMTP client </a>
</h3>
+<p> 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.</p>
+
+<dl>
+<dt><b>none</b></dt>
+<dd><a href="#client_tls_none">No TLS.</a></dd>
+<dt><b>may</b></dt>
+<dd><a href="#client_tls_may">Opportunistic TLS.</a></dd>
+<dt><b>encrypt</b></dt>
+<dd><a href="#client_tls_encrypt">Mandatory TLS encryption.</a>
+<dt><b>fingerprint</b></dt>
+<dd><a href="#client_tls_fprint">Certificate fingerprint verification.</a>
+<dt><b>verify</b></dt>
+<dd><a href="#client_tls_verify">Mandatory server certificate verification.</a>
+<dt><b>secure</b></dt>
+<dd><a href="#client_tls_secure">Secure-channel TLS.</a>
+</dl>
+
+<h4><a name="client_lmtp_tls"> TLS support in the LMTP delivery agent </a> </h4>
+
<p> The smtp(8) and lmtp(8) delivery agents are implemented by a
single dual-purpose program. Specifically, all the TLS features
described below apply
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 <i>nexthop</i> and
-<i>hostname</i>. Note, opportunistic encryption of LMTP traffic over
-UNIX-domain sockets is futile. TLS is only useful in this context when
+<i>hostname</i>. </p>
+
+<p> 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. </p>
-<h3><a name="client_cert_key">Client-side certificate and private
-key configuration </a> </h3>
+<h4><a name="client_tls_none"> No TLS encryption </a> </h4>
-<p> Do not configure Postfix SMTP client certificates unless you <b>must</b>
-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: </p>
+<p> At the "none" TLS security level, TLS encryption is
+disabled. This is the default security level. With Postfix 2.3 and later,
+it can be configured explicitly by setting "smtp_tls_security_level = none". </p>
-<blockquote>
-<pre>
- 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 =
-</pre>
-</blockquote>
+<p> With Postfix 2.2 and earlier, or when smtp_tls_security_level is set to
+its default (backwards compatible) empty value, the appropriate configuration
+settings are "smtp_use_tls = no" and "smtp_enforce_tls = no".
+With either approach, TLS is not used even if supported by the server.
+For LMTP, use the corresponding "lmtp_" parameters. </p>
-<p> The best way to use the default settings is to comment out the above
-parameters in main.cf if present. </p>
+<p> Per destination settings may override this default setting, in which case
+TLS is used selectively, only with destinations explicitly configured
+for TLS. </p>
-<p> During TLS startup negotiation the Postfix SMTP client may present
-a certificate to the remote SMTP server. The Netscape client is
-rather clever here and lets the user select between only those
-certificates that match CA certificates offered by the remote SMTP
-server. As the Postfix SMTP client uses the "SSL_connect()" function
-from the OpenSSL package, this is not possible and we have to choose
-just one certificate. So for now the default is to use _no_
-certificate and key unless one is explicitly specified here. </p>
+<p> You can disable TLS for a subset of destinations, while leaving
+it enabled for the rest. With the Postfix 2.3 and later TLS <a
+href="#client_tls_policy">policy table</a>, specify the "none"
+security level. With the obsolete <a href="#client_tls_obs">per-site</a>
+table, specify the "NONE" keyword. </p>
-<p> 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. </p>
+<h4><a name="client_tls_may"> Opportunistic TLS </a> </h4>
-<p> 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. </p>
+<p> At the "may" TLS security level, TLS encryption is <i>opportunistic</i>.
+The SMTP transaction is encrypted if the STARTTLS ESMTP feature
+is supported by the server. Otherwise, messages are sent in the clear.
+With Postfix 2.3 and later, opportunistic TLS can be configured by
+setting "smtp_tls_security_level = may".
-<p> 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). </p>
+<p> Since sending in the clear is acceptable, demanding stronger
+than default TLS security mostly reduces inter-operability. If you
+must restrict TLS protocol or cipher selection even with opportunistic
+TLS, the "smtp_tls_ciphers" and "smtp_tls_protocols" configuration
+parameters (Postfix ≥ 2.6) provide control over the protocols
+and cipher grade
+used with opportunistic TLS. With earlier releases the opportunistic TLS
+cipher grade is always "export" and no protocols are disabled. </p>
-<p> Example: the certificate for "client.example.com" was issued by
-"intermediate CA" which itself has a certificate issued by "root CA".
-Create the client.pem file with: </p>
+<p> With Postfix 2.2 and earlier, or when smtp_tls_security_level is
+set to its default (backwards compatible) empty value, the appropriate
+configuration settings are "smtp_use_tls = yes" and
+"smtp_enforce_tls = no".
+For LMTP use the corresponding "lmtp_" parameters. </p>
-<blockquote>
-<pre>
-% <b>cat client_cert.pem intermediate_CA.pem > client.pem </b>
-</pre>
-</blockquote>
+<p> With opportunistic TLS, mail delivery continues even if the
+server certificate is untrusted or bears the wrong name. Starting
+with Postfix 2.3, when the TLS handshake fails for an opportunistic
+TLS session, rather than give up on mail delivery, the transaction
+is retried with TLS disabled. Trying an unencrypted connection makes
+it possible to deliver mail to sites with non-interoperable server
+TLS implementations. </p>
-<p> A Postfix SMTP client certificate supplied here must be usable
-as SSL client certificate and hence pass the "openssl verify -purpose
-sslclient ..." test. </p>
+<p> 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
+<a href="#client_tls_encrypt">encrypt</a> security level or higher.
+Attempts to configure opportunistic encryption of LMTP sessions will
+be ignored with a warning written to the mail logs. </p>
-<p> 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 "client.pem" file reduces
-the overhead of the TLS exchange. </p>
+<p> You can enable opportunistic TLS just for selected destinations. With
+the Postfix 2.3 and later TLS <a href="#client_tls_policy">policy table</a>,
+specify the "may" security level. With the obsolete <a
+href="#client_tls_obs">per-site</a> table, specify the "MAY" keyword.</p>
-<p> 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. </p>
+<p> 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 <a href="#client_tls_limits">limitations</a> above. </p>
+
+<p> Example: </p>
-<p> RSA key and certificate examples: </p>
-
<blockquote>
<pre>
/etc/postfix/main.cf:
- smtp_tls_cert_file = /etc/postfix/client.pem
- smtp_tls_key_file = $smtp_tls_cert_file
+ smtp_tls_security_level = may
</pre>
</blockquote>
-<p> Their DSA counterparts: </p>
+<p> Postfix 2.2 syntax: </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
- smtp_tls_dcert_file = /etc/postfix/client-dsa.pem
- smtp_tls_dkey_file = $smtp_tls_dcert_file
-</pre>
+ smtp_use_tls = yes
+ smtp_enforce_tls = no
+</pre>
</blockquote>
-<p> Their ECDSA counterparts (Postfix ≥ 2.6 + OpenSSL ≥ 0.9.9): </p>
-
-<blockquote>
-<pre>
-/etc/postfix/main.cf:
- smtp_tls_eccert_file = /etc/postfix/client-ecdsa.pem
- smtp_tls_eckey_file = $smtp_tls_eccert_file
-</pre>
-</blockquote>
-
-<p> 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: </p>
-
-<blockquote>
-<pre>
-# <b>$OPENSSL_HOME/bin/c_rehash <i>/path/to/directory</i> </b>
-</pre>
-</blockquote>
-
-<p> 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. </p>
-
-<p> 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. </p>
-
-<p> 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. </p>
-
-<p> Example: </p>
-
-<blockquote>
-<pre>
-/etc/postfix/main.cf:
- smtp_tls_CAfile = /etc/postfix/CAcert.pem
- smtp_tls_CApath = /etc/postfix/certs
-</pre>
-</blockquote>
-
-<h3><a name="client_logging"> Client-side TLS activity logging </a> </h3>
-
-<p> 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. </p>
-
-<blockquote>
-
-<table>
-
-<tr> <td> 0 </td> <td> Disable logging of TLS activity.</td> </tr>
-
-<tr> <td> 1 </td> <td> Log TLS handshake and certificate information.
-</td> </tr>
-
-<tr> <td> 2 </td> <td> Log levels during TLS negotiation. </td>
-</tr>
-
-<tr> <td> 3 </td> <td> Log hexadecimal and ASCII dump of TLS
-negotiation process </td> </tr>
-
-<tr> <td> 4 </td> <td> Log hexadecimal and ASCII dump of complete
-transmission after STARTTLS </td> </tr>
-
-</table>
-
-</blockquote>
-
-<p> Example: </p>
-
-<blockquote>
-<pre>
-/etc/postfix/main.cf:
- smtp_tls_loglevel = 0
-</pre>
-</blockquote>
-
-<h3><a name="client_tls_cache">Client-side TLS session cache</a> </h3>
-
-<p> 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.</p>
-
-
-<p> Example: </p>
-
-<blockquote>
-<pre>
-/etc/postfix/main.cf:
- smtp_tls_session_cache_database = btree:/var/lib/postfix/smtp_scache
-</pre>
-</blockquote>
-
-<p> 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. </p>
-
-<p> 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. </p>
-
-<p> Example: </p>
-
-<blockquote>
-<pre>
-/etc/postfix/main.cf:
- smtp_tls_session_cache_timeout = 3600s
-</pre>
-</blockquote>
-
-<h3><a name="client_tls_limits"> Client TLS limitations </a>
-</h3>
-
-<p> 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. </p>
-
-<p> 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. </p>
-
-<p> 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. </p>
-
-<p> 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. </p>
-
-<p> 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. </p>
-
-<p> 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. </p>
-
-<p> 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. </p>
-
-<p> It is regrettably the case that TLS <i>secure-channels</i>
-(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
-<a href="#client_tls_policy">policy table</a> entries for additional
-domains hosted at a common secured destination. With Postfix 2.3, we
-make secure-channel configurations substantially easier to configure,
-but they 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. </p>
-
-<p> 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. </p>
-
-<p> Historical note: while the documentation of these issues and many of the
-related features are new with Postfix 2.3, the issue was well
-understood before Postfix 1.0, when Lutz Jänicke was designing
-the first unofficial Postfix TLS patch. See his original post <a
-href="http://www.imc.org/ietf-apps-tls/mail-archive/msg00304.html">http://www.imc.org/ietf-apps-tls/mail-archive/msg00304.html</a>
-and the first response <a
-href="http://www.imc.org/ietf-apps-tls/mail-archive/msg00305.html">http://www.imc.org/ietf-apps-tls/mail-archive/msg00305.html</a>.
-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. </p>
-
-<h3><a name="client_tls_levels"> Configuring TLS in the SMTP/LMTP client </a>
-</h3>
-
-<p> 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.</p>
-
-<dl>
-<dt><b>none</b></dt>
-<dd><a href="#client_tls_none">No TLS.</a></dd>
-<dt><b>may</b></dt>
-<dd><a href="#client_tls_may">Opportunistic TLS.</a></dd>
-<dt><b>encrypt</b></dt>
-<dd><a href="#client_tls_encrypt">Mandatory TLS encryption.</a>
-<dt><b>fingerprint</b></dt>
-<dd><a href="#client_tls_fprint">Certificate fingerprint verification.</a>
-<dt><b>verify</b></dt>
-<dd><a href="#client_tls_verify">Mandatory server certificate verification.</a>
-<dt><b>secure</b></dt>
-<dd><a href="#client_tls_secure">Secure-channel TLS.</a>
-</dl>
-
-<h3><a name="client_tls_none"> No TLS encryption </a>
-</h3>
-
-<p> At the "none" TLS security level, TLS encryption is
-disabled. This is the default security level. With Postfix 2.3 and later,
-it can be configured explicitly by setting "smtp_tls_security_level = none". </p>
-
-<p> With Postfix 2.2 and earlier, or when smtp_tls_security_level is set to
-its default (backwards compatible) empty value, the appropriate configuration
-settings are "smtp_use_tls = no" and "smtp_enforce_tls = no".
-With either approach, TLS is not used even if supported by the server.
-For LMTP, use the corresponding "lmtp_" parameters. </p>
-
-<p> Per destination settings may override this default setting, in which case
-TLS is used selectively, only with destinations explicitly configured
-for TLS. </p>
-
-<p> You can disable TLS for a subset of destinations, while leaving
-it enabled for the rest. With the Postfix 2.3 and later TLS <a
-href="#client_tls_policy">policy table</a>, specify the "none"
-security level. With the obsolete <a href="#client_tls_obs">per-site</a>
-table, specify the "NONE" keyword. </p>
-
-<h3><a name="client_tls_may"> Opportunistic TLS </a>
-</h3>
-
-<p> At the "may" TLS security level, TLS encryption is <i>opportunistic</i>.
-The SMTP transaction is encrypted if the STARTTLS ESMTP feature
-is supported by the server. Otherwise, messages are sent in the clear.
-With Postfix 2.3 and later, opportunistic TLS can be configured by
-setting "smtp_tls_security_level = may".
-
-<p> Since sending in the clear is acceptable, demanding stronger
-than default TLS security mostly reduces inter-operability. If you
-must restrict TLS protocol or cipher selection even with opportunistic
-TLS, the "smtp_tls_ciphers" and "smtp_tls_protocols" configuration
-parameters (Postfix ≥ 2.6) provide control over the protocols
-and cipher grade
-used with opportunistic TLS. With earlier releases the opportunistic TLS
-cipher grade is always "export" and no protocols are disabled. </p>
-
-<p> With Postfix 2.2 and earlier, or when smtp_tls_security_level is
-set to its default (backwards compatible) empty value, the appropriate
-configuration settings are "smtp_use_tls = yes" and
-"smtp_enforce_tls = no".
-For LMTP use the corresponding "lmtp_" parameters. </p>
-
-<p> With opportunistic TLS, mail delivery continues even if the
-server certificate is untrusted or bears the wrong name. Starting
-with Postfix 2.3, when the TLS handshake fails for an opportunistic
-TLS session, rather than give up on mail delivery, the transaction
-is retried with TLS disabled. Trying an unencrypted connection makes
-it possible to deliver mail to sites with non-interoperable server
-TLS implementations. </p>
-
-<p> 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
-<a href="#client_tls_encrypt">encrypt</a> security level or higher.
-Attempts to configure opportunistic encryption of LMTP sessions will
-be ignored with a warning written to the mail logs. </p>
-
-<p> You can enable opportunistic TLS just for selected destinations. With
-the Postfix 2.3 and later TLS <a href="#client_tls_policy">policy table</a>,
-specify the "may" security level. With the obsolete <a
-href="#client_tls_obs">per-site</a> table, specify the "MAY" keyword.</p>
-
-<p> 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 <a href="#client_tls_limits">limitations</a> above. </p>
-
-<p> Example: </p>
-
-<blockquote>
-<pre>
-/etc/postfix/main.cf:
- smtp_tls_security_level = may
-</pre>
-</blockquote>
-
-<p> Postfix 2.2 syntax: </p>
-
-<blockquote>
-<pre>
-/etc/postfix/main.cf:
- smtp_use_tls = yes
- smtp_enforce_tls = no
-</pre>
-</blockquote>
-
-<h3><a name="client_tls_encrypt"> Mandatory TLS encryption </a>
-</h3>
+<h4><a name="client_tls_encrypt"> Mandatory TLS encryption </a> </h4>
<p> At the "encrypt" TLS security level, messages are sent only
over TLS encrypted sessions. The SMTP transaction is aborted unless
</pre>
</blockquote>
-<h3><a name="client_tls_fprint"> Certificate fingerprint verification </a>
-</h3>
+<h4><a name="client_tls_fprint"> Certificate fingerprint verification </a> </h4>
-<p> Certificate fingerprint verification is available with Postfix 2.5 and
-later. At this security level ("smtp_tls_security_level = fingerprint"),
-no trusted certificate authorities are used or required. The certificate
-trust chain, expiration date, ... are not checked. Instead, the
-smtp_tls_fingerprint_cert_match parameter or the "match" attribute
-in the <a href="#client_tls_policy">policy</a> table lists the valid
-"fingerprints" of the remote SMTP server certificate. </p>
+<p> Certificate fingerprint verification is available with Postfix
+2.5 and later. At this security level ("smtp_tls_security_level =
+fingerprint"), no trusted certificate authorities are used or
+required. The certificate trust chain, expiration date, ... are
+not checked. Instead, the smtp_tls_fingerprint_cert_match parameter
+or the "match" attribute in the <a href="#client_tls_policy">policy</a>
+table lists the remote SMTP server certificate fingerprint or
+public key fingerprint (Postfix 2.9 and later).
<p> 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. This 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. </p>
+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,
+<b>provided</b> that the same public/private keys are used to obtain
+the new certificate. </p>
+
+<p> 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. </p>
<p> The digest algorithm used to calculate the fingerprint is
selected by the <b>smtp_tls_fingerprint_digest</b> parameter. In the <a
</pre>
</blockquote>
-<h3><a name="client_tls_verify"> Mandatory server certificate verification </a>
-</h3>
+<h4><a name="client_tls_verify"> Mandatory server certificate verification </a> </h4>
<p> At the "verify" TLS security level, messages are sent only over
TLS encrypted sessions if the remote SMTP server certificate is
</pre>
</blockquote>
-<h3><a name="client_tls_secure"> Secure server certificate verification </a>
-</h3>
+<h4><a name="client_tls_secure"> Secure server certificate verification </a> </h4>
<p> At the <i>secure</i> TLS security level, messages are sent only over
<i>secure-channel</i> TLS sessions where DNS forgery resistant server
<blockquote>
<pre>
/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
+ 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
+</pre>
+</blockquote>
+
+<p> Secure-channel TLS with transport(5) table overrides: <p>
+
+<p> In this case traffic to <i>example.com</i> 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. This secure-channel configuration can also
+be implemented via a <a href="#client_tls_harden">hardened</a> variant of
+the MUST policy in the obsolete <a href="#client_tls_obs">per-site</a>
+table. As stated above, this approach has the potential to mis-deliver
+email if the related domains change hands. </p>
+
+<blockquote>
+<pre>
+/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
+</pre>
+</blockquote>
+
+<p> Postfix 2.2.9 and later syntax: </p>
+
+<p> <b>Note:</b> Avoid policy lookups with the bare hostname (for
+example, "tls.example.com"). Instead, use the destination (for
+example, "[tls.example.com]") as the <a
+href="#client_tls_obs">per-site</a> table lookup key (a recipient domain
+or MX-enabled transport nexthop with no port suffix may look like a bare
+hostname, but is still a suitable <i>destination</i>). With Postfix 2.3
+and later,
+do not use the obsolete <a href="#client_tls_obs">per-site</a> table;
+use the new <a href="#client_tls_policy">policy table</a> instead. </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_cname_overrides_servername = no
+ smtp_tls_CAfile = /etc/postfix/CAfile.pem
+ transport_maps = hash:/etc/postfix/transport
+ smtp_tls_per_site = hash:/etc/postfix/tls_per_site
+
+/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_per_site:
+ [tls.example.com] MUST
+</pre>
+</blockquote>
+
+<h3><a name="client_logging"> Client-side TLS activity logging </a> </h3>
+
+<p> 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. </p>
+
+<blockquote>
+
+<table border="1">
+
+<tr> <th> Level </th> <th> Postfix 2.9 and later</th> <th> Earlier
+releases. </th> </tr>
+
+<tr> <td valign="top"> 0 </td> <td valign="top"> Log only a summary
+message on TLS handshake completion — no logging of remote
+SMTP server certificate trust-chain verification errors if server
+certificate verification is not required. </td> <td valign="top">
+Disable logging of TLS activity.</td> </tr>
+
+<tr> <td valign="top"> 1 </td> <td valign="top"> Also log remote
+SMTP server trust-chain verification errors and peer certificate
+summary information. </td> <td valign="top"> Also log TLS handshake
+and certificate information. </td> </tr>
+
+<tr> <td valign="top"> 2 </td> <td valign="top" colspan="2"> Also
+log levels during TLS negotiation. </td> </tr>
+
+<tr> <td valign="top"> 3 </td> <td valign="top" colspan="2"> Also
+log hexadecimal and ASCII dump of TLS negotiation process. </td>
+</tr>
+
+<tr> <td valign="top"> 4 </td> <td valign="top" colspan="2"> Also
+log hexadecimal and ASCII dump of complete transmission after
+STARTTLS. </td> </tr>
+
+</table>
+
+</blockquote>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_loglevel = 0
+</pre>
+</blockquote>
+
+<h3><a name="client_cert_key">Client-side certificate and private
+key configuration </a> </h3>
+
+<p> Do not configure Postfix SMTP client certificates unless you <b>must</b>
+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: </p>
+
+<blockquote>
+<pre>
+ 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 =
+</pre>
+</blockquote>
+
+<p> The best way to use the default settings is to comment out the above
+parameters in main.cf if present. </p>
+
+<p> During TLS startup negotiation the Postfix SMTP client may present
+a certificate to the remote SMTP server. The Netscape client is
+rather clever here and lets the user select between only those
+certificates that match CA certificates offered by the remote SMTP
+server. As the Postfix SMTP client uses the "SSL_connect()" function
+from the OpenSSL package, this is not possible and we have to choose
+just one certificate. So for now the default is to use _no_
+certificate and key unless one is explicitly specified here. </p>
+
+<p> 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. </p>
+
+<p> 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. </p>
+
+<p> 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). </p>
+
+<p> Example: the certificate for "client.example.com" was issued by
+"intermediate CA" which itself has a certificate issued by "root CA".
+Create the client.pem file with: </p>
+
+<blockquote>
+<pre>
+% <b>cat client_cert.pem intermediate_CA.pem > client.pem </b>
+</pre>
+</blockquote>
+
+<p> A Postfix SMTP client certificate supplied here must be usable
+as SSL client certificate and hence pass the "openssl verify -purpose
+sslclient ..." test. </p>
+
+<p> 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 "client.pem" file reduces
+the overhead of the TLS exchange. </p>
+
+<p> 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. </p>
+
+<p> RSA key and certificate examples: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_cert_file = /etc/postfix/client.pem
+ smtp_tls_key_file = $smtp_tls_cert_file
+</pre>
+</blockquote>
+
+<p> Their DSA counterparts: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_dcert_file = /etc/postfix/client-dsa.pem
+ smtp_tls_dkey_file = $smtp_tls_dcert_file
+</pre>
+</blockquote>
+
+<p> Their ECDSA counterparts (Postfix ≥ 2.6 + OpenSSL ≥ 0.9.9): </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_eccert_file = /etc/postfix/client-ecdsa.pem
+ smtp_tls_eckey_file = $smtp_tls_eccert_file
+</pre>
+</blockquote>
+
+<p> 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: </p>
+
+<blockquote>
+<pre>
+# <b>$OPENSSL_HOME/bin/c_rehash <i>/path/to/directory</i> </b>
+</pre>
+</blockquote>
+
+<p> 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. </p>
+
+<p> 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. </p>
+
+<p> 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. </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_CAfile = /etc/postfix/CAcert.pem
+ smtp_tls_CApath = /etc/postfix/certs
</pre>
</blockquote>
-<p> Secure-channel TLS with transport(5) table overrides: <p>
+<h3><a name="client_tls_cache">Client-side TLS session cache</a> </h3>
+
+<p> 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.</p>
-<p> In this case traffic to <i>example.com</i> 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. This secure-channel configuration can also
-be implemented via a <a href="#client_tls_harden">hardened</a> variant of
-the MUST policy in the obsolete <a href="#client_tls_obs">per-site</a>
-table. As stated above, this approach has the potential to mis-deliver
-email if the related domains change hands. </p>
+<p> Example: </p>
+
<blockquote>
<pre>
/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
+ smtp_tls_session_cache_database = btree:/var/lib/postfix/smtp_scache
</pre>
</blockquote>
-<p> Postfix 2.2.9 and later syntax: </p>
+<p> 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. </p>
-<p> <b>Note:</b> Avoid policy lookups with the bare hostname (for
-example, "tls.example.com"). Instead, use the destination (for
-example, "[tls.example.com]") as the <a
-href="#client_tls_obs">per-site</a> table lookup key (a recipient domain
-or MX-enabled transport nexthop with no port suffix may look like a bare
-hostname, but is still a suitable <i>destination</i>). With Postfix 2.3
-and later,
-do not use the obsolete <a href="#client_tls_obs">per-site</a> table;
-use the new <a href="#client_tls_policy">policy table</a> instead. </p>
+<p> 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. </p>
+<p> Example: </p>
+
<blockquote>
<pre>
/etc/postfix/main.cf:
- smtp_cname_overrides_servername = no
- smtp_tls_CAfile = /etc/postfix/CAfile.pem
- transport_maps = hash:/etc/postfix/transport
- smtp_tls_per_site = hash:/etc/postfix/tls_per_site
-
-/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_per_site:
- [tls.example.com] MUST
+ smtp_tls_session_cache_timeout = 3600s
</pre>
</blockquote>
+<h3><a name="client_tls_limits"> Client TLS limitations </a>
+</h3>
+
+<p> 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. </p>
+
+<p> 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. </p>
+
+<p> 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. </p>
+
+<p> 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. </p>
+
+<p> 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. </p>
+
+<p> 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. </p>
+
+<p> 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. </p>
+
+<p> It is regrettably the case that TLS <i>secure-channels</i>
+(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
+<a href="#client_tls_policy">policy table</a> entries for additional
+domains hosted at a common secured destination. With Postfix 2.3, we
+make secure-channel configurations substantially easier to configure,
+but they 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. </p>
+
+<p> 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. </p>
+
+<p> Historical note: while the documentation of these issues and many of the
+related features are new with Postfix 2.3, the issue was well
+understood before Postfix 1.0, when Lutz Jänicke was designing
+the first unofficial Postfix TLS patch. See his original post <a
+href="http://www.imc.org/ietf-apps-tls/mail-archive/msg00304.html">http://www.imc.org/ietf-apps-tls/mail-archive/msg00304.html</a>
+and the first response <a
+href="http://www.imc.org/ietf-apps-tls/mail-archive/msg00305.html">http://www.imc.org/ietf-apps-tls/mail-archive/msg00305.html</a>.
+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. </p>
+
<h3> <a name="client_tls_policy"> TLS policy table </a>
</h3>
later. At this security level, there are no trusted certificate
authorities. The certificate trust chain, expiration date, ... are
not checked. Instead, the optional <b>match</b> attribute, or else
-the main.cf <b>smtp_tls_fingerprint_cert_match</b> parameter,
-lists the valid fingerprints of the server certificate. The
+the main.cf <b>smtp_tls_fingerprint_cert_match</b> 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
<b>smtp_tls_fingerprint_digest</b> parameter. Multiple fingerprints can
be combined with a "|" delimiter in a single match attribute, or multiple
</ul>
+<h2><a name="build_tls">Building Postfix with TLS support</a></h2>
+
+<p> 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. </p>
+
+<p> To build Postfix with TLS support, first we need to generate
+the <tt>make(1)</tt> files with the necessary definitions. This is
+done by invoking the command "<tt>make makefiles</tt>" in the Postfix
+top-level directory and with arguments as shown next. </p>
+
+<p> <b> NOTE: Do not use Gnu TLS. It will spontaneously terminate
+a Postfix daemon process with exit status code 2, instead of allowing
+Postfix to 1) report the error to the maillog file, and to 2) provide
+plaintext service where this is appropriate. </b> </p>
+
+<ul>
+
+<li> <p> If the OpenSSL include files (such as <tt>ssl.h</tt>) are
+in directory <tt>/usr/include/openssl</tt>, and the OpenSSL libraries
+(such as <tt>libssl.so</tt> and <tt>libcrypto.so</tt>) are in
+directory <tt>/usr/lib</tt>: </p>
+
+<blockquote>
+<pre>
+% <b>make tidy</b> # if you have left-over files from a previous build
+% <b>make makefiles CCARGS="-DUSE_TLS" AUXLIBS="-lssl -lcrypto"</b>
+</pre>
+</blockquote>
+
+<li> <p> If the OpenSSL include files (such as <tt>ssl.h</tt>) are
+in directory <tt>/usr/local/include/openssl</tt>, and the OpenSSL
+libraries (such as <tt>libssl.so</tt> and <tt>libcrypto.so</tt>)
+are in directory <tt>/usr/local/lib</tt>: </p>
+
+<blockquote>
+<pre>
+% <b>make tidy</b> # if you have left-over files from a previous build
+% <b>make makefiles CCARGS="-DUSE_TLS -I/usr/local/include" \
+ AUXLIBS="-L/usr/local/lib -lssl -lcrypto" </b>
+</pre>
+</blockquote>
+
+<p> On Solaris, specify the <tt>-R</tt> option as shown below:
+
+<blockquote>
+<pre>
+% <b>make tidy</b> # if you have left-over files from a previous build
+% <b>make makefiles CCARGS="-DUSE_TLS -I/usr/local/include" \
+ AUXLIBS="-R/usr/local/lib -L/usr/local/lib -lssl -lcrypto" </b>
+</pre>
+</blockquote>
+
+</ul>
+
+<p> 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 "<tt>make makefiles</tt>"
+instructions with the instructions above: </p>
+
+<blockquote>
+<pre>
+% <b>make tidy</b> # if you have left-over files from a previous build
+% <b>make makefiles CCARGS="-DUSE_TLS \
+ <i>(other -D or -I options)</i>" \
+ AUXLIBS="-lssl -lcrypto \
+ <i>(other -l options for libraries in /usr/lib)</i> \
+ <i>(-L/path/name + -l options for other libraries)</i>"</b>
+</pre>
+</blockquote>
+
+<p> 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. </p>
+
<h2> <a name="problems"> Reporting problems </a> </h2>
<p> Problems are preferably reported via <postfix-users@postfix.org>.
%PARAM default_rbl_reply see "postconf -d" output
<p>
-The default SMTP server response template for a request that is
+The default Postfix SMTP server response template for a request that is
rejected by an RBL-based restriction. This template can be overruled
by specific entries in the optional rbl_reply_maps lookup table.
</p>
</p>
<p>
-With the default 100 SMTP server process limit, "in_flow_delay
+With the default 100 Postfix SMTP server process limit, "in_flow_delay
= 1s" limits the mail inflow to 100 messages per second above the
number of messages delivered per second.
</p>
<p>
On a multi-homed firewall with separate Postfix instances listening on the
"inside" and "outside" interfaces, this can prevent each instance from
-being able to reach servers on the "other side" of the firewall. Setting
+being able to reach remote SMTP servers on the "other side" of the
+firewall. Setting
smtp_bind_address to 0.0.0.0 avoids the potential problem for
IPv4, and setting smtp_bind_address6 to :: solves the problem
for IPv6. </p>
<p>
The time after which a client closes an idle internal communication
-channel. The purpose is to allow servers to terminate voluntarily
-after they become idle. This is used, for example, by the address
-resolving and rewriting clients.
+channel. The purpose is to allow Postfix daemon processes to
+terminate voluntarily after they become idle. This is used, for
+example, by the Postfix address resolving and rewriting clients.
</p>
<p> With Postfix 2.4 the default value was reduced from 100s to 5s. </p>
<p>
The time after which a client closes an active internal communication
-channel. The purpose is to allow servers to terminate voluntarily
+channel. The purpose is to allow Postfix daemon processes to
+terminate voluntarily
after reaching their client limit. This is used, for example, by
-the address resolving and rewriting clients.
+the Postfix address resolving and rewriting clients.
</p>
<p>
%PARAM lmtp_connect_timeout 0s
-<p> The LMTP client time limit for completing a TCP connection, or
+<p> The Postfix LMTP client time limit for completing a TCP connection, or
zero (use the operating system built-in time limit). When no
connection can be made within the deadline, the LMTP client tries
the next address on the mail exchanger list. </p>
%PARAM lmtp_data_done_timeout 600s
-<p> The LMTP client time limit for sending the LMTP ".", and for
-receiving the server response. When no response is received within
-the deadline, a warning is logged that the mail may be delivered
-multiple times. </p>
+<p> The Postfix LMTP client time limit for sending the LMTP ".",
+and for receiving the remote LMTP server response. When no response
+is received within the deadline, a warning is logged that the mail
+may be delivered multiple times. </p>
<p>
Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
%PARAM lmtp_data_init_timeout 120s
<p>
-The LMTP client time limit for sending the LMTP DATA command, and
-for receiving the server response.
+The Postfix LMTP client time limit for sending the LMTP DATA command,
+and
+for receiving the remote LMTP server response.
</p>
<p>
%PARAM lmtp_data_xfer_timeout 180s
<p>
-The LMTP client time limit for sending the LMTP message content.
+The Postfix LMTP client time limit for sending the LMTP message
+content.
When the connection stalls for more than $lmtp_data_xfer_timeout
the LMTP client terminates the transfer.
</p>
%PARAM lmtp_lhlo_timeout 300s
-<p> The LMTP client time limit for receiving the LMTP greeting
-banner. When the server drops the connection without sending a
+<p> The Postfix LMTP client time limit for receiving the LMTP
+greeting banner. When the remote LMTP server drops the connection
+without sending a
greeting banner, or when it sends no greeting banner within the
deadline, the LMTP client tries the next address on the mail
exchanger list. </p>
%PARAM lmtp_mail_timeout 300s
<p>
-The LMTP client time limit for sending the MAIL FROM command, and
-for receiving the server response.
+The Postfix LMTP client time limit for sending the MAIL FROM command,
+and for receiving the remote LMTP server response.
</p>
<p>
%PARAM lmtp_quit_timeout 300s
<p>
-The LMTP client time limit for sending the QUIT command, and for
-receiving the server response.
+The Postfix LMTP client time limit for sending the QUIT command,
+and for receiving the remote LMTP server response.
</p>
<p>
%PARAM lmtp_rcpt_timeout 300s
<p>
-The LMTP client time limit for sending the RCPT TO command, and
-for receiving the server response.
+The Postfix LMTP client time limit for sending the RCPT TO command,
+and for receiving the remote LMTP server response.
</p>
<p>
%PARAM lmtp_rset_timeout 20s
-<p> The LMTP client time limit for sending the RSET command, and
-for receiving the server response. The LMTP client sends RSET in
+<p> The Postfix LMTP client time limit for sending the RSET command,
+and for receiving the remote LMTP server response. The LMTP client
+sends RSET in
order to finish a recipient address probe, or to verify that a
cached connection is still alive. </p>
%PARAM lmtp_send_xforward_command no
<p>
-Send an XFORWARD command to the LMTP server when the LMTP LHLO
+Send an XFORWARD command to the remote LMTP server when the LMTP LHLO
server response announces XFORWARD support. This allows an lmtp(8)
delivery agent, used for content filter message injection, to
forward the name, address, protocol and HELO name of the original
%PARAM lmtp_xforward_timeout 300s
<p>
-The LMTP client time limit for sending the XFORWARD command, and
-for receiving the server response.
+The Postfix LMTP client time limit for sending the XFORWARD command,
+and for receiving the remote LMTP server response.
</p>
<p>
%PARAM mynetworks see "postconf -d" output
<p>
-The list of "trusted" SMTP clients that have more privileges than
+The list of "trusted" remote SMTP clients that have more privileges than
"strangers".
</p>
%PARAM qmqpd_authorized_clients
<p>
-What clients are allowed to connect to the QMQP server port.
+What remote QMQP clients are allowed to connect to the Postfix QMQP
+server port.
</p>
<p>
%PARAM qmqpd_error_delay 1s
<p>
-How long the QMQP server will pause before sending a negative reply
-to the client. The purpose is to slow down confused or malicious
-clients.
+How long the Postfix QMQP server will pause before sending a negative
+reply to the remote QMQP client. The purpose is to slow down confused
+or malicious clients.
</p>
<p>
<p>
The time limit for sending or receiving information over the network.
If a read or write operation blocks for more than $qmqpd_timeout
-seconds the QMQP server gives up and disconnects.
+seconds the Postfix QMQP server gives up and disconnects.
</p>
<p>
<p>
The minimal amount of free space in bytes in the queue file system
-that is needed to receive mail. This is currently used by the SMTP
-server to decide if it will accept any mail at all.
+that is needed to receive mail. This is currently used by the
+Postfix SMTP server to decide if it will accept any mail at all.
</p>
<p>
</p>
<p>
-With "smtp_always_send_ehlo = no", Postfix sends EHLO only when
+With "smtp_always_send_ehlo = no", the Postfix SMTP client sends
+EHLO only when
the word "ESMTP" appears in the server greeting banner (example:
220 spike.porcupine.org ESMTP Postfix).
</p>
%PARAM smtp_connect_timeout 30s
<p>
-The SMTP client time limit for completing a TCP connection, or
+The Postfix SMTP client time limit for completing a TCP connection, or
zero (use the operating system built-in time limit).
</p>
%PARAM smtp_data_done_timeout 600s
<p>
-The SMTP client time limit for sending the SMTP ".", and for receiving
-the server response.
+The Postfix SMTP client time limit for sending the SMTP ".", and
+for receiving the remote SMTP server response.
</p>
<p>
%PARAM smtp_data_init_timeout 120s
<p>
-The SMTP client time limit for sending the SMTP DATA command, and for
-receiving the server response.
+The Postfix SMTP client time limit for sending the SMTP DATA command,
+and for receiving the remote SMTP server response.
</p>
<p>
%PARAM smtp_data_xfer_timeout 180s
<p>
-The SMTP client time limit for sending the SMTP message content.
+The Postfix SMTP client time limit for sending the SMTP message content.
When the connection makes no progress for more than $smtp_data_xfer_timeout
seconds the Postfix SMTP client terminates the transfer.
</p>
</p>
<p>
-Note: Postfix always ignores MX records with equal or worse preference
+Note: the Postfix SMTP client always ignores MX records with equal
+or worse preference
than the local MTA itself.
</p>
%PARAM smtp_helo_timeout 300s
<p>
-The SMTP client time limit for sending the HELO or EHLO command,
-and for receiving the initial server response.
+The Postfix SMTP client time limit for sending the HELO or EHLO command,
+and for receiving the initial remote SMTP server response.
</p>
<p>
%PARAM smtp_mail_timeout 300s
<p>
-The SMTP client time limit for sending the MAIL FROM command, and
-for receiving the server response.
+The Postfix SMTP client time limit for sending the MAIL FROM command,
+and for receiving the remote SMTP server response.
</p>
<p>
<p>
The maximal number of MX (mail exchanger) IP addresses that can
-result from mail exchanger lookups, or zero (no limit). Prior to
+result from Postfix SMTP client mail exchanger lookups, or zero (no
+limit). Prior to
Postfix version 2.3, this limit was disabled by default.
</p>
%PARAM smtp_mx_session_limit 2
<p> The maximal number of SMTP sessions per delivery request before
-giving up or delivering to a fall-back relay host, or zero (no
+the Postfix SMTP client
+gives up or delivers to a fall-back relay host, or zero (no
limit). This restriction ignores sessions that fail to complete the
SMTP initial handshake (Postfix version 2.2 and earlier) or that fail to
complete the EHLO and TLS handshake (Postfix version 2.3 and later). </p>
%PARAM smtp_quit_timeout 300s
<p>
-The SMTP client time limit for sending the QUIT command, and for
-receiving the server response.
+The Postfix SMTP client time limit for sending the QUIT command,
+and for receiving the remote SMTP server response.
</p>
<p>
%PARAM smtp_quote_rfc821_envelope yes
<p>
-Quote addresses in SMTP MAIL FROM and RCPT TO commands as required
+Quote addresses in Postfix SMTP client MAIL FROM and RCPT TO commands
+as required
by RFC 2821. This includes putting quotes around an address localpart
that ends in ".".
</p>
%PARAM smtp_rcpt_timeout 300s
<p>
-The SMTP client time limit for sending the SMTP RCPT TO command, and
-for receiving the server response.
+The Postfix SMTP client time limit for sending the SMTP RCPT TO
+command, and for receiving the remote SMTP server response.
</p>
<p>
%PARAM smtp_sasl_password_maps
<p>
-Optional SMTP client lookup tables with one username:password entry
+Optional Postfix SMTP client lookup tables with one username:password
+entry
per remote hostname or domain, or sender address when sender-dependent
authentication is enabled. If no username:password entry is found,
then the Postfix SMTP client will not
</p>
<p>
-This allows an "smtp" delivery agent, used for injecting mail into
+This allows a Postfix SMTP delivery agent, used for injecting mail
+into
a content filter, to forward the name, address, protocol and HELO
name of the original client to the content filter and downstream
queuing SMTP server. This can produce more useful logging than
</p>
<p>
-By default, Postfix moves on the next mail exchanger. Specify
+By default, the Postfix SMTP client moves on the next mail exchanger.
+Specify
"smtp_skip_4xx_greeting = no" if Postfix should defer delivery
immediately.
</p>
<p> This feature is available in Postfix 2.0 and earlier.
-Later Postfix versions always skip SMTP servers that greet with a
+Later Postfix versions always skip remote SMTP servers that greet
+with a
4XX status code. </p>
%PARAM smtp_skip_5xx_greeting yes
<p>
-Skip SMTP servers that greet with a 5XX status code (go away, do
+Skip remote SMTP servers that greet with a 5XX status code (go away,
+do
not try again later).
</p>
%PARAM smtp_xforward_timeout 300s
<p>
-The SMTP client time limit for sending the XFORWARD command, and
-for receiving the server response.
+The Postfix SMTP client time limit for sending the XFORWARD command,
+and for receiving the remote SMTP server response.
</p>
<p>
%PARAM authorized_verp_clients $mynetworks
-<p> What SMTP clients are allowed to specify the XVERP command.
+<p> What remote SMTP clients are allowed to specify the XVERP command.
This command requests that mail be delivered one recipient at a
time with a per recipient return address. </p>
%PARAM smtpd_authorized_verp_clients $authorized_verp_clients
-<p> What SMTP clients are allowed to specify the XVERP command.
+<p> What remote SMTP clients are allowed to specify the XVERP command.
This command requests that mail be delivered one recipient at a
time with a per recipient return address. </p>
%PARAM smtpd_authorized_xclient_hosts
<p>
-What SMTP clients are allowed to use the XCLIENT feature. This
-command overrides SMTP client information that is used for access
+What remote SMTP clients are allowed to use the XCLIENT feature. This
+command overrides remote SMTP client information that is used for access
control. Typical use is for SMTP-based content filters, fetchmail-like
programs, or SMTP server access rule testing. See the XCLIENT_README
document for details.
%PARAM smtpd_authorized_xforward_hosts
<p>
-What SMTP clients are allowed to use the XFORWARD feature. This
+What remote SMTP clients are allowed to use the XFORWARD feature. This
command forwards information that is used to improve logging after
SMTP-based content filters. See the XFORWARD_README document for
details.
%PARAM smtpd_client_restrictions
<p>
-Optional SMTP server access restrictions in the context of a client
-SMTP connection request.
+Optional Postfix SMTP server access restrictions in the context of
+a remote SMTP client connection request.
See SMTPD_ACCESS_README, section "Delayed evaluation of SMTP access
restriction lists" for a discussion of evaluation context and time.
</p>
<dt><b><a name="check_ccert_access">check_ccert_access</a> <i><a href="DATABASE_README.html">type:table</a></i></b></dt>
-<dd> Use the client certificate fingerprint as lookup key for the
-specified access(5) database; with Postfix version 2.2, also require that
-the SMTP client certificate is verified successfully.
+<dd> Use the remote SMTP client certificate fingerprint or the public key
+fingerprint (Postfix 2.9 and later) as lookup key for the specified
+access(5) database; with Postfix version 2.2, also require that the
+remote SMTP client certificate is verified successfully.
The fingerprint digest algorithm is configurable via the
smtpd_tls_fingerprint_digest parameter (hard-coded as md5 prior to
Postfix version 2.5). This feature is available with Postfix version
<dt><b><a name="permit_tls_clientcerts">permit_tls_clientcerts</a></b></dt>
<dd>Permit the request when the remote SMTP client certificate
-fingerprint is listed in $relay_clientcerts.
+fingerprint or public key fingerprint (Postfix 2.9 and later) is
+listed in $relay_clientcerts.
The fingerprint digest algorithm is configurable via the
smtpd_tls_fingerprint_digest parameter (hard-coded as md5 prior to
Postfix version 2.5). This feature is available with Postfix version
<p>
How long the postkick(1) command waits for a request to enter the
-server's input buffer before giving up.
+Postfix daemon process input buffer before giving up.
</p>
<p>
%PARAM broken_sasl_auth_clients no
<p>
-Enable inter-operability with SMTP clients that implement an obsolete
+Enable inter-operability with remote SMTP clients that implement an obsolete
version of the AUTH command (RFC 4954). Examples of such clients
are MicroSoft Outlook Express version 4 and MicroSoft Exchange
version 5.0.
<p>
The effectiveness of cached connections will be determined by the
-number of LMTP servers in use, and the concurrency limit specified
-for the LMTP client. Cached connections are closed under any of
+number of remote LMTP servers in use, and the concurrency limit specified
+for the Postfix LMTP client. Cached connections are closed under any of
the following conditions:
</p>
<ul>
-<li> The LMTP client idle time limit is reached. This limit is
+<li> The Postfix LMTP client idle time limit is reached. This limit is
specified with the Postfix max_idle configuration parameter.
<li> A delivery request specifies a different destination than the
reached. This limit is specified with the Postfix max_use
configuration parameter.
-<li> Upon the onset of another delivery request, the LMTP server
+<li> Upon the onset of another delivery request, the remote LMTP server
associated with the current session does not respond to the RSET
command.
</ul>
<p>
-Most of these limitations will be removed after Postfix implements
+Most of these limitations have been with the Postfix
a connection cache that is shared among multiple LMTP client
programs.
</p>
%PARAM lmtp_sasl_password_maps
<p>
-Optional LMTP client lookup tables with one username:password entry
+Optional Postfix LMTP client lookup tables with one username:password entry
per host or domain. If a remote host or domain has no username:password
entry, then the Postfix LMTP client will not attempt to authenticate
to the remote host.
"trust" only the local machine. </p>
<li><p>Specify "mynetworks_style = subnet" when Postfix
-should "trust" SMTP clients in the same IP subnetworks as the local
+should "trust" remote SMTP clients in the same IP subnetworks as the local
machine. On Linux, this works correctly only with interfaces
specified with the "ifconfig" command. </p>
<li><p>Specify "mynetworks_style = class" when Postfix should
-"trust" SMTP clients in the same IP class A/B/C networks as the
+"trust" remote SMTP clients in the same IP class A/B/C networks as the
local machine. Don't do this with a dialup site - it would cause
Postfix to "trust" your entire provider's network. Instead, specify
an explicit mynetworks list by hand, as described with the mynetworks
%PARAM smtp_rset_timeout 20s
-<p> The SMTP client time limit for sending the RSET command, and
-for receiving the server response. The SMTP client sends RSET in
+<p> The Postfix SMTP client time limit for sending the RSET command,
+and for receiving the remote SMTP server response. The SMTP client
+sends RSET in
order to finish a recipient address probe, or to verify that a
cached session is still usable. </p>
%PARAM unknown_virtual_alias_reject_code 550
<p>
-The SMTP server reply code when a recipient address matches
+The Postfix SMTP server reply code when a recipient address matches
$virtual_alias_domains, and $virtual_alias_maps specifies a list
of lookup tables that does not match the recipient address.
</p>
%PARAM unknown_virtual_mailbox_reject_code 550
<p>
-The SMTP server reply code when a recipient address matches
+The Postfix SMTP server reply code when a recipient address matches
$virtual_mailbox_domains, and $virtual_mailbox_maps specifies a list
of lookup tables that does not match the recipient address.
</p>
%PARAM smtpd_discard_ehlo_keywords
<p> A case insensitive list of EHLO keywords (pipelining, starttls,
-auth, etc.) that the SMTP server will not send in the EHLO response
+auth, etc.) that the Postfix SMTP server will not send in the EHLO
+response
to a remote SMTP client. </p>
<p> This feature is available in Postfix 2.2 and later. </p>
<p> Lookup tables, indexed by the remote SMTP client address, with
case insensitive lists of EHLO keywords (pipelining, starttls, auth,
-etc.) that the SMTP server will not send in the EHLO response to a
+etc.) that the Postfix SMTP server will not send in the EHLO response
+to a
remote SMTP client. See smtpd_discard_ehlo_keywords for details.
The table is not searched by hostname for robustness reasons. </p>
<dt><b>permit_tls_clientcerts </b></dt>
<dd> Append the domain name in $myorigin or $mydomain when the
-client TLS certificate fingerprint is listed in $relay_clientcerts.
+remote SMTP client TLS certificate fingerprint or public key fingerprint
+(Postfix 2.9 and later) is listed in $relay_clientcerts.
The fingerprint digest algorithm is configurable via the
smtpd_tls_fingerprint_digest parameter (hard-coded as md5 prior to
Postfix version 2.5). </dd>
<dt><b>permit_tls_all_clientcerts </b></dt>
<dd> Append the domain name in $myorigin or $mydomain when the
-client TLS certificate is successfully verified, regardless of
+remote SMTP client TLS certificate is successfully verified, regardless of
whether it is listed on the server, and regardless of the certifying
authority. </dd>
<dl compact>
-<dt> </dt> <dd> 0 Disable logging of TLS activity. </dd>
+<dt> </dt> <dd> 0 Log only a summary message on TLS handshake completion
+— no logging of remote SMTP client certificate trust-chain verification
+errors
+if client certificate verification is not required. With Postfix 2.8
+and earlier, disable logging of TLS activity. </dd>
-<dt> </dt> <dd> 1 Log TLS handshake and certificate information. </dd>
+<dt> </dt> <dd> 1 Also log trust-chain verification errors and peer
+certificate name and issuer. With Postfix 2.8 and earlier, log TLS
+handshake and certificate information. </dd>
-<dt> </dt> <dd> 2 Log levels during TLS negotiation. </dd>
+<dt> </dt> <dd> 2 Also log levels during TLS negotiation. </dd>
-<dt> </dt> <dd> 3 Log hexadecimal and ASCII dump of TLS negotiation
-process. </dd>
+<dt> </dt> <dd> 3 Also log hexadecimal and ASCII dump of TLS negotiation
+process. </dd>
<dt> </dt> <dd> 4 Also log hexadecimal and ASCII dump of complete
transmission after STARTTLS. </dd>
</dl>
-<p> Use "smtpd_tls_loglevel = 3" only in case of problems. Use of
-loglevel 4 is strongly discouraged. </p>
+<p> Do not use "smtpd_tls_loglevel = 2" or higher except in case
+of problems. Use of loglevel 4 is strongly discouraged. </p>
<p> This feature is available in Postfix 2.2 and later. </p>
<p> Request that the Postfix SMTP server produces Received: message
headers that include information about the protocol and cipher used,
-as well as the client CommonName and client certificate issuer
+as well as the remote SMTP client CommonName and client certificate issuer
CommonName. This is disabled by default, as the information may
be modified in transit through other mail servers. Only information
that was recorded by the final destination can be trusted. </p>
%PARAM smtpd_use_tls no
-<p> Opportunistic TLS: announce STARTTLS support to SMTP clients,
+<p> Opportunistic TLS: announce STARTTLS support to remote SMTP clients,
but do not require that clients use TLS encryption. </p>
<p> Note: when invoked via "<b>sendmail -bs</b>", Postfix will never offer
%PARAM smtpd_enforce_tls no
-<p> Mandatory TLS: announce STARTTLS support to SMTP clients,
+<p> Mandatory TLS: announce STARTTLS support to remote SMTP clients,
and require that clients use TLS encryption. According to RFC 2487
this MUST NOT be applied in case of a publicly-referenced SMTP
server. This option is therefore off by default. </p>
%PARAM relay_clientcerts
-<p> List of tables with remote SMTP client-certificate fingerprints
-for which the Postfix SMTP server will allow access with the
-permit_tls_clientcerts feature.
-The fingerprint digest algorithm is configurable via the
+<p> List of tables with remote SMTP client-certificate fingerprints or
+public key fingerprints (Postfix 2.9 and later) for which the Postfix
+SMTP server will allow access with the permit_tls_clientcerts
+feature. The fingerprint digest algorithm is configurable via the
smtpd_tls_fingerprint_digest parameter (hard-coded as md5 prior to
Postfix version 2.5). </p>
<dl compact>
-<dt> </dt> <dd> 0 Disable logging of TLS activity. </dd>
+<dt> </dt> <dd> 0 Log only a summary message on TLS handshake completion
+— no logging of remote SMTP server certificate trust-chain
+verification errors if server certificate verification is not required.
+With Postfix 2.8 and earlier, disable logging of TLS activity. </dd>
-<dt> </dt> <dd> 1 Log TLS handshake and certificate information. </dd>
+<dt> </dt> <dd> 1 Also log remote SMTP server trust-chain verification
+errors and peer certificate summary information. With Postfix 2.8
+and earlier, log TLS handshake and certificate information. </dd>
-<dt> </dt> <dd> 2 Log levels during TLS negotiation. </dd>
+<dt> </dt> <dd> 2 Also log levels during TLS negotiation. </dd>
-<dt> </dt> <dd> 3 Log hexadecimal and ASCII dump of TLS negotiation
+<dt> </dt> <dd> 3 Also log hexadecimal and ASCII dump of TLS negotiation
process. </dd>
-<dt> </dt> <dd> 4 Log hexadecimal and ASCII dump of complete
+<dt> </dt> <dd> 4 Also log hexadecimal and ASCII dump of complete
transmission after STARTTLS. </dd>
</dl>
-<p> Use "smtp_tls_loglevel = 3" only in case of problems. Use of
-loglevel 4 is strongly discouraged. </p>
+<p> Do not use "smtp_tls_loglevel = 2" or higher except in case of
+problems. Use of loglevel 4 is strongly discouraged. </p>
<p> This feature is available in Postfix 2.2 and later. </p>
%PARAM smtp_generic_maps
<p> Optional lookup tables that perform address rewriting in the
-SMTP client, typically to transform a locally valid address into
+Postfix SMTP client, typically to transform a locally valid address into
a globally valid address when sending mail across the Internet.
This is needed when the local machine does not have its own Internet
domain name, but uses something like <i>localdomain.local</i>
<p> Lookup tables, indexed by the remote LMTP server address, with
case insensitive lists of LHLO keywords (pipelining, starttls,
-auth, etc.) that the LMTP client will ignore in the LHLO response
+auth, etc.) that the Postfix LMTP client will ignore in the LHLO
+response
from a remote LMTP server. See lmtp_discard_lhlo_keywords for
details. The table is not indexed by hostname for consistency with
smtpd_discard_ehlo_keyword_address_maps. </p>
%PARAM lmtp_discard_lhlo_keywords
<p> A case insensitive list of LHLO keywords (pipelining, starttls,
-auth, etc.) that the LMTP client will ignore in the LHLO response
+auth, etc.) that the Postfix LMTP client will ignore in the LHLO
+response
from a remote LMTP server. </p>
<p> This feature is available in Postfix 2.3 and later. </p>
%PARAM lmtp_lhlo_timeout 300s
-<p> The LMTP client time limit for sending the LHLO command, and
-for receiving the initial server response. </p>
+<p> The Postfix LMTP client time limit for sending the LHLO command,
+and for receiving the initial remote LMTP server response. </p>
<p> Time units: s (seconds), m (minutes), h (hours), d (days), w
(weeks). The default time unit is s (seconds). </p>
<p> Postpone the start of an SMTP mail transaction until a valid
RCPT TO command is received. Specify "no" to create a mail transaction
-as soon as the SMTP server receives a valid MAIL FROM command. </p>
+as soon as the Postfix SMTP server receives a valid MAIL FROM
+command. </p>
<p> With sites that reject lots of mail, the default setting reduces
the use of
level, there are no trusted certificate authorities. The certificate
trust chain, expiration date, ... are not checked. Instead,
the optional <b>match</b> attribute, or else the main.cf
-<b>smtp_tls_fingerprint_cert_match</b> parameter, lists the
-valid "fingerprints" of the server certificate. The digest
+<b>smtp_tls_fingerprint_cert_match</b> parameter, lists the certificate
+fingerprints or the public key fingerprint (Postfix 2.9 and later)
+of the valid server certificate. The digest
algorithm used to calculate the fingerprint is selected by the
<b>smtp_tls_fingerprint_digest</b> parameter. Multiple fingerprints can
be combined with a "|" delimiter in a single match attribute, or multiple
%PARAM smtp_tls_verify_cert_match hostname
-<p> The server certificate peername verification method for the
+<p> How the Postfix SMTP client verifies the server certificate
+peername for the
"verify" TLS security level. In a "verify" TLS policy table
($smtp_tls_policy_maps) entry the optional "match" attribute
overrides this main.cf setting. </p>
%PARAM smtp_tls_secure_cert_match nexthop, dot-nexthop
-<p> The server certificate peername verification method for the
+<p> How the Postfix SMTP client verifies the server certificate
+peername for the
"secure" TLS security level. In a "secure" TLS policy table
($smtp_tls_policy_maps) entry the optional "match" attribute
overrides this main.cf setting. </p>
<dt><b>fingerprint</b></dt> <dd>Certificate fingerprint
verification. Available with Postfix 2.5 and later. At this security
level, there are no trusted certificate authorities. The certificate
-trust chain, expiration date, ... are not checked. Instead,
-the <b>smtp_tls_fingerprint_cert_match</b> parameter lists
-the valid "fingerprints" of the server certificate. The digest
+trust chain, expiration date, ... are not checked. Instead, the
+<b>smtp_tls_fingerprint_cert_match</b> parameter lists the certificate
+fingerprint or public key fingerprint (Postfix 2.9 and later) of
+the valid server certificate. The digest
algorithm used to calculate the fingerprint is selected by the
<b>smtp_tls_fingerprint_digest</b> parameter. </dd>
<p> The underlying cipherlists for grades other than "null" include
anonymous ciphers, but these are automatically filtered out if the
-server is configured to ask for client certificates. You are very
+server is configured to ask for remote SMTP client certificates. You are very
unlikely to need to take any steps to exclude anonymous ciphers, they
are excluded automatically as required. If you must exclude anonymous
ciphers even when Postfix does not need or use peer certificates, set
%PARAM smtpd_tls_mandatory_exclude_ciphers
<p> Additional list of ciphers or cipher types to exclude from the
-SMTP server cipher list at mandatory TLS security levels. This list
+Postfix SMTP server cipher list at mandatory TLS security levels.
+This list
works in addition to the exclusions listed with smtpd_tls_exclude_ciphers
(see there for syntax details). </p>
%PARAM smtp_tls_mandatory_exclude_ciphers
<p> Additional list of ciphers or cipher types to exclude from the
-SMTP client cipher list at mandatory TLS security levels. This list
+Postfix SMTP client cipher list at mandatory TLS security levels. This list
works in addition to the exclusions listed with smtp_tls_exclude_ciphers
(see there for syntax details). </p>
<dt><b>none</b></dt> <dd> TLS will not be used. </dd>
<dt><b>may</b></dt> <dd> Opportunistic TLS: announce STARTTLS support
-to SMTP clients, but do not require that clients use TLS encryption.
+to remote SMTP clients, but do not require that clients use TLS encryption.
</dd>
<dt><b>encrypt</b></dt> <dd>Mandatory TLS encryption: announce
-STARTTLS support to SMTP clients, and require that clients use TLS
+STARTTLS support to remote SMTP clients, and require that clients use TLS
encryption. According to RFC 2487 this MUST NOT be applied in case
of a publicly-referenced SMTP server. Instead, this option should
be used only on dedicated servers. </dd>
<p> Note 1: the "fingerprint", "verify" and "secure" levels are not
supported here.
The Postfix SMTP server logs a warning and uses "encrypt" instead.
-To verify SMTP client certificates, see TLS_README for a discussion
+To verify remote SMTP client certificates, see TLS_README for a discussion
of the smtpd_tls_ask_ccert, smtpd_tls_req_ccert, and permit_tls_clientcerts
features. </p>
<p> With Postfix 2.3 and later the Postfix SMTP server can disable
session id generation when TLS session caching is turned off. This
-keeps clients from caching sessions that almost certainly cannot
+keeps remote SMTP clients from caching sessions that almost certainly cannot
be re-used. </p>
<p> By default, the Postfix SMTP server always generates TLS session
<p> The message digest algorithm used to construct remote SMTP server
certificate fingerprints. At the "fingerprint" TLS security level
(<b>smtp_tls_security_level</b> = fingerprint), the server certificate is
-verified by directly matching its <i>fingerprint</i>. The fingerprint
-is the message digest of the server certificate using the selected
+verified by directly matching its certificate fingerprint or its public
+key fingerprint (Postfix 2.9 and later). The fingerprint is the
+message digest of the server certificate (or its public key)
+using the selected
algorithm. With a digest algorithm resistant to "second pre-image"
attacks, it is not feasible to create a new public key and a matching
-certificate that has the same fingerprint. </p>
+certificate (or public/private key-pair) that has the same fingerprint. </p>
<p> The default algorithm is <b>md5</b>; this is consistent with
the backwards compatible setting of the digest used to verify client
</pre>
</blockquote>
+<p> Public key fingerprints are more difficult to extract, however,
+the SHA-1 public key fingerprint is often present as the value of the
+"Subject Key Identifier" extension in X.509v3 certificates. The Postfix
+SMTP server and client log the peer certificate fingerprint and public
+key fingerprint when TLS loglevel is 1 or higher. </p>
+
<p> This feature is available in Postfix 2.5 and later. </p>
%PARAM smtp_tls_fingerprint_cert_match
-<p> List of acceptable remote SMTP server certificate fingerprints
-for the "fingerprint" TLS security level (<b>smtp_tls_security_level</b> =
-fingerprint). At this security level, certificate authorities are
-not used, and certificate expiration times are ignored. Instead,
-server certificates are verified directly via their "fingerprint". The
-fingerprint is a message digest of the server certificate. The digest
-algorithm is selected via the <b>smtp_tls_fingerprint_digest</b>
+<p> List of acceptable remote SMTP server certificate fingerprints for
+the "fingerprint" TLS security level (<b>smtp_tls_security_level</b> =
+fingerprint). At this security level, certificate authorities are not
+used, and certificate expiration times are ignored. Instead, server
+certificates are verified directly via their certificate fingerprint
+or public key fingerprint (Postfix 2.9 and later). The fingerprint
+is a message digest of the server certificate (or public key). The
+digest algorithm is selected via the <b>smtp_tls_fingerprint_digest</b>
parameter. </p>
<p> When an <b>smtp_tls_policy_maps</b> table entry specifies the
%PARAM smtpd_tls_fingerprint_digest md5
-<p> The message digest algorithm used to construct client-certificate
-fingerprints for <b>check_ccert_access</b> and
-<b>permit_tls_clientcerts</b>. The default algorithm is <b>md5</b>,
-for backwards compatibility with Postfix releases prior to 2.5.
-</p>
+<p> The message digest algorithm to construct remote SMTP
+client-certificate
+fingerprints or public key fingerprints (Postfix 2.9 and later)
+for <b>check_ccert_access</b> and <b>permit_tls_clientcerts</b>. The
+default algorithm is <b>md5</b>, for backwards compatibility with Postfix
+releases prior to 2.5. </p>
<p> Advances in hash
function cryptanalysis have led to md5 being deprecated in favor of sha1.
</pre>
</blockquote>
+<p> Public key fingerprints are more difficult to extract, however,
+the SHA-1 public key fingerprint is often present as the value of the
+"Subject Key Identifier" extension in X.509v3 certificates. The Postfix
+SMTP server and client log the peer certificate fingerprint and public
+key fingerprint when TLS loglevel is 1 or higher. </p>
+
<p> Example: client-certificate access table, with sha1 fingerprints: </p>
<blockquote>
%PARAM tls_eecdh_strong_curve prime256v1
-<p> The elliptic curve used by the SMTP server for sensibly strong
+<p> The elliptic curve used by the Postfix SMTP server for sensibly
+strong
ephemeral ECDH key exchange. This curve is used by the Postfix SMTP
server when "smtpd_tls_eecdh_grade = strong". The phrase "sensibly
strong" means approximately 128-bit security based on best known
%PARAM tls_eecdh_ultra_curve secp384r1
-<p> The elliptic curve used by the SMTP server for maximally strong
+<p> The elliptic curve used by the Postfix SMTP server for maximally
+strong
ephemeral ECDH key exchange. This curve is used by the Postfix SMTP
server when "smtpd_tls_eecdh_grade = ultra". The phrase "maximally
strong" means approximately 192-bit security based on best known attacks.
%PARAM lmtp_assume_final no
-<p> When an LMTP server announces no DSN support, assume that the
+<p> When a remote LMTP server announces no DSN support, assume that
+the
server performs final delivery, and send "delivered" delivery status
notifications instead of "relayed". The default setting is backwards
compatible to avoid the infinetisimal possibility of breaking
%PARAM postscreen_post_queue_limit $default_process_limit
<p> The number of clients that can be waiting for service from a
-real SMTP server process. When this queue is full, all clients will
+real Postfix SMTP server process. When this queue is full, all
+clients will
receive a 421 reponse. </p>
<p> This feature is available in Postfix 2.8. </p>
%PARAM postscreen_pre_queue_limit $default_process_limit
<p> The number of non-whitelisted clients that can be waiting for
-a decision whether they will receive service from a real SMTP server
+a decision whether they will receive service from a real Postfix
+SMTP server
process. When this queue is full, all non-whitelisted clients will
receive a 421 reponse. </p>
<p> When a client's score is equal to or greater than the threshold
specified with postscreen_dnsbl_threshold, postscreen(8) can drop
-the connection with the SMTP client. </p>
+the connection with the remote SMTP client. </p>
<p> Specify a list of domain=filter*weight entries, separated by
comma or whitespace. </p>
or more ";"-separated numbers or number..number ranges. </p>
<li> <p> When no "*weight" is specified, postscreen(8) increments
-the SMTP client's DNSBL score by 1. Otherwise, the weight must be
+the remote SMTP client's DNSBL score by 1. Otherwise, the weight must be
an integral number, and postscreen(8) adds the specified weight to
-the SMTP client's DNSBL score. Specify a negative number for
+the remote SMTP client's DNSBL score. Specify a negative number for
whitelisting. </p>
<li> <p> When one postscreen_dnsbl_sites entry produces multiple
%PARAM postscreen_dnsbl_action ignore
-<p>The action that postscreen(8) takes when an SMTP client's combined
+<p>The action that postscreen(8) takes when a remote SMTP client's combined
DNSBL score is equal to or greater than a threshold (as defined
with the postscreen_dnsbl_sites and postscreen_dnsbl_threshold
parameters). Specify one of the following: </p>
%PARAM postscreen_greet_action ignore
-<p>The action that postscreen(8) takes when an SMTP client speaks
+<p>The action that postscreen(8) takes when a remote SMTP client speaks
before its turn within the time specified with the postscreen_greet_wait
parameter. Specify one of the following: </p>
</dl>
-<p> In either case, postscreen(8) will not whitelist the SMTP client
+<p> In either case, postscreen(8) will not whitelist the remote SMTP client
IP address. </p>
<p> This feature is available in Postfix 2.8. </p>
%PARAM postscreen_blacklist_action ignore
-<p> The action that postscreen(8) takes when an SMTP client is
+<p> The action that postscreen(8) takes when a remote SMTP client is
permanently blacklisted with the postscreen_access_list parameter.
Specify one of the following: </p>
%PARAM postscreen_dnsbl_threshold 1
-<p> The inclusive lower bound for blocking an SMTP client, based on
+<p> The inclusive lower bound for blocking a remote SMTP client, based on
its combined DNSBL score as defined with the postscreen_dnsbl_sites
parameter. </p>
%PARAM postscreen_pipelining_action enforce
-<p> The action that postscreen(8) takes when an SMTP client sends
+<p> The action that postscreen(8) takes when a remote SMTP client
+sends
multiple commands instead of sending one command and waiting for
the server to respond. Specify one of the following: </p>
%PARAM postscreen_watchdog_timeout 10s
<p> How much time a postscreen(8) process may take to respond to
-an SMTP client command or to perform a cache operation before it
+a remote SMTP client command or to perform a cache operation before it
is terminated by a built-in watchdog timer. This is a safety
mechanism that prevents postscreen(8) from becoming non-responsive
due to a bug in Postfix itself or in system software. To avoid
%PARAM postscreen_non_smtp_command_action drop
-<p> The action that postscreen(8) takes when an SMTP client sends
+<p> The action that postscreen(8) takes when a remote SMTP client sends
non-SMTP commands as specified with the postscreen_forbidden_commands
parameter. Specify one of the following: </p>
%PARAM postscreen_bare_newline_action ignore
-<p> The action that postscreen(8) takes when an SMTP client sends
+<p> The action that postscreen(8) takes when a remote SMTP client sends
a bare newline character, that is, a newline not preceded by carriage
return. Specify one of the following: </p>
<p> The amount of time that postscreen(8) will use the result from
a successful "bare newline" SMTP protocol test. During this
time, the client IP address is excluded from this test. The default
-is long because a client must disconnect after it passes the test,
+is long because a remote SMTP client must disconnect after it passes
+the test,
before it can talk to a real Postfix SMTP server. </p>
<p> Specify a non-zero time value (an integral value plus an optional
%PARAM postscreen_bare_newline_enable no
<p> Enable "bare newline" SMTP protocol tests in the postscreen(8)
-server. These tests are expensive: a client must disconnect after
+server. These tests are expensive: a remote SMTP client must
+disconnect after
it passes the test, before it can talk to a real Postfix SMTP server.
</p>
%PARAM postscreen_client_connection_count_limit $smtpd_client_connection_count_limit
-<p> How many simultaneous connections any client is allowed to have
+<p> How many simultaneous connections any remote SMTP client is
+allowed to have
with the postscreen(8) daemon. By default, this limit is the same
as with the Postfix SMTP server. Note that the triage process can
take several seconds, with the time spent in postscreen_greet_wait
%PARAM tls_preempt_cipherlist no
-<p> With SSLv3 and later, use the server's cipher preference order
-instead of the client's cipher preference order. </p>
+<p> With SSLv3 and later, use the Postfix SMTP server's cipher
+preference order instead of the remote client's cipher preference
+order. </p>
<p> By default, the OpenSSL server selects the client's most preferred
cipher that the server supports. With SSLv3 and later, the server may
%PARAM postscreen_use_tls $smtpd_use_tls
-<p> Opportunistic TLS: announce STARTTLS support to SMTP clients,
+<p> Opportunistic TLS: announce STARTTLS support to remote SMTP clients,
but do not require that clients use TLS encryption. </p>
<p> This feature is available in Postfix 2.8 and later.
%PARAM postscreen_enforce_tls $smtpd_enforce_tls
-<p> Mandatory TLS: announce STARTTLS support to SMTP clients, and
+<p> Mandatory TLS: announce STARTTLS support to remote SMTP clients, and
require that clients use TLS encryption. See smtpd_postscreen_enforce_tls
for details. </p>
%PARAM tlsproxy_enforce_tls $smtpd_enforce_tls
-<p> Mandatory TLS: announce STARTTLS support to SMTP clients, and
+<p> Mandatory TLS: announce STARTTLS support to remote SMTP clients, and
require that clients use TLS encryption. See smtpd_enforce_tls for
further details. </p>
%PARAM tlsproxy_tls_fingerprint_digest $smtpd_tls_fingerprint_digest
-<p> The message digest algorithm used to construct client-certificate
+<p> The message digest algorithm to construct remote SMTP
+client-certificate
fingerprints. See smtpd_tls_fingerprint_digest for further details.
</p>
%PARAM tlsproxy_use_tls $smtpd_use_tls
-<p> Opportunistic TLS: announce STARTTLS support to SMTP clients,
+<p> Opportunistic TLS: announce STARTTLS support to remote SMTP clients,
but do not require that clients use TLS encryption. See smtpd_use_tls
for further details. </p>
%PARAM smtpd_reject_footer
-<p> Optional information that is appended after each SMTP server
+<p> Optional information that is appended after each Postfix SMTP
+server
4XX or 5XX response. </p>
<p> Example: </p>
%PARAM postscreen_reject_footer $smtpd_reject_footer
-<p> Optional information that is appended after a 4XX or 5XX server
+<p> Optional information that is appended after a 4XX or 5XX
+postscreen(8) server
response. See smtpd_reject_footer for further details. </p>
<p> This feature is available in Postfix 2.8 and later. </p>
%PARAM postscreen_whitelist_interfaces static:all
<p> A list of local postscreen(8) server IP addresses where a
-non-whitelisted SMTP client can obtain postscreen(8)'s temporary
+non-whitelisted remote SMTP client can obtain postscreen(8)'s temporary
whitelist status. This status is required before the client can
talk to a Postfix SMTP server process. By default, a client can
obtain postscreen(8)'s whitelist status on any local postscreen(8)
extern char *var_smtpd_tls_eecdh;
#define VAR_SMTPD_TLS_LOGLEVEL "smtpd_tls_loglevel"
-#define DEF_SMTPD_TLS_LOGLEVEL 0
-extern int var_smtpd_tls_loglevel;
+#define DEF_SMTPD_TLS_LOGLEVEL "0"
+extern char *var_smtpd_tls_loglevel;
#define VAR_SMTPD_TLS_RECHEAD "smtpd_tls_received_header"
#define DEF_SMTPD_TLS_RECHEAD 0
extern char *var_smtp_tls_fpt_dgst;
#define VAR_SMTP_TLS_LOGLEVEL "smtp_tls_loglevel"
-#define DEF_SMTP_TLS_LOGLEVEL 0
+#define DEF_SMTP_TLS_LOGLEVEL "0"
#define VAR_LMTP_TLS_LOGLEVEL "lmtp_tls_loglevel"
-#define DEF_LMTP_TLS_LOGLEVEL 0
-extern int var_smtp_tls_loglevel; /* In smtp(8) and tlsmgr(8) */
-extern int var_lmtp_tls_loglevel; /* In tlsmgr(8) */
+#define DEF_LMTP_TLS_LOGLEVEL "0"
+extern char *var_smtp_tls_loglevel; /* In smtp(8) and tlsmgr(8) */
+extern char *var_lmtp_tls_loglevel; /* In tlsmgr(8) */
#define VAR_SMTP_TLS_NOTEOFFER "smtp_tls_note_starttls_offer"
#define DEF_SMTP_TLS_NOTEOFFER 0
#define VAR_TLSP_TLS_LOGLEVEL "tlsproxy_tls_loglevel"
#define DEF_TLSP_TLS_LOGLEVEL "$" VAR_SMTPD_TLS_LOGLEVEL
-extern int var_tlsp_tls_loglevel;
+extern char *var_tlsp_tls_loglevel;
#define VAR_TLSP_TLS_RECHEAD "tlsproxy_tls_received_header"
#define DEF_TLSP_TLS_RECHEAD "$" VAR_SMTPD_TLS_RECHEAD
#define MAIL_ATTR_CCERT_SUBJECT "ccert_subject"
#define MAIL_ATTR_CCERT_ISSUER "ccert_issuer"
#define MAIL_ATTR_CCERT_FINGERPRINT "ccert_fingerprint"
+#define MAIL_ATTR_CCERT_PKEY_FPRINT "ccert_pubkey_fingerprint"
#define MAIL_ATTR_CRYPTO_PROTOCOL "encryption_protocol"
#define MAIL_ATTR_CRYPTO_CIPHER "encryption_cipher"
#define MAIL_ATTR_CRYPTO_KEYSIZE "encryption_keysize"
#define MAIL_ATTR_PEER_CN "peer_CN"
#define MAIL_ATTR_ISSUER_CN "issuer_CN"
#define MAIL_ATTR_PEER_FPT "peer_fingerprint"
+#define MAIL_ATTR_PEER_PKEY_FPT "peer_pubkey_fingerprint"
#define MAIL_ATTR_PEER_STATUS "peer_status"
#define MAIL_ATTR_CIPHER_PROTOCOL "cipher_protocol"
#define MAIL_ATTR_CIPHER_NAME "cipher_name"
* Patches change both the patchlevel and the release date. Snapshots have no
* patchlevel; they change the release date only.
*/
-#define MAIL_RELEASE_DATE "20111203"
+#define MAIL_RELEASE_DATE "20111205"
#define MAIL_VERSION_NUMBER "2.9"
#ifdef SNAPSHOT
/* NAME
/* verify_sender_addr 3
/* SUMMARY
-/* address verification support
+/* time-dependent probe sender addresses
/* SYNOPSIS
/* #include <verify_sender_addr.h>
/*
/* time-dependent portion is appended to the address localpart
/* specified with the address_verify_sender parameter.
/*
+/* When the address_verify_sender parameter is empty or <>,
+/* the sender address always the empty address (i.e. always
+/* time-independent).
+/*
/* The caller must initialize the address_verify_sender and
/* address_verify_sender_ttl parameter values.
/*
/* make_verify_sender_addr() generates an envelope sender
-/* address for an address verification probe. When the
-/* address_verify_sender parameter is empty or <>, the result
-/* is always the null address.
+/* address for an address verification probe.
/*
/* valid_verify_sender_addr() verifies that the given address
/* is a valid sender address for address verification probes.
-/* When the address_verify_sender parameter is empty or <>,
-/* the match succeeds only if the given address is empty. When
-/* the address is time-dependent, it is allowed to differ by
-/* +/-1 TTL unit from the expected address. The result is a
-/* null pointer when no match is found. Otherwise, the result
-/* is the sender address without the time-dependent portion;
-/* this is the address that should be used for further delivery.
+/* When probe sender addresses are configured to be time-dependent,
+/* the given address is allowed to differ by +/-1 TTL unit
+/* from the expected address. The result is a null pointer
+/* when no match is found. Otherwise, the result is the sender
+/* address without the time-dependent portion; this is the
+/* address that should be used for further delivery.
/* DIAGNOSTICS
-/* Fatal errors: malformed address_verify_sender value.
+/* Fatal errors: malformed address_verify_sender value; out
+/* of memory.
/* LICENSE
/* .ad
/* .fi
/*
* We convert the time-dependent portion to a safe string (no vowels) in a
* reversible manner, so that we can check an incoming address against the
- * previous, current, and next time slot. This allows for some time slippage
- * between multiple MTAs that handle mail for the same site.
+ * current and +/-1 TTL time slot. This allows for some time slippage
+ * between multiple MTAs that handle mail for the same site. We use base 31
+ * so that the time stamp contains B-Z0-9. This simplifies regression tests.
*/
#define VERIFY_BASE 31
/*
- * The time-dependent address verification probe sender address has the form
- * ``fixedvariable@fixed''. The fixed text is taken from var_verify_sender
- * with perhaps domain information appended during address canonicalization.
- * The variable part of the address changes every var_verify_sender_ttl
- * seconds.
+ * We append the time-dependent portion to the localpart of the the address
+ * verification probe sender address, so that the result has the form
+ * ``fixed1variable@fixed2''. There is no delimiter between ``fixed1'' and
+ * ``variable'', because that could make "old" time stamps valid depending
+ * on how the recipient_delimiter feature is configured. The fixed text is
+ * taken from var_verify_sender with perhaps domain information appended
+ * during address canonicalization. The variable part of the address changes
+ * every var_verify_sender_ttl seconds.
*/
char *var_verify_sender; /* "bare" probe sender address */
int var_verify_sender_ttl; /* time between address changes */
{
static VSTRING *verify_sender_buf; /* the complete sender address */
static VSTRING *my_epoch_buf; /* scratch space */
- char *at_domain;
+ char *my_at_domain;
/*
* The null sender is always time-independent.
if (*var_verify_sender == '@')
msg_fatal("parameter %s: value \"%s\" must not start with '@'",
VAR_VERIFY_SENDER, var_verify_sender);
- if ((at_domain = strchr(var_verify_sender, '@')) != 0 && at_domain[1] == 0)
+ if ((my_at_domain = strchr(var_verify_sender, '@')) != 0 && my_at_domain[1] == 0)
msg_fatal("parameter %s: value \"%s\" must not end with '@'",
VAR_VERIFY_SENDER, var_verify_sender);
*/
if (var_verify_sender_ttl > 0) {
/* Strip the @domain portion, if applicable. */
- if (at_domain != 0)
+ if (my_at_domain != 0)
vstring_truncate(verify_sender_buf,
- (ssize_t) (at_domain - var_verify_sender));
+ (ssize_t) (my_at_domain - var_verify_sender));
/* Append the time stamp to the address localpart. */
vstring_sprintf_append(verify_sender_buf, "%s",
safe_ultostr(my_epoch_buf,
VERIFY_SENDER_ADDR_EPOCH(),
VERIFY_BASE, 0, 0));
/* Add back the @domain, if applicable. */
- if (at_domain != 0)
- vstring_sprintf_append(verify_sender_buf, "%s", at_domain);
+ if (my_at_domain != 0)
+ vstring_sprintf_append(verify_sender_buf, "%s", my_at_domain);
}
/*
/* valid_verify_sender_addr - decide if address matches time window +/-1 */
-const char *valid_verify_sender_addr(const char *addr)
+const char *valid_verify_sender_addr(const char *their_addr)
{
- static VSTRING *fixed_sender_buf; /* sender without time stamp */
+ static VSTRING *time_indep_sender_buf; /* sender without time stamp */
ssize_t base_len;
unsigned long my_epoch;
unsigned long their_epoch;
* The null address is always time-independent.
*/
if (*var_verify_sender == 0 || strcmp(var_verify_sender, "<>") == 0)
- return (*addr ? 0 : "");
+ return (*their_addr ? 0 : "");
/*
* One-time initialization. Generate the time-independent address that we
* will return if the match is successful. This address is also used as a
* matching template.
*/
- if (fixed_sender_buf == 0) {
- fixed_sender_buf = vstring_alloc(10);
- vstring_strcpy(fixed_sender_buf, var_verify_sender);
- rewrite_clnt_internal(MAIL_ATTR_RWR_LOCAL, STR(fixed_sender_buf),
- fixed_sender_buf);
+ if (time_indep_sender_buf == 0) {
+ time_indep_sender_buf = vstring_alloc(10);
+ vstring_strcpy(time_indep_sender_buf, var_verify_sender);
+ rewrite_clnt_internal(MAIL_ATTR_RWR_LOCAL, STR(time_indep_sender_buf),
+ time_indep_sender_buf);
}
/*
* Check the time-independent sender localpart.
*/
- if ((my_at_domain = strchr(STR(fixed_sender_buf), '@')) != 0)
- base_len = my_at_domain - STR(fixed_sender_buf);
+ if ((my_at_domain = strchr(STR(time_indep_sender_buf), '@')) != 0)
+ base_len = my_at_domain - STR(time_indep_sender_buf);
else
- base_len = LEN(fixed_sender_buf);
- if (strncasecmp(STR(fixed_sender_buf), addr, base_len) != 0)
+ base_len = LEN(time_indep_sender_buf);
+ if (strncasecmp(STR(time_indep_sender_buf), their_addr, base_len) != 0)
return (0); /* sender localpart mis-match */
/*
* Check the time-independent domain.
*/
- if ((their_at_domain = strchr(addr, '@')) == 0 && my_at_domain != 0)
- return ("domain mis-match"); /* sender domain mis-match */
- if (their_at_domain != 0 && (my_at_domain == 0
- || strcasecmp(their_at_domain, my_at_domain) != 0))
+ if ((their_at_domain = strchr(their_addr, '@')) == 0 && my_at_domain != 0)
+ return (0); /* sender domain mis-match */
+ if (their_at_domain != 0
+ && (my_at_domain == 0 || strcasecmp(their_at_domain, my_at_domain) != 0))
return (0); /* sender domain mis-match */
/*
* Check the time-dependent portion.
*/
if (var_verify_sender_ttl > 0) {
- their_epoch = safe_strtoul(addr + base_len, &cp, VERIFY_BASE);
+ their_epoch = safe_strtoul(their_addr + base_len, &cp, VERIFY_BASE);
if ((*cp != '@' && *cp != 0)
|| (their_epoch == ULONG_MAX && errno == ERANGE))
return (0); /* malformed time stamp */
* No time-dependent portion.
*/
else {
- if (addr[base_len] != '@' && addr[base_len] != 0)
+ if (their_addr[base_len] != '@' && their_addr[base_len] != 0)
return (0); /* garbage after sender base */
}
- return (STR(fixed_sender_buf));
+ return (STR(time_indep_sender_buf));
}
/*
tests: test1 test2 test3 test4 test5 test6 test7 test8 test9 test10 test11 \
test12 test13 test14 test15 test16 test17 test18 test19 test20 test21 \
- test22 test23 test24 test25
+ test22 test23 test24 test25 test26 test27
root_tests:
diff test22.ref test22.tmp
rm -f main.cf master.cf test22.tmp
-# Test the -C flag.
+# Test the -C flag for each category.
test23: $(PROG) test23.ref
rm -f main.cf master.cf
diff test25.ref test25.tmp
rm -f main.cf master.cf test25.tmp
+# Test completeness of "-C all".
+
+test26: $(PROG) test26.ref
+ rm -f main.cf master.cf
+ touch main.cf master.cf
+ echo always_bcc = yes >> main.cf
+ echo name = value >> main.cf
+ echo whatevershebrings unix - n n - 0 smtp >> master.cf
+ echo ' -o always_bcc=$$name' >> master.cf
+ ./$(PROG) -nc . -C all >test26.tmp 2>&1
+ diff test26.ref test26.tmp
+ rm -f main.cf master.cf test26.tmp
+
+test27: $(PROG) test27.ref
+ rm -f main.cf master.cf
+ touch main.cf master.cf
+ echo always_bcc = yes >> main.cf
+ echo name = value >> main.cf
+ echo whatevershebrings unix - n n - 0 smtp >> master.cf
+ echo ' -o always_bcc=$$name' >> master.cf
+ ./$(PROG) -c . -C all 2>&1 | grep whatevershebrings >test27.tmp
+ diff test27.ref test27.tmp
+ rm -f main.cf master.cf test27.tmp
+
printfck: $(OBJS) $(PROG)
rm -rf printfck
mkdir printfck
/* a \fBmaster.cf\fR entry plus a Postfix-defined suffix).
/* .IP \fBuser\fR
/* Parameters with user-defined names.
+/* .IP \fBall\fR
+/* All the above classes.
/* .RE
/* .IP
-/* The default is as if "\fB-C builtin,service,user\fR" is
+/* The default is as if "\fB-C all\fR" is
/* specified.
/* .IP \fB-d\fR
/* Print \fBmain.cf\fR default parameter settings instead of
"builtin", PC_PARAM_FLAG_BUILTIN,
"service", PC_PARAM_FLAG_SERVICE,
"user", PC_PARAM_FLAG_USER,
+ "all", PC_PARAM_MASK_CLASS,
0,
};
--- /dev/null
+always_bcc = yes
+config_directory = .
+name = value
--- /dev/null
+whatevershebrings_delivery_slot_cost = $default_delivery_slot_cost
+whatevershebrings_delivery_slot_discount = $default_delivery_slot_discount
+whatevershebrings_delivery_slot_loan = $default_delivery_slot_loan
+whatevershebrings_destination_concurrency_failed_cohort_limit = $default_destination_concurrency_failed_cohort_limit
+whatevershebrings_destination_concurrency_limit = $default_destination_concurrency_limit
+whatevershebrings_destination_concurrency_negative_feedback = $default_destination_concurrency_negative_feedback
+whatevershebrings_destination_concurrency_positive_feedback = $default_destination_concurrency_positive_feedback
+whatevershebrings_destination_rate_delay = $default_destination_rate_delay
+whatevershebrings_destination_recipient_limit = $default_destination_recipient_limit
+whatevershebrings_extra_recipient_limit = $default_extra_recipient_limit
+whatevershebrings_initial_destination_concurrency = $initial_destination_concurrency
+whatevershebrings_minimum_delivery_slots = $default_minimum_delivery_slots
+whatevershebrings_recipient_limit = $default_recipient_limit
+whatevershebrings_recipient_refill_delay = $default_recipient_refill_delay
+whatevershebrings_recipient_refill_limit = $default_recipient_refill_limit
/* List of characters that are permitted in postscreen_reject_footer
/* attribute expansions.
/* .IP "\fBpostscreen_reject_footer ($smtpd_reject_footer)\fR"
-/* Optional information that is appended after a 4XX or 5XX server
+/* Optional information that is appended after a 4XX or 5XX
+/* \fBpostscreen\fR(8) server
/* response.
/* .IP "\fBsoft_bounce (no)\fR"
/* Safety net to keep mail queued that would otherwise be returned to
/* .IP "\fBpostscreen_access_list (permit_mynetworks)\fR"
/* Permanent white/blacklist for remote SMTP client IP addresses.
/* .IP "\fBpostscreen_blacklist_action (ignore)\fR"
-/* The action that \fBpostscreen\fR(8) takes when an SMTP client is
+/* The action that \fBpostscreen\fR(8) takes when a remote SMTP client is
/* permanently blacklisted with the postscreen_access_list parameter.
/* MAIL EXCHANGER POLICY TESTS
/* .ad
/* to clients that connect only to backup MX hosts.
/* .IP "\fBpostscreen_whitelist_interfaces (static:all)\fR"
/* A list of local \fBpostscreen\fR(8) server IP addresses where a
-/* non-whitelisted SMTP client can obtain \fBpostscreen\fR(8)'s temporary
-/* whitelist status to talk to a Postfix SMTP server process.
+/* non-whitelisted remote SMTP client can obtain \fBpostscreen\fR(8)'s temporary
+/* whitelist status.
/* BEFORE-GREETING TESTS
/* .ad
/* .fi
/* .IP "\fBdnsblog_service_name (dnsblog)\fR"
/* The name of the \fBdnsblog\fR(8) service entry in master.cf.
/* .IP "\fBpostscreen_dnsbl_action (ignore)\fR"
-/* The action that \fBpostscreen\fR(8) takes when an SMTP client's combined
+/* The action that \fBpostscreen\fR(8) takes when a remote SMTP client's combined
/* DNSBL score is equal to or greater than a threshold (as defined
/* with the postscreen_dnsbl_sites and postscreen_dnsbl_threshold
/* parameters).
/* Optional list of DNS white/blacklist domains, filters and weight
/* factors.
/* .IP "\fBpostscreen_dnsbl_threshold (1)\fR"
-/* The inclusive lower bound for blocking an SMTP client, based on
+/* The inclusive lower bound for blocking a remote SMTP client, based on
/* its combined DNSBL score as defined with the postscreen_dnsbl_sites
/* parameter.
/* .IP "\fBpostscreen_greet_action (ignore)\fR"
-/* The action that \fBpostscreen\fR(8) takes when an SMTP client speaks
+/* The action that \fBpostscreen\fR(8) takes when a remote SMTP client speaks
/* before its turn within the time specified with the postscreen_greet_wait
/* parameter.
/* .IP "\fBpostscreen_greet_banner ($smtpd_banner)\fR"
/* the client will be allowed to talk directly to a Postfix
/* SMTP server process.
/* .IP "\fBpostscreen_bare_newline_action (ignore)\fR"
-/* The action that \fBpostscreen\fR(8) takes when an SMTP client sends
+/* The action that \fBpostscreen\fR(8) takes when a remote SMTP client sends
/* a bare newline character, that is, a newline not preceded by carriage
/* return.
/* .IP "\fBpostscreen_bare_newline_enable (no)\fR"
/* Require that a remote SMTP client sends HELO or EHLO before
/* commencing a MAIL transaction.
/* .IP "\fBpostscreen_non_smtp_command_action (drop)\fR"
-/* The action that \fBpostscreen\fR(8) takes when an SMTP client sends
+/* The action that \fBpostscreen\fR(8) takes when a remote SMTP client sends
/* non-SMTP commands as specified with the postscreen_forbidden_commands
/* parameter.
/* .IP "\fBpostscreen_non_smtp_command_enable (no)\fR"
/* Enable "non-SMTP command" tests in the \fBpostscreen\fR(8) server.
/* .IP "\fBpostscreen_pipelining_action (enforce)\fR"
-/* The action that \fBpostscreen\fR(8) takes when an SMTP client sends
+/* The action that \fBpostscreen\fR(8) takes when a remote SMTP client
+/* sends
/* multiple commands instead of sending one command and waiting for
/* the server to respond.
/* .IP "\fBpostscreen_pipelining_enable (no)\fR"
/* Upon input, long lines are chopped up into pieces of at most
/* this length; upon delivery, long lines are reconstructed.
/* .IP "\fBpostscreen_client_connection_count_limit ($smtpd_client_connection_count_limit)\fR"
-/* How many simultaneous connections any client is allowed to have
+/* How many simultaneous connections any remote SMTP client is
+/* allowed to have
/* with the \fBpostscreen\fR(8) daemon.
/* .IP "\fBpostscreen_command_count_limit (20)\fR"
/* The limit on the total number of commands per SMTP session for
/* built-in SMTP protocol engine.
/* .IP "\fBpostscreen_post_queue_limit ($default_process_limit)\fR"
/* The number of clients that can be waiting for service from a
-/* real SMTP server process.
+/* real Postfix SMTP server process.
/* .IP "\fBpostscreen_pre_queue_limit ($default_process_limit)\fR"
/* The number of non-whitelisted clients that can be waiting for
-/* a decision whether they will receive service from a real SMTP server
+/* a decision whether they will receive service from a real Postfix
+/* SMTP server
/* process.
/* .IP "\fBpostscreen_watchdog_timeout (10s)\fR"
/* How much time a \fBpostscreen\fR(8) process may take to respond to
-/* an SMTP client command or to perform a cache operation before it
+/* a remote SMTP client command or to perform a cache operation before it
/* is terminated by a built-in watchdog timer.
/* STARTTLS CONTROLS
/* .ad
/* These parameters are supported for compatibility with
/* \fBsmtpd\fR(8) legacy parameters.
/* .IP "\fBpostscreen_use_tls ($smtpd_use_tls)\fR"
-/* Opportunistic TLS: announce STARTTLS support to SMTP clients,
+/* Opportunistic TLS: announce STARTTLS support to remote SMTP clients,
/* but do not require that clients use TLS encryption.
/* .IP "\fBpostscreen_enforce_tls ($smtpd_enforce_tls)\fR"
-/* Mandatory TLS: announce STARTTLS support to SMTP clients, and
+/* Mandatory TLS: announce STARTTLS support to remote SMTP clients, and
/* require that clients use TLS encryption.
/* MISCELLANEOUS CONTROLS
/* .ad
VAR_LMTP_TLS_CIPH, DEF_LMTP_TLS_CIPH, &var_smtp_tls_ciph, 1, 0,
VAR_LMTP_TLS_ECCERT_FILE, DEF_LMTP_TLS_ECCERT_FILE, &var_smtp_tls_eccert_file, 0, 0,
VAR_LMTP_TLS_ECKEY_FILE, DEF_LMTP_TLS_ECKEY_FILE, &var_smtp_tls_eckey_file, 0, 0,
+ VAR_LMTP_TLS_LOGLEVEL, DEF_LMTP_TLS_LOGLEVEL, &var_smtp_tls_loglevel, 0, 0,
#endif
VAR_LMTP_SASL_MECHS, DEF_LMTP_SASL_MECHS, &var_smtp_sasl_mechs, 0, 0,
VAR_LMTP_SASL_TYPE, DEF_LMTP_SASL_TYPE, &var_smtp_sasl_type, 1, 0,
VAR_LMTP_MXSESS_LIMIT, DEF_LMTP_MXSESS_LIMIT, &var_smtp_mxsess_limit, 0, 0,
#ifdef USE_TLS
VAR_LMTP_TLS_SCERT_VD, DEF_LMTP_TLS_SCERT_VD, &var_smtp_tls_scert_vd, 0, 0,
- VAR_LMTP_TLS_LOGLEVEL, DEF_LMTP_TLS_LOGLEVEL, &var_smtp_tls_loglevel, 0, 0,
#endif
0,
};
/* Lookup tables, indexed by the remote SMTP server address, with
/* per-destination workarounds for CISCO PIX firewall bugs.
/* .IP "\fBsmtp_quote_rfc821_envelope (yes)\fR"
-/* Quote addresses in SMTP MAIL FROM and RCPT TO commands as required
+/* Quote addresses in Postfix SMTP client MAIL FROM and RCPT TO commands
+/* as required
/* by RFC 2821.
/* .IP "\fBsmtp_reply_filter (empty)\fR"
/* A mechanism to transform replies from remote SMTP servers one
/* line at a time.
/* .IP "\fBsmtp_skip_5xx_greeting (yes)\fR"
-/* Skip SMTP servers that greet with a 5XX status code (go away, do
+/* Skip remote SMTP servers that greet with a 5XX status code (go away,
+/* do
/* not try again later).
/* .IP "\fBsmtp_skip_quit_response (yes)\fR"
/* Do not wait for the response to the SMTP QUIT command.
/* response from a remote SMTP server.
/* .IP "\fBsmtp_generic_maps (empty)\fR"
/* Optional lookup tables that perform address rewriting in the
-/* SMTP client, typically to transform a locally valid address into
+/* Postfix SMTP client, typically to transform a locally valid address into
/* a globally valid address when sending mail across the Internet.
/* .PP
/* Available in Postfix version 2.2.9 and later:
/* .IP "\fBlmtp_discard_lhlo_keyword_address_maps (empty)\fR"
/* Lookup tables, indexed by the remote LMTP server address, with
/* case insensitive lists of LHLO keywords (pipelining, starttls,
-/* auth, etc.) that the LMTP client will ignore in the LHLO response
+/* auth, etc.) that the Postfix LMTP client will ignore in the LHLO
+/* response
/* from a remote LMTP server.
/* .IP "\fBlmtp_discard_lhlo_keywords (empty)\fR"
/* A case insensitive list of LHLO keywords (pipelining, starttls,
-/* auth, etc.) that the LMTP client will ignore in the LHLO response
+/* auth, etc.) that the Postfix LMTP client will ignore in the LHLO
+/* response
/* from a remote LMTP server.
/* .PP
/* Available in Postfix version 2.4.4 and later:
/* .IP "\fBsmtp_sasl_auth_enable (no)\fR"
/* Enable SASL authentication in the Postfix SMTP client.
/* .IP "\fBsmtp_sasl_password_maps (empty)\fR"
-/* Optional SMTP client lookup tables with one username:password entry
+/* Optional Postfix SMTP client lookup tables with one username:password
+/* entry
/* per remote hostname or domain, or sender address when sender-dependent
/* authentication is enabled.
/* .IP "\fBsmtp_sasl_security_options (noplaintext, noanonymous)\fR"
/* list at all TLS security levels.
/* .IP "\fBsmtp_tls_mandatory_exclude_ciphers (empty)\fR"
/* Additional list of ciphers or cipher types to exclude from the
-/* SMTP client cipher list at mandatory TLS security levels.
+/* Postfix SMTP client cipher list at mandatory TLS security levels.
/* .IP "\fBsmtp_tls_dcert_file (empty)\fR"
/* File with the Postfix SMTP client DSA certificate in PEM format.
/* .IP "\fBsmtp_tls_dkey_file ($smtp_tls_dcert_file)\fR"
/* .IP "\fBsmtp_tls_scert_verifydepth (9)\fR"
/* The verification depth for remote SMTP server certificates.
/* .IP "\fBsmtp_tls_secure_cert_match (nexthop, dot-nexthop)\fR"
-/* The server certificate peername verification method for the
+/* How the Postfix SMTP client verifies the server certificate
+/* peername for the
/* "secure" TLS security level.
/* .IP "\fBsmtp_tls_session_cache_database (empty)\fR"
/* Name of the file containing the optional Postfix SMTP client
/* The expiration time of Postfix SMTP client TLS session cache
/* information.
/* .IP "\fBsmtp_tls_verify_cert_match (hostname)\fR"
-/* The server certificate peername verification method for the
+/* How the Postfix SMTP client verifies the server certificate
+/* peername for the
/* "verify" TLS security level.
/* .IP "\fBtls_daemon_random_bytes (32)\fR"
/* The number of pseudo-random bytes that an \fBsmtp\fR(8) or \fBsmtpd\fR(8)
/* .PP
/* Available in Postfix version 2.5 and later:
/* .IP "\fBsmtp_tls_fingerprint_cert_match (empty)\fR"
-/* List of acceptable remote SMTP server certificate fingerprints
-/* for the "fingerprint" TLS security level (\fBsmtp_tls_security_level\fR =
+/* List of acceptable remote SMTP server certificate fingerprints for
+/* the "fingerprint" TLS security level (\fBsmtp_tls_security_level\fR =
/* fingerprint).
/* .IP "\fBsmtp_tls_fingerprint_digest (md5)\fR"
/* The message digest algorithm used to construct remote SMTP server
/* The maximal number of recipients per message for the smtp
/* message delivery transport.
/* .IP "\fBsmtp_connect_timeout (30s)\fR"
-/* The SMTP client time limit for completing a TCP connection, or
+/* The Postfix SMTP client time limit for completing a TCP connection, or
/* zero (use the operating system built-in time limit).
/* .IP "\fBsmtp_helo_timeout (300s)\fR"
-/* The SMTP client time limit for sending the HELO or EHLO command,
-/* and for receiving the initial server response.
+/* The Postfix SMTP client time limit for sending the HELO or EHLO command,
+/* and for receiving the initial remote SMTP server response.
/* .IP "\fBlmtp_lhlo_timeout (300s)\fR"
-/* The LMTP client time limit for sending the LHLO command, and
-/* for receiving the initial server response.
+/* The Postfix LMTP client time limit for sending the LHLO command,
+/* and for receiving the initial remote LMTP server response.
/* .IP "\fBsmtp_xforward_timeout (300s)\fR"
-/* The SMTP client time limit for sending the XFORWARD command, and
-/* for receiving the server response.
+/* The Postfix SMTP client time limit for sending the XFORWARD command,
+/* and for receiving the remote SMTP server response.
/* .IP "\fBsmtp_mail_timeout (300s)\fR"
-/* The SMTP client time limit for sending the MAIL FROM command, and
-/* for receiving the server response.
+/* The Postfix SMTP client time limit for sending the MAIL FROM command,
+/* and for receiving the remote SMTP server response.
/* .IP "\fBsmtp_rcpt_timeout (300s)\fR"
-/* The SMTP client time limit for sending the SMTP RCPT TO command, and
-/* for receiving the server response.
+/* The Postfix SMTP client time limit for sending the SMTP RCPT TO
+/* command, and for receiving the remote SMTP server response.
/* .IP "\fBsmtp_data_init_timeout (120s)\fR"
-/* The SMTP client time limit for sending the SMTP DATA command, and for
-/* receiving the server response.
+/* The Postfix SMTP client time limit for sending the SMTP DATA command,
+/* and for receiving the remote SMTP server response.
/* .IP "\fBsmtp_data_xfer_timeout (180s)\fR"
-/* The SMTP client time limit for sending the SMTP message content.
+/* The Postfix SMTP client time limit for sending the SMTP message content.
/* .IP "\fBsmtp_data_done_timeout (600s)\fR"
-/* The SMTP client time limit for sending the SMTP ".", and for receiving
-/* the server response.
+/* The Postfix SMTP client time limit for sending the SMTP ".", and
+/* for receiving the remote SMTP server response.
/* .IP "\fBsmtp_quit_timeout (300s)\fR"
-/* The SMTP client time limit for sending the QUIT command, and for
-/* receiving the server response.
+/* The Postfix SMTP client time limit for sending the QUIT command,
+/* and for receiving the remote SMTP server response.
/* .PP
/* Available in Postfix version 2.1 and later:
/* .IP "\fBsmtp_mx_address_limit (5)\fR"
/* The maximal number of MX (mail exchanger) IP addresses that can
-/* result from mail exchanger lookups, or zero (no limit).
+/* result from Postfix SMTP client mail exchanger lookups, or zero (no
+/* limit).
/* .IP "\fBsmtp_mx_session_limit (2)\fR"
/* The maximal number of SMTP sessions per delivery request before
-/* giving up or delivering to a fall-back relay host, or zero (no
+/* the Postfix SMTP client
+/* gives up or delivers to a fall-back relay host, or zero (no
/* limit).
/* .IP "\fBsmtp_rset_timeout (20s)\fR"
-/* The SMTP client time limit for sending the RSET command, and
-/* for receiving the server response.
+/* The Postfix SMTP client time limit for sending the RSET command,
+/* and for receiving the remote SMTP server response.
/* .PP
/* Available in Postfix version 2.2 and earlier:
/* .IP "\fBlmtp_cache_connection (yes)\fR"
/* The time limit for sending or receiving information over an internal
/* communication channel.
/* .IP "\fBlmtp_assume_final (no)\fR"
-/* When an LMTP server announces no DSN support, assume that the
+/* When a remote LMTP server announces no DSN support, assume that
+/* the
/* server performs final delivery, and send "delivered" delivery status
/* notifications instead of "relayed".
/* .IP "\fBlmtp_tcp_port (24)\fR"
char *var_smtp_tls_dkey_file;
bool var_smtp_tls_enforce_peername;
char *var_smtp_tls_key_file;
-int var_smtp_tls_loglevel;
+char *var_smtp_tls_loglevel;
bool var_smtp_tls_note_starttls_offer;
char *var_smtp_tls_mand_proto;
char *var_smtp_tls_sec_cmatch;
if (use_tls || var_smtp_tls_per_site[0] || var_smtp_tls_policy[0]) {
#ifdef USE_TLS
TLS_CLIENT_INIT_PROPS props;
+ int using_smtp = (strcmp(var_procname, "smtp") == 0);
/*
* We get stronger type safety and a cleaner interface by combining
*/
smtp_tls_ctx =
TLS_CLIENT_INIT(&props,
+ log_param = using_smtp ?
+ VAR_SMTP_TLS_LOGLEVEL : VAR_LMTP_TLS_LOGLEVEL,
log_level = var_smtp_tls_loglevel,
verifydepth = var_smtp_tls_scert_vd,
- cache_type = strcmp(var_procname, "smtp") == 0 ?
+ cache_type = using_smtp ?
TLS_MGR_SCACHE_SMTP : TLS_MGR_SCACHE_LMTP,
cert_file = var_smtp_tls_cert_file,
key_file = var_smtp_tls_key_file,
VAR_SMTP_TLS_CIPH, DEF_SMTP_TLS_CIPH, &var_smtp_tls_ciph, 1, 0,
VAR_SMTP_TLS_ECCERT_FILE, DEF_SMTP_TLS_ECCERT_FILE, &var_smtp_tls_eccert_file, 0, 0,
VAR_SMTP_TLS_ECKEY_FILE, DEF_SMTP_TLS_ECKEY_FILE, &var_smtp_tls_eckey_file, 0, 0,
+ VAR_SMTP_TLS_LOGLEVEL, DEF_SMTP_TLS_LOGLEVEL, &var_smtp_tls_loglevel, 0, 0,
#endif
VAR_SMTP_SASL_MECHS, DEF_SMTP_SASL_MECHS, &var_smtp_sasl_mechs, 0, 0,
VAR_SMTP_SASL_TYPE, DEF_SMTP_SASL_TYPE, &var_smtp_sasl_type, 1, 0,
VAR_SMTP_MXSESS_LIMIT, DEF_SMTP_MXSESS_LIMIT, &var_smtp_mxsess_limit, 0, 0,
#ifdef USE_TLS
VAR_SMTP_TLS_SCERT_VD, DEF_SMTP_TLS_SCERT_VD, &var_smtp_tls_scert_vd, 0, 0,
- VAR_SMTP_TLS_LOGLEVEL, DEF_SMTP_TLS_LOGLEVEL, &var_smtp_tls_loglevel, 0, 0,
#endif
0,
};
TLS_CLIENT_START(&tls_props,
ctx = smtp_tls_ctx,
stream = session->stream,
- log_level = var_smtp_tls_loglevel,
timeout = var_smtp_starttls_tmout,
tls_level = session->tls_level,
nexthop = session->tls_nexthop,
/* .ad
/* .fi
/* .IP "\fBbroken_sasl_auth_clients (no)\fR"
-/* Enable inter-operability with SMTP clients that implement an obsolete
+/* Enable inter-operability with remote SMTP clients that implement an obsolete
/* version of the AUTH command (RFC 4954).
/* .IP "\fBdisable_vrfy_command (no)\fR"
/* Disable the SMTP VRFY command.
/* .IP "\fBsmtpd_discard_ehlo_keyword_address_maps (empty)\fR"
/* Lookup tables, indexed by the remote SMTP client address, with
/* case insensitive lists of EHLO keywords (pipelining, starttls, auth,
-/* etc.) that the SMTP server will not send in the EHLO response to a
+/* etc.) that the Postfix SMTP server will not send in the EHLO response
+/* to a
/* remote SMTP client.
/* .IP "\fBsmtpd_discard_ehlo_keywords (empty)\fR"
/* A case insensitive list of EHLO keywords (pipelining, starttls,
-/* auth, etc.) that the SMTP server will not send in the EHLO response
+/* auth, etc.) that the Postfix SMTP server will not send in the EHLO
+/* response
/* to a remote SMTP client.
/* .IP "\fBsmtpd_delay_open_until_valid_rcpt (yes)\fR"
/* Postpone the start of an SMTP mail transaction until a valid
/* .PP
/* Available in Postfix version 2.1 and later:
/* .IP "\fBsmtpd_authorized_xforward_hosts (empty)\fR"
-/* What SMTP clients are allowed to use the XFORWARD feature.
+/* What remote SMTP clients are allowed to use the XFORWARD feature.
/* SASL AUTHENTICATION CONTROLS
/* .ad
/* .fi
/* Postfix SMTP client to a remote SMTP server.
/* See the SASL_README document for details.
/* .IP "\fBbroken_sasl_auth_clients (no)\fR"
-/* Enable inter-operability with SMTP clients that implement an obsolete
+/* Enable inter-operability with remote SMTP clients that implement an obsolete
/* version of the AUTH command (RFC 4954).
/* .IP "\fBsmtpd_sasl_auth_enable (no)\fR"
/* Enable SASL authentication in the Postfix SMTP server.
/* use with mandatory TLS encryption.
/* .IP "\fBsmtpd_tls_mandatory_exclude_ciphers (empty)\fR"
/* Additional list of ciphers or cipher types to exclude from the
-/* SMTP server cipher list at mandatory TLS security levels.
+/* Postfix SMTP server cipher list at mandatory TLS security levels.
/* .IP "\fBsmtpd_tls_mandatory_protocols (SSLv3, TLSv1)\fR"
/* The SSL/TLS protocols accepted by the Postfix SMTP server with
/* mandatory TLS encryption.
/* .IP "\fBsmtpd_tls_received_header (no)\fR"
/* Request that the Postfix SMTP server produces Received: message
/* headers that include information about the protocol and cipher used,
-/* as well as the client CommonName and client certificate issuer
+/* as well as the remote SMTP client CommonName and client certificate issuer
/* CommonName.
/* .IP "\fBsmtpd_tls_req_ccert (no)\fR"
/* With mandatory TLS encryption, require a trusted remote SMTP client
/* .PP
/* Available in Postfix version 2.5 and later:
/* .IP "\fBsmtpd_tls_fingerprint_digest (md5)\fR"
-/* The message digest algorithm used to construct client-certificate
-/* fingerprints for \fBcheck_ccert_access\fR and
-/* \fBpermit_tls_clientcerts\fR.
+/* The message digest algorithm to construct remote SMTP
+/* client-certificate
+/* fingerprints or public key fingerprints (Postfix 2.9 and later)
+/* for \fBcheck_ccert_access\fR and \fBpermit_tls_clientcerts\fR.
/* .PP
/* Available in Postfix version 2.6 and later:
/* .IP "\fBsmtpd_tls_protocols (empty)\fR"
/* The Postfix SMTP server security grade for ephemeral elliptic-curve
/* Diffie-Hellman (EECDH) key exchange.
/* .IP "\fBtls_eecdh_strong_curve (prime256v1)\fR"
-/* The elliptic curve used by the SMTP server for sensibly strong
+/* The elliptic curve used by the Postfix SMTP server for sensibly
+/* strong
/* ephemeral ECDH key exchange.
/* .IP "\fBtls_eecdh_ultra_curve (secp384r1)\fR"
-/* The elliptic curve used by the SMTP server for maximally strong
+/* The elliptic curve used by the Postfix SMTP server for maximally
+/* strong
/* ephemeral ECDH key exchange.
/* .PP
/* Available in Postfix version 2.8 and later:
/* .IP "\fBtls_preempt_cipherlist (no)\fR"
-/* With SSLv3 and later, use the server's cipher preference order
-/* instead of the client's cipher preference order.
+/* With SSLv3 and later, use the Postfix SMTP server's cipher
+/* preference order instead of the remote client's cipher preference
+/* order.
/* .IP "\fBtls_disable_workarounds (see 'postconf -d' output)\fR"
/* List or bit-mask of OpenSSL bug work-arounds to disable.
/* OBSOLETE STARTTLS CONTROLS
/* with Postfix versions before 2.3. Support for these will
/* be removed in a future release.
/* .IP "\fBsmtpd_use_tls (no)\fR"
-/* Opportunistic TLS: announce STARTTLS support to SMTP clients,
+/* Opportunistic TLS: announce STARTTLS support to remote SMTP clients,
/* but do not require that clients use TLS encryption.
/* .IP "\fBsmtpd_enforce_tls (no)\fR"
-/* Mandatory TLS: announce STARTTLS support to SMTP clients,
+/* Mandatory TLS: announce STARTTLS support to remote SMTP clients,
/* and require that clients use TLS encryption.
/* .IP "\fBsmtpd_tls_cipherlist (empty)\fR"
/* Obsolete Postfix < 2.3 control for the Postfix SMTP server TLS
/* .PP
/* Available in Postfix version 1.1 and 2.0:
/* .IP "\fBauthorized_verp_clients ($mynetworks)\fR"
-/* What SMTP clients are allowed to specify the XVERP command.
+/* What remote SMTP clients are allowed to specify the XVERP command.
/* .PP
/* Available in Postfix version 2.1 and later:
/* .IP "\fBsmtpd_authorized_verp_clients ($authorized_verp_clients)\fR"
-/* What SMTP clients are allowed to specify the XVERP command.
+/* What remote SMTP clients are allowed to specify the XVERP command.
/* TROUBLE SHOOTING CONTROLS
/* .ad
/* .fi
/* .IP "\fBnotify_classes (resource, software)\fR"
/* The list of error classes that are reported to the postmaster.
/* .IP "\fBsmtpd_reject_footer (empty)\fR"
-/* Optional information that is appended after each SMTP server
+/* Optional information that is appended after each Postfix SMTP
+/* server
/* 4XX or 5XX response.
/* .IP "\fBsoft_bounce (no)\fR"
/* Safety net to keep mail queued that would otherwise be returned to
/* .PP
/* Available in Postfix version 2.1 and later:
/* .IP "\fBsmtpd_authorized_xclient_hosts (empty)\fR"
-/* What SMTP clients are allowed to use the XCLIENT feature.
+/* What remote SMTP clients are allowed to use the XCLIENT feature.
/* KNOWN VERSUS UNKNOWN RECIPIENT CONTROLS
/* .ad
/* .fi
/* Optional lookup tables that alias specific mail addresses or domains
/* to other local or remote address.
/* .IP "\fBunknown_virtual_alias_reject_code (550)\fR"
-/* The SMTP server reply code when a recipient address matches
+/* The Postfix SMTP server reply code when a recipient address matches
/* $virtual_alias_domains, and $virtual_alias_maps specifies a list
/* of lookup tables that does not match the recipient address.
/* .PP
/* Optional lookup tables with all valid addresses in the domains that
/* match $virtual_mailbox_domains.
/* .IP "\fBunknown_virtual_mailbox_reject_code (550)\fR"
-/* The SMTP server reply code when a recipient address matches
+/* The Postfix SMTP server reply code when a recipient address matches
/* $virtual_mailbox_domains, and $virtual_mailbox_maps specifies a list
/* of lookup tables that does not match the recipient address.
/* RESOURCE AND RATE CONTROLS
/* What Postfix features match subdomains of "domain.tld" automatically,
/* instead of requiring an explicit ".domain.tld" pattern.
/* .IP "\fBsmtpd_client_restrictions (empty)\fR"
-/* Optional SMTP server access restrictions in the context of a client
-/* SMTP connection request.
+/* Optional Postfix SMTP server access restrictions in the context of
+/* a remote SMTP client connection request.
/* .IP "\fBsmtpd_helo_required (no)\fR"
/* Require that a remote SMTP client introduces itself with the HELO
/* or EHLO command before sending the MAIL command or other commands
/* .PP
/* Available in Postfix version 2.0 and later:
/* .IP "\fBdefault_rbl_reply (see 'postconf -d' output)\fR"
-/* The default SMTP server response template for a request that is
+/* The default Postfix SMTP server response template for a request that is
/* rejected by an RBL-based restriction.
/* .IP "\fBmulti_recipient_bounce_reject_code (550)\fR"
/* The numerical Postfix SMTP server response code when a remote SMTP
/* .IP "\fBmyhostname (see 'postconf -d' output)\fR"
/* The internet hostname of this mail system.
/* .IP "\fBmynetworks (see 'postconf -d' output)\fR"
-/* The list of "trusted" SMTP clients that have more privileges than
+/* The list of "trusted" remote SMTP clients that have more privileges than
/* "strangers".
/* .IP "\fBmyorigin ($myhostname)\fR"
/* The domain name that locally-posted mail appears to come
char *var_smtpd_tls_dh512_param_file;
char *var_smtpd_tls_dkey_file;
char *var_smtpd_tls_key_file;
-int var_smtpd_tls_loglevel;
+char *var_smtpd_tls_loglevel;
char *var_smtpd_tls_mand_proto;
bool var_smtpd_tls_received_header;
bool var_smtpd_tls_req_ccert;
ctx = smtpd_tls_ctx,
stream = state->client,
fd = -1,
- log_level = var_smtpd_tls_loglevel,
timeout = var_smtpd_starttls_tmout,
requirecert = requirecert,
serverid = state->service,
*/
smtpd_tls_ctx =
TLS_SERVER_INIT(&props,
+ log_param = VAR_SMTPD_TLS_LOGLEVEL,
log_level = var_smtpd_tls_loglevel,
verifydepth = var_smtpd_tls_ccert_vd,
cache_type = TLS_MGR_SCACHE_SMTPD,
VAR_SMTPD_CNTLS_LIMIT, DEF_SMTPD_CNTLS_LIMIT, &var_smtpd_cntls_limit, 0, 0,
#ifdef USE_TLS
VAR_SMTPD_TLS_CCERT_VD, DEF_SMTPD_TLS_CCERT_VD, &var_smtpd_tls_ccert_vd, 0, 0,
- VAR_SMTPD_TLS_LOGLEVEL, DEF_SMTPD_TLS_LOGLEVEL, &var_smtpd_tls_loglevel, 0, 0,
#endif
0,
};
VAR_SMTPD_TLS_1024_FILE, DEF_SMTPD_TLS_1024_FILE, &var_smtpd_tls_dh1024_param_file, 0, 0,
VAR_SMTPD_TLS_EECDH, DEF_SMTPD_TLS_EECDH, &var_smtpd_tls_eecdh, 1, 0,
VAR_SMTPD_TLS_FPT_DGST, DEF_SMTPD_TLS_FPT_DGST, &var_smtpd_tls_fpt_dgst, 1, 0,
+ VAR_SMTPD_TLS_LOGLEVEL, DEF_SMTPD_TLS_LOGLEVEL, &var_smtpd_tls_loglevel, 0, 0,
#endif
VAR_SMTPD_TLS_LEVEL, DEF_SMTPD_TLS_LEVEL, &var_smtpd_tls_level, 0, 0,
VAR_SMTPD_SASL_TYPE, DEF_SMTPD_SASL_TYPE, &var_smtpd_sasl_type, 1, 0,
*/
typedef struct {
SMTPD_STATE *state; /* general state */
- char *domain; /* query domain */
+ char *domain; /* query domain */
const char *what; /* rejected value */
const char *class; /* name of rejected value */
const char *txt; /* randomly selected trimmed TXT rr */
static int permit_tls_clientcerts(SMTPD_STATE *state, int permit_all_certs)
{
#ifdef USE_TLS
- const char *found;
+ const char *found = 0;
dict_errno = 0;
* not trusted.
*/
if (TLS_CERT_IS_PRESENT(state->tls_context)) {
- found = maps_find(relay_ccerts, state->tls_context->peer_fingerprint,
- DICT_FLAG_NONE);
+ int i;
+ char *prints[2];
+
+ prints[0] = state->tls_context->peer_fingerprint;
+ prints[1] = state->tls_context->peer_pkey_fprint;
+
+ /* After lookup error, leave dict_errno at its non-zero value. */
+ for (i = 0; i < 2 && found == 0 && dict_errno == 0; ++i)
+ found = maps_find(relay_ccerts, prints[i], DICT_FLAG_NONE);
if (found) {
if (msg_verbose)
msg_info("Relaying allowed for certified client: %s", found);
return (SMTPD_CHECK_OK);
} else if (msg_verbose)
- msg_info("relay_clientcerts: No match for fingerprint '%s'",
- state->tls_context->peer_fingerprint);
+ msg_info("relay_clientcerts: No match for fingerprint '%s', "
+ "pkey fingerprint %s", prints[0], prints[1]);
}
#else
dict_errno = 0;
static int check_ccert_access(SMTPD_STATE *state, const char *table,
const char *def_acl)
{
+ int result = SMTPD_CHECK_DUNNO;
#ifdef USE_TLS
const char *myname = "check_ccert_access";
int found;
* not trusted.
*/
if (TLS_CERT_IS_PRESENT(state->tls_context)) {
- if (msg_verbose)
- msg_info("%s: %s", myname, state->tls_context->peer_fingerprint);
+ int i;
+ char *prints[2];
- /*
- * Regexp tables don't make sense for certificate fingerprints. That
- * may be so, but we can't ignore the entire check_ccert_access
- * request without logging a warning.
- *
- * Log the peer CommonName when access is denied. Non-printable
- * characters will be neutered by smtpd_check_reject(). The SMTP
- * client name and address are always syslogged as part of a "reject"
- * event.
- */
- return (check_access(state, table,
- state->tls_context->peer_fingerprint,
- DICT_FLAG_NONE, &found,
- state->tls_context->peer_CN,
- SMTPD_NAME_CCERT, def_acl));
+ prints[0] = state->tls_context->peer_fingerprint;
+ prints[1] = state->tls_context->peer_pkey_fprint;
+
+ for (i = 0; i < 2; ++i) {
+ if (msg_verbose)
+ msg_info("%s: %s", myname, prints[i]);
+
+ /*
+ * Regexp tables don't make sense for certificate fingerprints.
+ * That may be so, but we can't ignore the entire
+ * check_ccert_access request without logging a warning.
+ *
+ * Log the peer CommonName when access is denied. Non-printable
+ * characters will be neutered by smtpd_check_reject(). The SMTP
+ * client name and address are always syslogged as part of a
+ * "reject" event.
+ */
+ result = check_access(state, table, prints[i],
+ DICT_FLAG_NONE, &found,
+ state->tls_context->peer_CN,
+ SMTPD_NAME_CCERT, def_acl);
+ if (result != SMTPD_CHECK_DUNNO)
+ break;
+ }
}
#endif
- return (SMTPD_CHECK_DUNNO);
+ return (result);
}
/* check_mail_access - OK/FAIL based on mail address lookup */
*/
ATTR_TYPE_STR, MAIL_ATTR_CCERT_FINGERPRINT,
IF_ENCRYPTED(state->tls_context->peer_fingerprint, ""),
+ ATTR_TYPE_STR, MAIL_ATTR_CCERT_PKEY_FPRINT,
+ IF_ENCRYPTED(state->tls_context->peer_pkey_fprint, ""),
ATTR_TYPE_STR, MAIL_ATTR_CRYPTO_PROTOCOL,
IF_ENCRYPTED(state->tls_context->protocol, ""),
ATTR_TYPE_STR, MAIL_ATTR_CRYPTO_CIPHER,
}
} else if (strcasecmp(name, PERMIT_NAKED_IP_ADDR) == 0) {
msg_warn("restriction %s is deprecated. Use %s or %s instead",
- PERMIT_NAKED_IP_ADDR, PERMIT_MYNETWORKS, PERMIT_SASL_AUTH);
+ PERMIT_NAKED_IP_ADDR, PERMIT_MYNETWORKS, PERMIT_SASL_AUTH);
if (state->helo_name) {
if (state->helo_name[strspn(state->helo_name, "0123456789.:")] == 0
&& (status = reject_invalid_hostaddr(state, state->helo_name,
#endif
} else if (strcasecmp(name, PERMIT_TLS_ALL_CLIENTCERTS) == 0) {
status = permit_tls_clientcerts(state, 1);
- if (dict_errno != 0)
+ if (dict_errno != 0)
reject_dict_retry(state, reply_name);
} else if (strcasecmp(name, PERMIT_TLS_CLIENTCERTS) == 0) {
status = permit_tls_clientcerts(state, 0);
- if (dict_errno != 0)
+ if (dict_errno != 0)
reject_dict_retry(state, reply_name);
} else if (strcasecmp(name, REJECT_UNKNOWN_RCPTDOM) == 0) {
if (state->recipient)
char *peer_CN; /* Peer Common Name */
char *issuer_CN; /* Issuer Common Name */
char *peer_fingerprint; /* ASCII fingerprint */
+ char *peer_pkey_fprint; /* ASCII public key fingerprint */
int peer_status; /* Certificate and match status */
const char *protocol;
const char *cipher_name;
char *cache_type; /* tlsmgr(8) cache type if enabled */
char *serverid; /* unique server identifier */
char *namaddr; /* nam[addr] for logging */
- int log_level; /* TLS library logging level */
+ int log_mask; /* What to log */
int session_reused; /* this session was reused */
int am_server; /* Are we an SSL server or client? */
/* Built-in vs external SSL_accept/read/write/shutdown support. */
#define TLS_CERT_FLAG_ALTNAME (1<<1)
#define TLS_CERT_FLAG_TRUSTED (1<<2)
#define TLS_CERT_FLAG_MATCHED (1<<3)
-#define TLS_CERT_FLAG_LOGGED (1<<4) /* Logged trust chain error */
#define TLS_CERT_IS_PRESENT(c) ((c) && ((c)->peer_status&TLS_CERT_FLAG_PRESENT))
#define TLS_CERT_IS_ALTNAME(c) ((c) && ((c)->peer_status&TLS_CERT_FLAG_ALTNAME))
#ifdef TLS_INTERNAL
+ /*
+ * Log mask details are internal to the library.
+ */
+extern int tls_log_mask(const char *, const char *);
+
+ /*
+ * What to log.
+ */
+#define TLS_LOG_NONE (1<<0)
+#define TLS_LOG_SUMMARY (1<<1)
+#define TLS_LOG_UNTRUSTED (1<<2)
+#define TLS_LOG_PEERCERT (1<<3)
+#define TLS_LOG_CERTMATCH (1<<4)
+#define TLS_LOG_VERBOSE (1<<5)
+#define TLS_LOG_CACHE (1<<6)
+#define TLS_LOG_DEBUG (1<<7)
+#define TLS_LOG_TLSPKTS (1<<8)
+#define TLS_LOG_ALLPKTS (1<<9)
+
/*
* Client and Server application contexts
*/
struct TLS_APPL_STATE {
SSL_CTX *ssl_ctx;
+ int log_mask;
char *cache_type;
char *cipher_exclusions; /* Last cipher selection state */
char *cipher_list; /* Last cipher selection state */
* tls_client.c
*/
typedef struct {
- int log_level;
+ const char *log_param;
+ const char *log_level;
int verifydepth;
const char *cache_type;
const char *cert_file;
typedef struct {
TLS_APPL_STATE *ctx;
VSTREAM *stream;
- int log_level;
int timeout;
int tls_level; /* Security level */
const char *nexthop; /* destination domain */
tls_session_stop(ctx, (stream), (timeout), (failure), (TLScontext))
#define TLS_CLIENT_INIT(props, a1, a2, a3, a4, a5, a6, a7, a8, a9, \
- a10, a11, a12) \
+ a10, a11, a12, a13) \
tls_client_init((((props)->a1), ((props)->a2), ((props)->a3), \
((props)->a4), ((props)->a5), ((props)->a6), ((props)->a7), \
((props)->a8), ((props)->a9), ((props)->a10), ((props)->a11), \
- ((props)->a12), (props)))
+ ((props)->a12), ((props)->a13), (props)))
#define TLS_CLIENT_START(props, a1, a2, a3, a4, a5, a6, a7, a8, a9, \
- a10, a11, a12, a13, a14) \
+ a10, a11, a12, a13) \
tls_client_start((((props)->a1), ((props)->a2), ((props)->a3), \
((props)->a4), ((props)->a5), ((props)->a6), ((props)->a7), \
((props)->a8), ((props)->a9), ((props)->a10), ((props)->a11), \
- ((props)->a12), ((props)->a13), ((props)->a14), (props)))
+ ((props)->a12), ((props)->a13), (props)))
/*
* tls_server.c
*/
typedef struct {
- int log_level;
+ const char *log_param;
+ const char *log_level;
int verifydepth;
const char *cache_type;
long scache_timeout;
TLS_APPL_STATE *ctx; /* TLS application context */
VSTREAM *stream; /* Client stream */
int fd; /* Event-driven file descriptor */
- int log_level; /* TLS log level */
int timeout; /* TLS handshake timeout */
int requirecert; /* Insist on client cert? */
const char *serverid; /* Server instance (salt cache key) */
tls_session_stop(ctx, (stream), (timeout), (failure), (TLScontext))
#define TLS_SERVER_INIT(props, a1, a2, a3, a4, a5, a6, a7, a8, a9, \
- a10, a11, a12, a13, a14, a15, a16, a17, a18, a19) \
+ a10, a11, a12, a13, a14, a15, a16, a17, a18, a19, a20) \
tls_server_init((((props)->a1), ((props)->a2), ((props)->a3), \
((props)->a4), ((props)->a5), ((props)->a6), ((props)->a7), \
((props)->a8), ((props)->a9), ((props)->a10), ((props)->a11), \
((props)->a12), ((props)->a13), ((props)->a14), ((props)->a15), \
- ((props)->a16), ((props)->a17), ((props)->a18), ((props)->a19), (props)))
+ ((props)->a16), ((props)->a17), ((props)->a18), ((props)->a19), \
+ ((props)->a20), (props)))
-#define TLS_SERVER_START(props, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11) \
+#define TLS_SERVER_START(props, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10) \
tls_server_start((((props)->a1), ((props)->a2), ((props)->a3), \
((props)->a4), ((props)->a5), ((props)->a6), ((props)->a7), \
- ((props)->a8), ((props)->a9), ((props)->a10), ((props)->a11), (props)))
+ ((props)->a8), ((props)->a9), ((props)->a10), (props)))
/*
* tls_session.c
extern char *tls_issuer_CN(X509 *, const TLS_SESS_STATE *);
extern const char *tls_dns_name(const GENERAL_NAME *, const TLS_SESS_STATE *);
extern char *tls_fingerprint(X509 *, const char *);
+extern char *tls_pkey_fprint(X509 *, const char *);
extern int tls_verify_certificate_callback(int, X509_STORE_CTX *);
/*
*/
extern int TLScontext_index;
-extern TLS_APPL_STATE *tls_alloc_app_context(SSL_CTX *);
+extern TLS_APPL_STATE *tls_alloc_app_context(SSL_CTX *, int);
extern TLS_SESS_STATE *tls_alloc_sess_context(int, const char *);
extern void tls_free_context(TLS_SESS_STATE *);
extern void tls_check_version(void);
/*
* Prepare the query.
*/
- if (TLScontext->log_level >= 2)
+ if (TLScontext->log_mask & TLS_LOG_CACHE)
+ /* serverid already contains namaddrport information */
msg_info("looking for session %s in %s cache",
TLScontext->serverid, TLScontext->cache_type);
session_data) == TLS_MGR_STAT_OK) {
session = tls_session_activate(STR(session_data), LEN(session_data));
if (session) {
- if (TLScontext->log_level >= 2)
+ if (TLScontext->log_mask & TLS_LOG_CACHE)
+ /* serverid already contains namaddrport information */
msg_info("reloaded session %s from %s cache",
TLScontext->serverid, TLScontext->cache_type);
}
msg_panic("%s: null session cache type in new session callback",
myname);
- if (TLScontext->log_level >= 2)
+ if (TLScontext->log_mask & TLS_LOG_CACHE)
+ /* serverid already contains namaddrport information */
msg_info("save session %s to %s cache",
TLScontext->serverid, TLScontext->cache_type);
if (TLScontext->cache_type == 0 || TLScontext->serverid == 0)
return;
- if (TLScontext->log_level >= 2)
+ if (TLScontext->log_mask & TLS_LOG_CACHE)
+ /* serverid already contains namaddrport information */
msg_info("remove session %s from client cache", TLScontext->serverid);
tls_mgr_delete(TLScontext->cache_type, TLScontext->serverid);
TLS_APPL_STATE *app_ctx;
const EVP_MD *md_alg;
unsigned int md_len;
+ int log_mask;
- if (props->log_level >= 2)
+ /*
+ * Convert user loglevel to internal logmask.
+ */
+ log_mask = tls_log_mask(props->log_param, props->log_level);
+
+ if (log_mask & TLS_LOG_VERBOSE)
msg_info("initializing the client-side TLS engine");
/*
/*
* Set the call-back routine for verbose logging.
*/
- if (props->log_level >= 2)
+ if (log_mask & TLS_LOG_DEBUG)
SSL_CTX_set_info_callback(client_ctx, tls_info_callback);
/*
* Allocate an application context, and populate with mandatory protocol
* and cipher data.
*/
- app_ctx = tls_alloc_app_context(client_ctx);
+ app_ctx = tls_alloc_app_context(client_ctx, log_mask);
/*
* The external session cache is implemented by the tlsmgr(8) process.
static int match_hostname(const char *peerid,
const TLS_CLIENT_START_PROPS *props)
{
- const ARGV *cmatch_argv = props->matchargv;
+ const ARGV *cmatch_argv;
const char *nexthop = props->nexthop;
const char *hname = props->host;
const char *pattern;
int idlen;
int patlen;
+ if ((cmatch_argv = props->matchargv) == 0)
+ return 0;
+
/*
* Match the peerid against each pattern until we find a match.
*/
int i;
int r;
int matched = 0;
+ int dnsname_match;
+ int verify_peername = 0;
+ int log_certmatch;
+ int verbose;
const char *dnsname;
const GENERAL_NAME *gn;
if (SSL_get_verify_result(TLScontext->con) == X509_V_OK)
TLScontext->peer_status |= TLS_CERT_FLAG_TRUSTED;
- if (TLS_CERT_IS_TRUSTED(TLScontext) && props->tls_level >= TLS_LEV_VERIFY) {
+ if (TLS_CERT_IS_TRUSTED(TLScontext) && props->tls_level >= TLS_LEV_VERIFY)
+ verify_peername = 1;
+
+ /* Force cert processing so we can log the data? */
+ log_certmatch = TLScontext->log_mask & TLS_LOG_CERTMATCH;
+
+ /* Log cert details when processing? */
+ verbose = log_certmatch || (TLScontext->log_mask & TLS_LOG_VERBOSE);
+
+ if (verify_peername || log_certmatch) {
/*
* Verify the dNSName(s) in the peer certificate against the nexthop
gens = X509_get_ext_d2i(peercert, NID_subject_alt_name, 0, 0);
if (gens) {
r = sk_GENERAL_NAME_num(gens);
- for (i = 0; i < r && !matched; ++i) {
+ for (i = 0; i < r; ++i) {
gn = sk_GENERAL_NAME_value(gens, i);
if (gn->type != GEN_DNS)
continue;
TLScontext->peer_status |= TLS_CERT_FLAG_ALTNAME;
dnsname = tls_dns_name(gn, TLScontext);
if (dnsname && *dnsname) {
- matched = match_hostname(dnsname, props);
+ if ((dnsname_match = match_hostname(dnsname, props)) != 0)
+ matched++;
+ /* Keep the first matched name. */
if (TLScontext->peer_CN
- && (matched || *TLScontext->peer_CN == 0)) {
+ && ((dnsname_match && matched == 1)
+ || *TLScontext->peer_CN == 0)) {
myfree(TLScontext->peer_CN);
TLScontext->peer_CN = 0;
}
+ if (verbose)
+ msg_info("%s: %ssubjectAltName: %s", props->namaddr,
+ dnsname_match ? "Matched " : "", dnsname);
}
if (TLScontext->peer_CN == 0)
TLScontext->peer_CN = mystrdup(dnsname ? dnsname : "");
+ if (matched && !log_certmatch)
+ break;
}
+ if (verify_peername && matched)
+ TLScontext->peer_status |= TLS_CERT_FLAG_MATCHED;
/*
* (Sam Rushing, Ironport) Free stack *and* member GENERAL_NAME
TLScontext->peer_CN = tls_peer_CN(peercert, TLScontext);
if (*TLScontext->peer_CN)
matched = match_hostname(TLScontext->peer_CN, props);
- }
- if (matched)
- TLScontext->peer_status |= TLS_CERT_FLAG_MATCHED;
+ if (verify_peername && matched)
+ TLScontext->peer_status |= TLS_CERT_FLAG_MATCHED;
+ if (verbose)
+ msg_info("%s %sCommonName %s", props->namaddr,
+ matched ? "Matched " : "", TLScontext->peer_CN);
+ } else if (verbose) {
+ char *tmpcn = tls_peer_CN(peercert, TLScontext);
- /*
- * - Matched: Trusted and peername matches - Trusted: Signed by
- * trusted CA(s), but peername not matched - Untrusted: Can't verify
- * the trust chain, reason already logged.
- */
- if (TLScontext->log_level >= 2)
- msg_info("%s: %s subject_CN=%s, issuer_CN=%s", props->namaddr,
- TLS_CERT_IS_MATCHED(TLScontext) ? "Matched" :
- TLS_CERT_IS_TRUSTED(TLScontext) ? "Trusted" : "Untrusted",
- TLScontext->peer_CN, TLScontext->issuer_CN);
+ /*
+ * Though the CommonName was superceded by a subjectAltName, log
+ * it when certificate match debugging was requested.
+ */
+ msg_info("%s CommonName %s", TLScontext->namaddr, tmpcn);
+ myfree(tmpcn);
+ }
} else
TLScontext->peer_CN = tls_peer_CN(peercert, TLScontext);
*/
if (TLScontext->session_reused
&& !TLS_CERT_IS_TRUSTED(TLScontext)
- && TLScontext->log_level >= 1)
+ && (TLScontext->log_mask & TLS_LOG_UNTRUSTED))
msg_info("%s: re-using session with untrusted certificate, "
"look for details earlier in the log", props->namaddr);
}
/* Non-null by contract */
TLScontext->peer_fingerprint = tls_fingerprint(peercert, props->fpt_dgst);
-
- if (props->tls_level != TLS_LEV_FPRINT)
- return;
+ TLScontext->peer_pkey_fprint = tls_pkey_fprint(peercert, props->fpt_dgst);
/*
* Compare the fingerprint against each acceptable value, ignoring
* upper/lower case differences.
*/
- for (cpp = props->matchargv->argv; *cpp; ++cpp)
- if (strcasecmp(TLScontext->peer_fingerprint, *cpp) == 0) {
- TLScontext->peer_status |= TLS_CERT_FLAG_MATCHED;
- break;
+ if (props->tls_level == TLS_LEV_FPRINT) {
+ for (cpp = props->matchargv->argv; *cpp; ++cpp) {
+ if (strcasecmp(TLScontext->peer_fingerprint, *cpp) == 0
+ || strcasecmp(TLScontext->peer_pkey_fprint, *cpp) == 0) {
+ TLScontext->peer_status |= TLS_CERT_FLAG_MATCHED;
+ break;
+ }
}
- if (props->log_level >= 2)
- msg_info("%s %s%s fingerprint %s", props->namaddr,
- TLS_CERT_IS_MATCHED(TLScontext) ? "Matched " : "",
- props->fpt_dgst, TLScontext->peer_fingerprint);
+ }
}
/*
TLS_SESS_STATE *TLScontext;
TLS_APPL_STATE *app_ctx = props->ctx;
VSTRING *myserverid;
+ int log_mask = app_ctx->log_mask;
- if (props->log_level >= 1)
+ /*
+ * When certificate verification is required, log trust chain validation
+ * errors even when disabled by default for opportunistic sessions.
+ */
+ if (props->tls_level >= TLS_LEV_VERIFY)
+ log_mask |= TLS_LOG_UNTRUSTED;
+
+ if (log_mask & TLS_LOG_VERBOSE)
msg_info("setting up TLS connection to %s", props->namaddr);
/*
vstring_free(myserverid);
return (0);
}
- if (props->log_level >= 2)
+ if (log_mask & TLS_LOG_VERBOSE)
msg_info("%s: TLS cipher list \"%s\"", props->namaddr, cipher_list);
vstring_sprintf_append(myserverid, "&c=%s", cipher_list);
* If session caching was enabled when TLS was initialized, the cache type
* is stored in the client SSL context.
*/
- TLScontext = tls_alloc_sess_context(props->log_level, props->namaddr);
+ TLScontext = tls_alloc_sess_context(log_mask, props->namaddr);
TLScontext->cache_type = app_ctx->cache_type;
TLScontext->serverid = vstring_export(myserverid);
/*
* If the debug level selected is high enough, all of the data is dumped:
- * 3 will dump the SSL negotiation, 4 will dump everything.
+ * TLS_LOG_TLSPKTS will dump the SSL negotiation, TLS_LOG_ALLPKTS will
+ * dump everything.
*
* We do have an SSL_set_fd() and now suddenly a BIO_ routine is called?
* Well there is a BIO below the SSL routines that is automatically
* created for us, so we can use it for debugging purposes.
*/
- if (props->log_level >= 3)
+ if (log_mask & TLS_LOG_TLSPKTS)
BIO_set_callback(SSL_get_rbio(TLScontext->con), tls_bio_dump_cb);
/*
tls_free_context(TLScontext);
return (0);
}
- /* Only log_level==4 dumps everything */
- if (props->log_level < 4)
+ /* Turn off packet dump if only dumping the handshake */
+ if ((log_mask & TLS_LOG_ALLPKTS) == 0)
BIO_set_callback(SSL_get_rbio(TLScontext->con), 0);
/*
* session was negotiated.
*/
TLScontext->session_reused = SSL_session_reused(TLScontext->con);
- if (props->log_level >= 2 && TLScontext->session_reused)
+ if ((log_mask & TLS_LOG_CACHE) && TLScontext->session_reused)
msg_info("%s: Reusing old session", TLScontext->namaddr);
/*
*/
verify_extract_name(TLScontext, peercert, props);
verify_extract_print(TLScontext, peercert, props);
+
+ if (TLScontext->log_mask &
+ (TLS_LOG_CERTMATCH | TLS_LOG_VERBOSE | TLS_LOG_PEERCERT))
+ msg_info("%s: subject_CN=%s, issuer_CN=%s, "
+ "fingerprint %s, pkey_fingerprint=%s", props->namaddr,
+ TLScontext->peer_CN, TLScontext->issuer_CN,
+ TLScontext->peer_fingerprint,
+ TLScontext->peer_pkey_fprint);
X509_free(peercert);
} else {
TLScontext->issuer_CN = mystrdup("");
TLScontext->peer_CN = mystrdup("");
TLScontext->peer_fingerprint = mystrdup("");
+ TLScontext->peer_pkey_fprint = mystrdup("");
}
/*
/*
* All the key facts in a single log entry.
*/
- if (props->log_level >= 1)
+ if (log_mask & TLS_LOG_SUMMARY)
msg_info("%s TLS connection established to %s: %s with cipher %s "
"(%d/%d bits)", TLS_CERT_IS_MATCHED(TLScontext) ? "Verified" :
TLS_CERT_IS_TRUSTED(TLScontext) ? "Trusted" : "Untrusted",
/* bool var_tls_append_def_CA;
/* bool var_tls_preempt_clist;
/*
-/* TLS_APPL_STATE *tls_alloc_app_context(ssl_ctx)
+/* TLS_APPL_STATE *tls_alloc_app_context(ssl_ctx, log_mask)
/* SSL_CTX *ssl_ctx;
+/* int log_mask;
/*
/* void tls_free_app_context(app_ctx)
/* void *app_ctx;
/*
-/* TLS_SESS_STATE *tls_alloc_sess_context(log_level, namaddr)
-/* int log_level;
+/* TLS_SESS_STATE *tls_alloc_sess_context(log_mask, namaddr)
+/* int log_mask;
/* const char *namaddr;
/*
/* void tls_free_context(TLScontext)
/* int argi;
/* long argl; /* unused */
/* long ret;
+/*
+/* int tls_log_mask(log_param, log_level)
+/* const char *log_param;
+/* const char *log_level;
/* DESCRIPTION
/* This module implements routines that support the TLS client
/* and server internals.
/* tls_bio_dump_cb() is a call-back routine for the
/* BIO_set_callback() routine. It logs SSL content to the
/* Postfix logfile.
+/*
+/* tls_log_mask() converts a TLS log_level value from string
+/* to mask. The main.cf parameter name is passed along for
+/* diagnostics.
/* LICENSE
/* .ad
/* .fi
0, TLS_CIPHER_NONE,
};
+ /*
+ * Log keyword <=> mask conversion.
+ */
+#define TLS_LOG_0 TLS_LOG_NONE
+#define TLS_LOG_1 TLS_LOG_SUMMARY
+#define TLS_LOG_2 (TLS_LOG_1 | TLS_LOG_VERBOSE | TLS_LOG_CACHE | TLS_LOG_DEBUG)
+#define TLS_LOG_3 (TLS_LOG_2 | TLS_LOG_TLSPKTS)
+#define TLS_LOG_4 (TLS_LOG_3 | TLS_LOG_ALLPKTS)
+
+static const NAME_MASK tls_log_table[] = {
+ "0", TLS_LOG_0,
+ "none", TLS_LOG_NONE,
+ "1", TLS_LOG_1,
+ "routine", TLS_LOG_1,
+ "2", TLS_LOG_2,
+ "debug", TLS_LOG_2,
+ "3", TLS_LOG_3,
+ "ssl-expert", TLS_LOG_3,
+ "4", TLS_LOG_4,
+ "ssl-developer", TLS_LOG_4,
+ "5", TLS_LOG_4, /* for good measure */
+ "6", TLS_LOG_4, /* for good measure */
+ "7", TLS_LOG_4, /* for good measure */
+ "8", TLS_LOG_4, /* for good measure */
+ "9", TLS_LOG_4, /* for good measure */
+ "summary", TLS_LOG_SUMMARY,
+ "untrusted", TLS_LOG_UNTRUSTED,
+ "peercert", TLS_LOG_PEERCERT,
+ "certmatch", TLS_LOG_CERTMATCH,
+ "verbose", TLS_LOG_VERBOSE, /* Postfix TLS library verbose */
+ "cache", TLS_LOG_CACHE,
+ "ssl-debug", TLS_LOG_DEBUG, /* SSL library debug/verbose */
+ "ssl-handshake-packet-dump", TLS_LOG_TLSPKTS,
+ "ssl-session-packet-dump", TLS_LOG_TLSPKTS | TLS_LOG_ALLPKTS,
+ 0, 0,
+};
+
/*
* Parsed OpenSSL version number.
*/
0, 0, 0,
};
+/* tls_log_mask - Convert user TLS loglevel to internal log feature mask */
+
+int tls_log_mask(const char *log_param, const char *log_level)
+{
+ int mask;
+
+ mask = name_mask_opt(log_param, tls_log_table, log_level,
+ NAME_MASK_ANY_CASE | NAME_MASK_RETURN);
+ return (mask);
+}
+
/* tls_exclude_missing - Append exclusions for missing ciphers */
static const char *tls_exclude_missing(SSL_CTX *ctx, VSTRING *buf)
/* tls_alloc_app_context - allocate TLS application context */
-TLS_APPL_STATE *tls_alloc_app_context(SSL_CTX *ssl_ctx)
+TLS_APPL_STATE *tls_alloc_app_context(SSL_CTX *ssl_ctx, int log_mask)
{
TLS_APPL_STATE *app_ctx;
app_ctx = (TLS_APPL_STATE *) mymalloc(sizeof(*app_ctx));
+ /* See portability note below with other memset() call. */
memset((char *) app_ctx, 0, sizeof(*app_ctx));
app_ctx->ssl_ctx = ssl_ctx;
+ app_ctx->log_mask = log_mask;
/* See also: cache purging code in tls_set_ciphers(). */
app_ctx->cipher_grade = TLS_CIPHER_NONE;
/* tls_alloc_sess_context - allocate TLS session context */
-TLS_SESS_STATE *tls_alloc_sess_context(int log_level, const char *namaddr)
+TLS_SESS_STATE *tls_alloc_sess_context(int log_mask, const char *namaddr)
{
TLS_SESS_STATE *TLScontext;
TLScontext->peer_CN = 0;
TLScontext->issuer_CN = 0;
TLScontext->peer_fingerprint = 0;
+ TLScontext->peer_pkey_fprint = 0;
TLScontext->protocol = 0;
TLScontext->cipher_name = 0;
- TLScontext->log_level = log_level;
+ TLScontext->log_mask = log_mask;
TLScontext->namaddr = lowercase(mystrdup(namaddr));
TLScontext->fpt_dgst = 0;
myfree(TLScontext->issuer_CN);
if (TLScontext->peer_fingerprint)
myfree(TLScontext->peer_fingerprint);
+ if (TLScontext->peer_pkey_fprint)
+ myfree(TLScontext->peer_pkey_fprint);
if (TLScontext->fpt_dgst)
myfree(TLScontext->fpt_dgst);
long tls_bug_bits(void)
{
long bits = SSL_OP_ALL; /* Work around all known bugs */
- long mask;
#if OPENSSL_VERSION_NUMBER >= 0x00908000L
long lib_version = SSLeay();
/* tls_proxy_context_print - send TLS session state over stream */
int tls_proxy_context_print(ATTR_PRINT_MASTER_FN print_fn, VSTREAM *fp,
- int flags, void *ptr)
+ int flags, void *ptr)
{
TLS_SESS_STATE *tp = (TLS_SESS_STATE *) ptr;
int ret;
STRING_OR_EMPTY(tp->issuer_CN),
ATTR_TYPE_STR, MAIL_ATTR_PEER_FPT,
STRING_OR_EMPTY(tp->peer_fingerprint),
+ ATTR_TYPE_STR, MAIL_ATTR_PEER_PKEY_FPT,
+ STRING_OR_EMPTY(tp->peer_pkey_fprint),
ATTR_TYPE_INT, MAIL_ATTR_PEER_STATUS,
tp->peer_status,
ATTR_TYPE_STR, MAIL_ATTR_CIPHER_PROTOCOL,
/* tls_proxy_context_scan - receive TLS session state from stream */
int tls_proxy_context_scan(ATTR_SCAN_MASTER_FN scan_fn, VSTREAM *fp,
- int flags, void *ptr)
+ int flags, void *ptr)
{
TLS_SESS_STATE *tls_context = (TLS_SESS_STATE *) ptr;
int ret;
VSTRING *peer_CN = vstring_alloc(25);
VSTRING *issuer_CN = vstring_alloc(25);
- VSTRING *peer_fingerprint = vstring_alloc(25);
+ VSTRING *peer_fingerprint = vstring_alloc(60); /* 60 for SHA-1 */
+ VSTRING *peer_pkey_fprint = vstring_alloc(60); /* 60 for SHA-1 */
VSTRING *protocol = vstring_alloc(25);
VSTRING *cipher_name = vstring_alloc(25);
ATTR_TYPE_STR, MAIL_ATTR_PEER_CN, peer_CN,
ATTR_TYPE_STR, MAIL_ATTR_ISSUER_CN, issuer_CN,
ATTR_TYPE_STR, MAIL_ATTR_PEER_FPT, peer_fingerprint,
+ ATTR_TYPE_STR, MAIL_ATTR_PEER_PKEY_FPT, peer_pkey_fprint,
ATTR_TYPE_INT, MAIL_ATTR_PEER_STATUS,
&tls_context->peer_status,
ATTR_TYPE_STR, MAIL_ATTR_CIPHER_PROTOCOL, protocol,
tls_context->peer_CN = vstring_export(peer_CN);
tls_context->issuer_CN = vstring_export(issuer_CN);
tls_context->peer_fingerprint = vstring_export(peer_fingerprint);
+ tls_context->peer_pkey_fprint = vstring_export(peer_pkey_fprint);
tls_context->protocol = vstring_export(protocol);
tls_context->cipher_name = vstring_export(cipher_name);
- return (ret == 8 ? 1 : -1);
+ return (ret == 9 ? 1 : -1);
}
#endif
/*
/* tls_server_start() activates the TLS feature for the VSTREAM
/* passed as argument. We assume that network buffers are flushed
-/* and the TLS handshake can begin immediately.
+/* and the TLS handshake can begin immediately.
/*
/* tls_server_stop() sends the "close notify" alert via
/* SSL_shutdown() to the peer and resets all connection specific
/* programs cannot use the synchronous VSTREAM-over-TLS
/* implementation that the current TLS library provides,
/* including tls_server_stop() and the underlying tls_stream(3)
-/* and tls_bio_ops(3) routines.
+/* and tls_bio_ops(3) routines.
/*
/* With the current TLS library implementation, this means
/* that the application is responsible for calling and retrying
GEN_CACHE_ID(cache_id, session_id, session_id_length, TLScontext->serverid);
- if (TLScontext->log_level >= 2)
+ if (TLScontext->log_mask & TLS_LOG_CACHE)
msg_info("%s: looking up session %s in %s cache", TLScontext->namaddr,
STR(cache_id), TLScontext->cache_type);
if (tls_mgr_lookup(TLScontext->cache_type, STR(cache_id),
session_data) == TLS_MGR_STAT_OK) {
session = tls_session_activate(STR(session_data), LEN(session_data));
- if (session && (TLScontext->log_level >= 2))
+ if (session && (TLScontext->log_mask & TLS_LOG_CACHE))
msg_info("%s: reloaded session %s from %s cache",
TLScontext->namaddr, STR(cache_id),
TLScontext->cache_type);
GEN_CACHE_ID(cache_id, session->session_id, session->session_id_length,
TLScontext->serverid);
- if (TLScontext->log_level >= 2)
+ if (TLScontext->log_mask & TLS_LOG_CACHE)
msg_info("%s: remove session %s from %s cache", TLScontext->namaddr,
STR(cache_id), TLScontext->cache_type);
GEN_CACHE_ID(cache_id, session->session_id, session->session_id_length,
TLScontext->serverid);
- if (TLScontext->log_level >= 2)
+ if (TLScontext->log_mask & TLS_LOG_CACHE)
msg_info("%s: save session %s to %s cache", TLScontext->namaddr,
STR(cache_id), TLScontext->cache_type);
TLS_APPL_STATE *app_ctx;
const EVP_MD *md_alg;
unsigned int md_len;
+ int log_mask;
- if (props->log_level >= 2)
+ /*
+ * Convert user loglevel to internal logmask.
+ */
+ log_mask = tls_log_mask(props->log_param, props->log_level);
+
+ if (log_mask & TLS_LOG_VERBOSE)
msg_info("initializing the server-side TLS engine");
/*
/*
* Set the call-back routine to debug handshake progress.
*/
- if (props->log_level >= 2)
+ if (log_mask & TLS_LOG_DEBUG)
SSL_CTX_set_info_callback(server_ctx, tls_info_callback);
/*
}
/*
- * According to the OpenSSL documentation, temporary RSA key is needed
- * export ciphers are in use. We have to provide one, so well, we just do
- * it.
+ * According to OpenSSL documentation, a temporary RSA key is needed when
+ * export ciphers are in use, because the certified key cannot be
+ * directly used.
*/
SSL_CTX_set_tmp_rsa_callback(server_ctx, tls_tmp_rsa_cb);
* Initialize our own TLS server handle, before diving into the details
* of TLS session cache management.
*/
- app_ctx = tls_alloc_app_context(server_ctx);
+ app_ctx = tls_alloc_app_context(server_ctx, log_mask);
/*
* The session cache is implemented by the tlsmgr(8) server.
TLS_SESS_STATE *TLScontext;
const char *cipher_list;
TLS_APPL_STATE *app_ctx = props->ctx;
+ int log_mask = app_ctx->log_mask;
+
+ /*
+ * Implicitly enable logging of trust chain errors when verified certs
+ * are required.
+ */
+ if (props->requirecert)
+ log_mask |= TLS_LOG_UNTRUSTED;
- if (props->log_level >= 1)
+ if (log_mask & TLS_LOG_VERBOSE)
msg_info("setting up TLS connection from %s", props->namaddr);
cipher_list = tls_set_ciphers(app_ctx, "TLS", props->cipher_grade,
vstring_str(app_ctx->why));
return (0);
}
- if (props->log_level >= 2)
+ if (log_mask & TLS_LOG_VERBOSE)
msg_info("%s: TLS cipher list \"%s\"", props->namaddr, cipher_list);
/*
* structure. Add the location of TLScontext to the SSL to later retrieve
* the information inside the tls_verify_certificate_callback().
*/
- TLScontext = tls_alloc_sess_context(props->log_level, props->namaddr);
+ TLScontext = tls_alloc_sess_context(log_mask, props->namaddr);
TLScontext->cache_type = app_ctx->cache_type;
TLScontext->serverid = mystrdup(props->serverid);
/*
* If the debug level selected is high enough, all of the data is dumped:
- * 3 will dump the SSL negotiation, 4 will dump everything.
+ * TLS_LOG_TLSPKTS will dump the SSL negotiation, TLS_LOG_ALLPKTS will
+ * dump everything.
*
* We do have an SSL_set_fd() and now suddenly a BIO_ routine is called?
* Well there is a BIO below the SSL routines that is automatically
* created for us, so we can use it for debugging purposes.
*/
- if (props->log_level >= 3)
+ if (log_mask & TLS_LOG_TLSPKTS)
BIO_set_callback(SSL_get_rbio(TLScontext->con), tls_bio_dump_cb);
/*
X509 *peer;
char buf[CCERT_BUFSIZ];
- /* Only loglevel==4 dumps everything */
- if (TLScontext->log_level < 4)
+ /* Turn off packet dump if only dumping the handshake */
+ if ((TLScontext->log_mask & TLS_LOG_ALLPKTS) == 0)
BIO_set_callback(SSL_get_rbio(TLScontext->con), 0);
/*
* session was negotiated.
*/
TLScontext->session_reused = SSL_session_reused(TLScontext->con);
- if (TLScontext->log_level >= 2 && TLScontext->session_reused)
+ if ((TLScontext->log_mask & TLS_LOG_CACHE) && TLScontext->session_reused)
msg_info("%s: Reusing old session", TLScontext->namaddr);
/*
if (SSL_get_verify_result(TLScontext->con) == X509_V_OK)
TLScontext->peer_status |= TLS_CERT_FLAG_TRUSTED;
- if (TLScontext->log_level >= 2) {
+ if (TLScontext->log_mask & TLS_LOG_VERBOSE) {
X509_NAME_oneline(X509_get_subject_name(peer),
buf, sizeof(buf));
msg_info("subject=%s", buf);
TLScontext->issuer_CN = tls_issuer_CN(peer, TLScontext);
TLScontext->peer_fingerprint =
tls_fingerprint(peer, TLScontext->fpt_dgst);
+ TLScontext->peer_pkey_fprint =
+ tls_pkey_fprint(peer, TLScontext->fpt_dgst);
- if (TLScontext->log_level >= 1) {
- msg_info("%s: %s: subject_CN=%s, issuer=%s, fingerprint=%s",
+ if (TLScontext->log_mask & (TLS_LOG_VERBOSE | TLS_LOG_PEERCERT)) {
+ msg_info("%s: subject_CN=%s, issuer=%s, fingerprint=%s"
+ ", pkey_fingerprint=%s",
TLScontext->namaddr,
- TLS_CERT_IS_TRUSTED(TLScontext) ? "Trusted" : "Untrusted",
TLScontext->peer_CN, TLScontext->issuer_CN,
- TLScontext->peer_fingerprint);
+ TLScontext->peer_fingerprint,
+ TLScontext->peer_pkey_fprint);
}
X509_free(peer);
} else {
/*
* All the key facts in a single log entry.
*/
- if (TLScontext->log_level >= 1)
+ if (TLScontext->log_mask & TLS_LOG_SUMMARY)
msg_info("%s TLS connection established from %s: %s with cipher %s "
"(%d/%d bits)", !TLS_CERT_IS_PRESENT(TLScontext) ? "Anonymous"
: TLS_CERT_IS_TRUSTED(TLScontext) ? "Trusted" : "Untrusted",
msg_panic("%s: no context", myname);
ret = tls_bio_read(fd, buf, len, timeout, TLScontext);
- if (ret > 0 && TLScontext->log_level >= 4)
+ if (ret > 0 && (TLScontext->log_mask & TLS_LOG_ALLPKTS))
msg_info("Read %ld chars: %.*s",
(long) ret, (int) (ret > 40 ? 40 : ret), (char *) buf);
return (NORMALIZED_VSTREAM_RETURN(ret));
if (!TLScontext)
msg_panic("%s: no context", myname);
- if (TLScontext->log_level >= 4)
+ if (TLScontext->log_mask & TLS_LOG_ALLPKTS)
msg_info("Write %ld chars: %.*s",
(long) len, (int) (len > 40 ? 40 : len), (char *) buf);
ret = tls_bio_write(fd, buf, len, timeout, TLScontext);
ok = 0;
X509_STORE_CTX_set_error(ctx, X509_V_ERR_CERT_CHAIN_TOO_LONG);
}
- if (TLScontext->log_level >= 2) {
+ if (TLScontext->log_mask & TLS_LOG_VERBOSE) {
X509_NAME_oneline(X509_get_subject_name(cert), buf, sizeof(buf));
msg_info("%s: certificate verification depth=%d verify=%d subject=%s",
TLScontext->namaddr, depth, ok, printable(buf, '?'));
/*
* If no errors, or we are not logging verification errors, we are done.
*/
- if (ok || (TLScontext->peer_status & TLS_CERT_FLAG_LOGGED) != 0)
+ if (ok || (TLScontext->log_mask & TLS_LOG_UNTRUSTED) == 0)
return (1);
/*
* One counter-example is enough.
*/
- TLScontext->peer_status |= TLS_CERT_FLAG_LOGGED;
+ TLScontext->log_mask &= ~TLS_LOG_UNTRUSTED;
#define PURPOSE ((depth>0) ? "CA": TLScontext->am_server ? "client": "server")
return (cn ? cn : mystrdup(""));
}
-/* tls_fingerprint - extract fingerprint from certificate */
+typedef int (*x509_dgst_cb) (const X509 *, const EVP_MD *, unsigned char *, unsigned int *);
-char *tls_fingerprint(X509 *peercert, const char *dgst)
+/* tls_fprint - extract cert or pkey fingerprint from certificate */
+
+static char *tls_fprint(X509 *peercert, x509_dgst_cb x509_dgst,
+ const char *dgst)
{
const char *myname = "tls_fingerprint";
const EVP_MD *md_alg;
msg_panic("%s: digest algorithm \"%s\" not found", myname, dgst);
/* Fails when serialization to ASN.1 runs out of memory */
- if (X509_digest(peercert, md_alg, md_buf, &md_len) == 0)
+ if (x509_dgst(peercert, md_alg, md_buf, &md_len) == 0)
msg_fatal("%s: error computing certificate %s digest (out of memory?)",
myname, dgst);
return (result);
}
+/* tls_fingerprint - extract certificate fingerprint */
+
+char *tls_fingerprint(X509 *peercert, const char *dgst)
+{
+ return (tls_fprint(peercert, X509_digest, dgst));
+}
+
+/* tls_pkey_fprint - extract public key fingerprint from certificate */
+
+char *tls_pkey_fprint(X509 *peercert, const char *dgst)
+{
+ return (tls_fprint(peercert, X509_pubkey_digest, dgst));
+}
+
#endif
/* TLS library. */
#ifdef USE_TLS
+#define TLS_INTERNAL
#include <tls.h> /* TLS_MGR_SCACHE_<type> */
#include <tls_prng.h>
#include <tls_scache.h>
int var_tls_rand_bytes;
int var_tls_reseed_period;
int var_tls_prng_exch_period;
-int var_smtpd_tls_loglevel;
+char *var_smtpd_tls_loglevel;
char *var_smtpd_tls_scache_db;
int var_smtpd_tls_scache_timeout;
-int var_smtp_tls_loglevel;
+char *var_smtp_tls_loglevel;
char *var_smtp_tls_scache_db;
int var_smtp_tls_scache_timeout;
-int var_lmtp_tls_loglevel;
+char *var_lmtp_tls_loglevel;
char *var_lmtp_tls_scache_db;
int var_lmtp_tls_scache_timeout;
char *var_tls_rand_exch_name;
TLS_SCACHE *cache_info; /* cache handle */
int cache_active; /* cache status */
char **cache_db; /* main.cf parameter value */
- int *cache_loglevel; /* main.cf parameter value */
+ const char *log_param; /* main.cf parameter name */
+ char **log_level; /* main.cf parameter value */
int *cache_timeout; /* main.cf parameter value */
} TLSMGR_SCACHE;
TLSMGR_SCACHE cache_table[] = {
TLS_MGR_SCACHE_SMTPD, 0, 0, &var_smtpd_tls_scache_db,
+ VAR_SMTPD_TLS_LOGLEVEL,
&var_smtpd_tls_loglevel, &var_smtpd_tls_scache_timeout,
TLS_MGR_SCACHE_SMTP, 0, 0, &var_smtp_tls_scache_db,
+ VAR_SMTP_TLS_LOGLEVEL,
&var_smtp_tls_loglevel, &var_smtp_tls_scache_timeout,
TLS_MGR_SCACHE_LMTP, 0, 0, &var_lmtp_tls_scache_db,
+ VAR_LMTP_TLS_LOGLEVEL,
&var_lmtp_tls_loglevel, &var_lmtp_tls_scache_timeout,
0,
};
ent->cache_info =
tls_scache_open(data_redirect_map(redirect, *ent->cache_db),
ent->cache_label,
- *ent->cache_loglevel >= 2,
+ tls_log_mask(ent->log_param,
+ *ent->log_level) & TLS_LOG_CACHE,
*ent->cache_timeout);
}
}
VAR_SMTPD_TLS_SCACHE_DB, DEF_SMTPD_TLS_SCACHE_DB, &var_smtpd_tls_scache_db, 0, 0,
VAR_SMTP_TLS_SCACHE_DB, DEF_SMTP_TLS_SCACHE_DB, &var_smtp_tls_scache_db, 0, 0,
VAR_LMTP_TLS_SCACHE_DB, DEF_LMTP_TLS_SCACHE_DB, &var_lmtp_tls_scache_db, 0, 0,
+ VAR_SMTPD_TLS_LOGLEVEL, DEF_SMTPD_TLS_LOGLEVEL, &var_smtpd_tls_loglevel, 0, 0,
+ VAR_SMTP_TLS_LOGLEVEL, DEF_SMTP_TLS_LOGLEVEL, &var_smtp_tls_loglevel, 0, 0,
+ VAR_LMTP_TLS_LOGLEVEL, DEF_LMTP_TLS_LOGLEVEL, &var_lmtp_tls_loglevel, 0, 0,
0,
};
static const CONFIG_TIME_TABLE time_table[] = {
};
static const CONFIG_INT_TABLE int_table[] = {
VAR_TLS_RAND_BYTES, DEF_TLS_RAND_BYTES, &var_tls_rand_bytes, 1, 0,
- VAR_SMTPD_TLS_LOGLEVEL, DEF_SMTPD_TLS_LOGLEVEL, &var_smtpd_tls_loglevel, 0, 0,
- VAR_SMTP_TLS_LOGLEVEL, DEF_SMTP_TLS_LOGLEVEL, &var_smtp_tls_loglevel, 0, 0,
- VAR_LMTP_TLS_LOGLEVEL, DEF_LMTP_TLS_LOGLEVEL, &var_lmtp_tls_loglevel, 0, 0,
0,
};
/* List of ciphers or cipher types to exclude from the \fBtlsproxy\fR(8)
/* server cipher list at all TLS security levels.
/* .IP "\fBtlsproxy_tls_fingerprint_digest ($smtpd_tls_fingerprint_digest)\fR"
-/* The message digest algorithm used to construct client-certificate
+/* The message digest algorithm to construct remote SMTP
+/* client-certificate
/* fingerprints.
/* .IP "\fBtlsproxy_tls_key_file ($smtpd_tls_key_file)\fR"
/* File with the Postfix \fBtlsproxy\fR(8) server RSA private key in PEM
/* These parameters are supported for compatibility with
/* \fBsmtpd\fR(8) legacy parameters.
/* .IP "\fBtlsproxy_use_tls ($smtpd_use_tls)\fR"
-/* Opportunistic TLS: announce STARTTLS support to SMTP clients,
+/* Opportunistic TLS: announce STARTTLS support to remote SMTP clients,
/* but do not require that clients use TLS encryption.
/* .IP "\fBtlsproxy_enforce_tls ($smtpd_enforce_tls)\fR"
-/* Mandatory TLS: announce STARTTLS support to SMTP clients, and
+/* Mandatory TLS: announce STARTTLS support to remote SMTP clients, and
/* require that clients use TLS encryption.
/* RESOURCE CONTROLS
/* .ad
* avoid any confusion about which parameters are used by this program.
*/
int var_smtpd_tls_ccert_vd;
-int var_smtpd_tls_loglevel;
+char *var_smtpd_tls_loglevel;
int var_smtpd_tls_scache_timeout;
bool var_smtpd_use_tls;
bool var_smtpd_enforce_tls;
char *var_smtpd_tls_level;
int var_tlsp_tls_ccert_vd;
-int var_tlsp_tls_loglevel;
+char *var_tlsp_tls_loglevel;
int var_tlsp_tls_scache_timeout;
bool var_tlsp_use_tls;
bool var_tlsp_enforce_tls;
ctx = tlsp_server_ctx,
stream = (VSTREAM *) 0,/* unused */
fd = state->ciphertext_fd,
- log_level = var_tlsp_tls_loglevel,
timeout = 0, /* unused */
requirecert = (var_tlsp_tls_req_ccert
&& var_tlsp_enforce_tls),
- serverid = state->service,
+ serverid = MAIL_SERVICE_SMTPD, /* XXX */
namaddr = state->remote_endpt,
cipher_grade = cipher_grade,
cipher_exclusions = STR(cipher_exclusions),
*/
tlsp_server_ctx =
TLS_SERVER_INIT(&props,
+ log_param = VAR_TLSP_TLS_LOGLEVEL,
log_level = var_tlsp_tls_loglevel,
verifydepth = var_tlsp_tls_ccert_vd,
cache_type = TLS_MGR_SCACHE_SMTPD,
{
static const CONFIG_INT_TABLE int_table[] = {
VAR_SMTPD_TLS_CCERT_VD, DEF_SMTPD_TLS_CCERT_VD, &var_smtpd_tls_ccert_vd, 0, 0,
- VAR_SMTPD_TLS_LOGLEVEL, DEF_SMTPD_TLS_LOGLEVEL, &var_smtpd_tls_loglevel, 0, 0,
0,
};
static const CONFIG_NINT_TABLE nint_table[] = {
VAR_TLSP_TLS_CCERT_VD, DEF_TLSP_TLS_CCERT_VD, &var_tlsp_tls_ccert_vd, 0, 0,
- VAR_TLSP_TLS_LOGLEVEL, DEF_TLSP_TLS_LOGLEVEL, &var_tlsp_tls_loglevel, 0, 0,
0,
};
static const CONFIG_TIME_TABLE time_table[] = {
VAR_SMTPD_TLS_1024_FILE, DEF_SMTPD_TLS_1024_FILE, &var_smtpd_tls_dh1024_param_file, 0, 0,
VAR_SMTPD_TLS_EECDH, DEF_SMTPD_TLS_EECDH, &var_smtpd_tls_eecdh, 1, 0,
VAR_SMTPD_TLS_FPT_DGST, DEF_SMTPD_TLS_FPT_DGST, &var_smtpd_tls_fpt_dgst, 1, 0,
+ VAR_SMTPD_TLS_LOGLEVEL, DEF_SMTPD_TLS_LOGLEVEL, &var_smtpd_tls_loglevel, 0, 0,
VAR_SMTPD_TLS_LEVEL, DEF_SMTPD_TLS_LEVEL, &var_smtpd_tls_level, 0, 0,
VAR_TLSP_TLS_CERT_FILE, DEF_TLSP_TLS_CERT_FILE, &var_tlsp_tls_cert_file, 0, 0,
VAR_TLSP_TLS_KEY_FILE, DEF_TLSP_TLS_KEY_FILE, &var_tlsp_tls_key_file, 0, 0,
VAR_TLSP_TLS_1024_FILE, DEF_TLSP_TLS_1024_FILE, &var_tlsp_tls_dh1024_param_file, 0, 0,
VAR_TLSP_TLS_EECDH, DEF_TLSP_TLS_EECDH, &var_tlsp_tls_eecdh, 1, 0,
VAR_TLSP_TLS_FPT_DGST, DEF_TLSP_TLS_FPT_DGST, &var_tlsp_tls_fpt_dgst, 1, 0,
+ VAR_TLSP_TLS_LOGLEVEL, DEF_TLSP_TLS_LOGLEVEL, &var_tlsp_tls_loglevel, 0, 0,
VAR_TLSP_TLS_LEVEL, DEF_TLSP_TLS_LEVEL, &var_tlsp_tls_level, 0, 0,
0,
};
projects / thirdparty / postfix.git / commitdiff
