levels that require no certificate checks. Perhaps it still
makes sense to save such sessions for reuse by less sensitive
deliveries. Files: smtp/smtp.h smtp/smtp_reuse.c.
+
+20180604
+
+ TLS reuse: smtp_tls_connection_reuse boolean parameter, and
+ corresponding override with "connection_reuse" boolean
+ attribute in smtp_policy_maps. Files: global/mail_params.h,
+ smtp.c, smtp.h, smtp_params.c, smtp_proto.c, smtp_session.c,
+ smtp_tls_policy.c. proto/postconf.proto. mantools/postlink.
+
+20180605
+
+ TLS reuse: updated TLS_README and CONNECTION_CACHE_README,
+ added comments in tlsproxy.c to explain why it works.
This document describes the Postfix connection cache implementation, which is
available with Postfix version 2.2 and later.
+See Client-side TLS connection reuse for how this connection cache is used to
+implement multiple deliveries per TLS-encrypted connection.
+
Topics covered in this document:
* What SMTP connection caching can do for you
/-- smtp(8) --> Internet
- qmgr(8) |
- |
- \-- | smtp(8) --> Internet
- |
- ^
- |
+ qmgr(8)
+ |
+ \-- | smtp(8) --> Internet
+ |
+ ^
+ |
- scache(8)
+ scache(8)
When SMTP connection caching is enabled (see next section), the smtp(8) client
does not disconnect after a mail transaction, but gives the connection to the
* Configuring TLS in the SMTP/LMTP client
* Client-side TLS activity logging
* Client-side certificate and private key configuration
+ * Client-side TLS connection reuse
* Client-side TLS session cache
* Client TLS limitations
* Per-destination TLS policy
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 c\bco\bon\bnn\bne\bec\bct\bti\bio\bon\bn r\bre\beu\bus\bse\be
+
+Historically, the Postfix SMTP client has supported multiple deliveries per
+connection only for plaintext connections. Postfix 3.4 introduces the ability
+to make multiple deliveries per TLS-encrypted connection. This is primarily to
+improve mail delivery performance for destinations that throttle clients when
+they don't combine deliveries.
+
+To enable multiple deliveries per TLS connection, specify:
+
+ /etc/postfix/main.cf:
+ smtp_tls_connection_reuse = yes
+
+Alternatively, specify the attribute "connection_reuse=yes" in an
+smtp_tls_policy_maps entry.
+
+The implementation of TLS connection reuse relies on the same scache(8) service
+as used for delivering plaintext SMTP mail, the same tlsproxy(8) daemon as used
+by the postscreen(8) service, and relies on the same hints from the qmgr(8)
+daemon. See "Postfix Connection Cache" for a description of the underlying
+connection reuse infrastructure.
+
+Initial SMTP handshake:
+
+ smtp(8) -> remote SMTP server
+
+Reused SMTP/TLS connection, or new SMTP/TLS connection:
+
+ smtp(8) -> tlsproxy(8) -> remote SMTP server
+
+Cached SMTP/TLS connection:
+
+ scache(8) -> tlsproxy(8) -> remote SMTP server
+
+As of Postfix 3.4, TLS connection reuse is disabled by default. This may change
+once the impact on over-all performance is undestood.
+
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
<p> This document describes the Postfix connection cache implementation,
which is available with Postfix version 2.2 and later. </p>
+<p> See <a href="TLS_README.html#client_tls_reuse">Client-side TLS
+connection reuse</a> for how this connection cache is used to
+implement multiple deliveries per TLS-encrypted connection. </p>
+
<p> Topics covered in this document: </p>
<ul>
<li><a href="#client_cert_key">Client-side certificate and private
key configuration </a>
+<li><a href="#client_tls_reuse">Client-side TLS connection reuse</a>
+
<li><a href="#client_tls_cache">Client-side TLS session cache</a>
<li><a href="#client_tls_limits"> Client TLS limitations </a>
</pre>
</blockquote>
+<h3><a name="client_tls_reuse">Client-side TLS connection reuse</a> </h3>
+
+<p> Historically, the Postfix SMTP client has supported multiple
+deliveries per connection only for plaintext connections. Postfix
+3.4 introduces the ability to make multiple deliveries per TLS-encrypted
+connection. This is primarily to improve mail delivery performance
+for destinations that throttle clients when they don't combine
+deliveries. </p>
+
+<p> To enable multiple deliveries per TLS connection, specify:</p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a> = yes
+</pre>
+</blockquote>
+
+<p> Alternatively, specify the attribute "connection_reuse=yes" in
+an <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> entry. </p>
+
+<p> The implementation of TLS connection reuse relies on the same
+<a href="scache.8.html">scache(8)</a> service as used for delivering plaintext SMTP mail, the
+same <a href="tlsproxy.8.html">tlsproxy(8)</a> daemon as used by the <a href="postscreen.8.html">postscreen(8)</a> service, and
+relies on the same hints from the <a href="qmgr.8.html">qmgr(8)</a> daemon.
+
+See "<a href="CONNECTION_CACHE_README.html">Postfix Connection
+Cache</a>" for a description of the underlying connection reuse
+infrastructure. </p>
+
+<p> Initial SMTP handshake:</p>
+<pre> <a href="smtp.8.html">smtp(8)</a> -> remote SMTP server</pre>
+
+<p> Reused SMTP/TLS connection, or new SMTP/TLS connection: </p>
+<pre> <a href="smtp.8.html">smtp(8)</a> -> <a href="tlsproxy.8.html">tlsproxy(8)</a> -> remote SMTP server </pre>
+
+<p> Cached SMTP/TLS connection:</p>
+<pre> <a href="scache.8.html">scache(8)</a> -> <a href="tlsproxy.8.html">tlsproxy(8)</a> -> remote SMTP server</pre>
+
+<p> As of Postfix 3.4, TLS connection reuse is disabled by default.
+This may change once the impact on over-all performance is undestood.
+</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
nexthop destination security level is <b>dane</b>, but the MX record
was found via an "insecure" MX lookup.
+ Available in Postfix version 3.4 and later:
+
+ <b><a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a> (no)</b>
+ Try to make multiple deliveries per TLS connection.
+
<b>OBSOLETE STARTTLS CONTROLS</b>
The following configuration parameters exist for compatibility with
Postfix versions before 2.3. Support for these will be removed in a
that an SMTP session may be reused before it is closed, or zero
(no limit).
+ Available in Postfix version 3.4 and later:
+
+ <b><a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a> (no)</b>
+ Try to make multiple deliveries per TLS connection.
+
Implemented in the <a href="qmgr.8.html">qmgr(8)</a> daemon:
<b>transport_destination_concurrency_limit ($<a href="postconf.5.html#default_destination_concurrency_limit">default_destination_concur</a>-</b>
<p> This feature is available in Postfix 2.6 and later. </p>
+</DD>
+
+<DT><b><a name="lmtp_tls_connection_reuse">lmtp_tls_connection_reuse</a>
+(default: no)</b></DT><DD>
+
+<p> The LMTP-specific version of the <a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a> configuration
+parameter. See there for details. </p>
+
+<p> This feature is available in Postfix 3.4 and later. </p>
+
+
</DD>
<DT><b><a name="lmtp_tls_dcert_file">lmtp_tls_dcert_file</a>
and opportunistic TLS always uses "export" or better (i.e. all) ciphers. </p>
+</DD>
+
+<DT><b><a name="smtp_tls_connection_reuse">smtp_tls_connection_reuse</a>
+(default: no)</b></DT><DD>
+
+<p> Try to make multiple deliveries per TLS connection. This uses
+the <a href="tlsproxy.8.html">tlsproxy(8)</a> service to make an outbound SMTP-over-TLS connection,
+uses the <a href="scache.8.html">scache(8)</a> service to save that connection, and relies on
+hints from the <a href="qmgr.8.html">qmgr(8)</a> daemon. </p>
+
+<p> See "<a href="TLS_README.html#client_tls_reuse">Client-side
+TLS connection reuse</a>" for background details. </p>
+
+<p> This feature is available in Postfix 3.4 and later. </p>
+
+
</DD>
<DT><b><a name="smtp_tls_dane_insecure_mx_policy">smtp_tls_dane_insecure_mx_policy</a>
<dt><b><a href="TLS_README.html#client_tls_may">may</a></b></dt>
<dd>Opportunistic TLS. Since sending in the clear is acceptable,
demanding stronger than default TLS security merely reduces
-interoperability. The optional "ciphers", "exclude" and "protocols"
+interoperability. The optional "ciphers", "exclude", and "protocols"
attributes (available for opportunistic TLS with Postfix ≥ 2.6)
-override the "<a href="postconf.5.html#smtp_tls_ciphers">smtp_tls_ciphers</a>", "<a href="postconf.5.html#smtp_tls_exclude_ciphers">smtp_tls_exclude_ciphers</a>" and
-"<a href="postconf.5.html#smtp_tls_protocols">smtp_tls_protocols</a>" configuration parameters. When opportunistic TLS
-handshakes fail, Postfix retries the connection with TLS disabled.
+and "connection_reuse" attribute (Postfix ≥ 3.4) override the
+"<a href="postconf.5.html#smtp_tls_ciphers">smtp_tls_ciphers</a>", "<a href="postconf.5.html#smtp_tls_exclude_ciphers">smtp_tls_exclude_ciphers</a>", "<a href="postconf.5.html#smtp_tls_protocols">smtp_tls_protocols</a>",
+and
+"<a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a>" configuration parameters. When opportunistic
+TLS handshakes fail, Postfix retries the connection with TLS disabled.
This allows mail delivery to sites with non-interoperable TLS
implementations.</dd>
<dd>Mandatory TLS encryption. At this level
and higher, the optional "protocols" attribute overrides the <a href="postconf.5.html">main.cf</a>
<a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a> parameter, the optional "ciphers" attribute
-overrides the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_mandatory_ciphers">smtp_tls_mandatory_ciphers</a> parameter, and the
+overrides the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_mandatory_ciphers">smtp_tls_mandatory_ciphers</a> parameter, the
optional "exclude" attribute (Postfix ≥ 2.6) overrides the <a href="postconf.5.html">main.cf</a>
-<a href="postconf.5.html#smtp_tls_mandatory_exclude_ciphers">smtp_tls_mandatory_exclude_ciphers</a> parameter. In the policy table,
+<a href="postconf.5.html#smtp_tls_mandatory_exclude_ciphers">smtp_tls_mandatory_exclude_ciphers</a> parameter, and the optional
+"connection_reuse" attribute (Postfix ≥ 3.4) overrides the
+<a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a> parameter. In the policy table,
multiple protocols or excluded ciphers must be separated by colons,
as attribute values may not contain whitespace or commas. </dd>
TLSA records are obtained for the remote SMTP server, the
server certificate must match the TLSA records. <a href="http://tools.ietf.org/html/rfc7672">RFC 7672</a> (DANE)
TLS authentication and DNSSEC support is available with Postfix
-2.11 and later. </dd>
+2.11 and later. The optional "connection_reuse" attribute (Postfix
+≥ 3.4) overrides the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a> parameter.
+</dd>
<dt><b><a href="TLS_README.html#client_tls_dane">dane-only</a></b></dt>
<dd>Mandatory DANE TLS. The TLS policy for the destination is
usable TLSA records are obtained for the remote SMTP server, the
server certificate must match the TLSA records. <a href="http://tools.ietf.org/html/rfc7672">RFC 7672</a> (DANE) TLS
authentication and DNSSEC support is available with Postfix 2.11
-and later. </dd>
+and later. The optional "connection_reuse" attribute (Postfix ≥
+3.4) overrides the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a> parameter.
+</dd>
<dt><b><a href="TLS_README.html#client_tls_fprint">fingerprint</a></b></dt>
<dd>Certificate fingerprint
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. </dd>
+digits. The optional "connection_reuse" attribute (Postfix ≥ 3.4)
+overrides the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a> parameter. </dd>
<dt><b><a href="TLS_README.html#client_tls_verify">verify</a></b></dt>
<dd>Mandatory TLS verification. At this security
the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_verify_cert_match">smtp_tls_verify_cert_match</a> parameter. In the policy table,
multiple match patterns and strategies must be separated by colons.
In practice explicit control over matching is more common with the
-"secure" policy, described below. </dd>
+"secure" policy, described below. The optional "connection_reuse"
+attribute (Postfix ≥ 3.4) overrides the <a href="postconf.5.html">main.cf</a>
+<a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a> parameter. </dd>
<dt><b><a href="TLS_README.html#client_tls_secure">secure</a></b></dt>
<dd>Secure-channel TLS. At this security level, DNS
verification, they risk delivery to the wrong destination when domains
change hands or are re-assigned to new gateways. With the "match"
attribute approach, routing is not perturbed, and mail is deferred if
-verification of a new MX host fails. </dd>
+verification of a new MX host fails. The optional "connection_reuse"
+attribute (Postfix ≥ 3.4) overrides the <a href="postconf.5.html">main.cf</a>
+<a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a> parameter. </dd>
</dl>
Postfix 2.3 and later use <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> instead. </p>
-</DD>
-
-<DT><b><a name="smtp_use_tlsproxy">smtp_use_tlsproxy</a>
-(default: no)</b></DT><DD>
-
-<p> The LMTP-specific version of the <a href="postconf.5.html#smtp_use_tlsproxy">smtp_use_tlsproxy</a> configuration
-parameter. See there for details. </p>
-
-<p> This feature is available in Postfix 3.4 and later. </p>
-
-
</DD>
<DT><b><a name="smtp_xforward_timeout">smtp_xforward_timeout</a>
nexthop destination security level is <b>dane</b>, but the MX record
was found via an "insecure" MX lookup.
+ Available in Postfix version 3.4 and later:
+
+ <b><a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a> (no)</b>
+ Try to make multiple deliveries per TLS connection.
+
<b>OBSOLETE STARTTLS CONTROLS</b>
The following configuration parameters exist for compatibility with
Postfix versions before 2.3. Support for these will be removed in a
that an SMTP session may be reused before it is closed, or zero
(no limit).
+ Available in Postfix version 3.4 and later:
+
+ <b><a href="postconf.5.html#smtp_tls_connection_reuse">smtp_tls_connection_reuse</a> (no)</b>
+ Try to make multiple deliveries per TLS connection.
+
Implemented in the <a href="qmgr.8.html">qmgr(8)</a> daemon:
<b>transport_destination_concurrency_limit ($<a href="postconf.5.html#default_destination_concurrency_limit">default_destination_concur</a>-</b>
<b>tlsproxy</b> [generic Postfix daemon options]
<b>DESCRIPTION</b>
- The <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server implements a server-side TLS proxy. It is used
- by <a href="postscreen.8.html"><b>postscreen</b>(8)</a> to talk SMTP-over-TLS with remote SMTP clients that
- are not whitelisted (including clients whose whitelist status has
- expired), but it should also work for non-SMTP protocols.
-
- Although one <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> process can serve multiple sessions at the
- same time, it is a good idea to allow the number of processes to
+ The <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server implements a two-way TLS proxy. It is used by
+ the <a href="postscreen.8.html"><b>postscreen</b>(8)</a> server to talk SMTP-over-TLS with remote SMTP clients
+ that are not whitelisted (including clients whose whitelist status has
+ expired), and by the <a href="smtp.8.html"><b>smtp</b>(8)</a> client to support TLS connection reuse,
+ but it should also work for non-SMTP protocols.
+
+ Although one <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> process can serve multiple sessions at the
+ same time, it is a good idea to allow the number of processes to
increase with load, so that the service remains responsive.
<b>PROTOCOL EXAMPLE</b>
- The
example below concerns <a href="postscreen.8.html"><b>postscreen</b>(8)</a>. However, the <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>
+ The
example below concerns <a href="postscreen.8.html"><b>postscreen</b>(8)</a>. However, the <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>
server is agnostic of the application protocol, and the example is eas-
ily adapted to other applications.
- After receiving a valid remote SMTP client STARTTLS command, the
- <a href="postscreen.8.html"><b>postscreen</b>(8)</a> server sends the remote SMTP client endpoint string, the
- requested
role (server), and the requested timeout to <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>.
- <a href="postscreen.8.html"><b>postscreen</b>(8)</a> then receives a "TLS available" indication from
- <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>. If the TLS service is available, <a href="postscreen.8.html"><b>postscreen</b>(8)</a> sends the
+ After receiving a valid remote SMTP client STARTTLS command, the
+ <a href="postscreen.8.html"><b>postscreen</b>(8)</a> server sends the remote SMTP client endpoint string, the
+ requested
role (server), and the requested timeout to <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>.
+ <a href="postscreen.8.html"><b>postscreen</b>(8)</a> then receives a "TLS available" indication from
+ <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>. If the TLS service is available, <a href="postscreen.8.html"><b>postscreen</b>(8)</a> sends the
remote SMTP client file descriptor to <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>, and sends the plain-
text 220 greeting to the remote SMTP client. This triggers TLS negoti-
ations between the remote SMTP client and <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>. Upon completion
- of the TLS-level handshake, <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> translates between plaintext
+ of the TLS-level handshake, <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> translates between plaintext
from/to <a href="postscreen.8.html"><b>postscreen</b>(8)</a> and ciphertext to/from the remote SMTP client.
<b>SECURITY</b>
- The <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server is moderately security-sensitive. It talks to
- untrusted clients on the network. The process can be run chrooted at
+ The <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server is moderately security-sensitive. It talks to
+ untrusted clients on the network. The process can be run chrooted at
fixed low privilege.
<b>DIAGNOSTICS</b>
<b>CONFIGURATION PARAMETERS</b>
Changes to <a href="postconf.5.html"><b>main.cf</b></a> are not picked up automatically, as <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> pro-
- cesses may run for a long time depending on mail server load. Use the
+ cesses may run for a long time depending on mail server load. Use the
command "<b>postfix reload</b>" to speed up a change.
- The text below provides only a parameter summary. See <a href="postconf.5.html"><b>postconf</b>(5)</a> for
+ 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>STARTTLS SUPPORT CONTROLS</b>
<b><a href="postconf.5.html#tlsproxy_tls_CAfile">tlsproxy_tls_CAfile</a> ($<a href="postconf.5.html#smtpd_tls_CAfile">smtpd_tls_CAfile</a>)</b>
- A file containing (PEM format) CA certificates of root CAs
+ A file containing (PEM format) CA certificates of root CAs
trusted to sign either remote SMTP client certificates or inter-
mediate CA certificates.
<b><a href="postconf.5.html#tlsproxy_tls_CApath">tlsproxy_tls_CApath</a> ($<a href="postconf.5.html#smtpd_tls_CApath">smtpd_tls_CApath</a>)</b>
- A directory containing (PEM format) CA certificates of root CAs
+ A directory containing (PEM format) CA certificates of root CAs
trusted to sign either remote SMTP client certificates or inter-
mediate CA certificates.
<b><a href="postconf.5.html#tlsproxy_tls_always_issue_session_ids">tlsproxy_tls_always_issue_session_ids</a> ($<a href="postconf.5.html#smtpd_tls_always_issue_session_ids">smtpd_tls_always_issue_ses</a>-</b>
<b><a href="postconf.5.html#smtpd_tls_always_issue_session_ids">sion_ids</a>)</b>
- Force the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server to issue a TLS session id,
+ Force the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server to issue a TLS session id,
even when TLS session caching is turned off.
<b><a href="postconf.5.html#tlsproxy_tls_ask_ccert">tlsproxy_tls_ask_ccert</a> ($<a href="postconf.5.html#smtpd_tls_ask_ccert">smtpd_tls_ask_ccert</a>)</b>
The verification depth for remote SMTP client certificates.
<b><a href="postconf.5.html#tlsproxy_tls_cert_file">tlsproxy_tls_cert_file</a> ($<a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a>)</b>
- File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server RSA certificate in PEM
+ File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server RSA certificate in PEM
format.
<b><a href="postconf.5.html#tlsproxy_tls_ciphers">tlsproxy_tls_ciphers</a> ($<a href="postconf.5.html#smtpd_tls_ciphers">smtpd_tls_ciphers</a>)</b>
will use with opportunistic TLS encryption.
<b><a href="postconf.5.html#tlsproxy_tls_dcert_file">tlsproxy_tls_dcert_file</a> ($<a href="postconf.5.html#smtpd_tls_dcert_file">smtpd_tls_dcert_file</a>)</b>
- File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server DSA certificate in PEM
+ File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server DSA certificate in PEM
format.
<b><a href="postconf.5.html#tlsproxy_tls_dh1024_param_file">tlsproxy_tls_dh1024_param_file</a> ($<a href="postconf.5.html#smtpd_tls_dh1024_param_file">smtpd_tls_dh1024_param_file</a>)</b>
- File with DH parameters that the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server
+ File with DH parameters that the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server
should use with non-export EDH ciphers.
<b><a href="postconf.5.html#tlsproxy_tls_dh512_param_file">tlsproxy_tls_dh512_param_file</a> ($<a href="postconf.5.html#smtpd_tls_dh512_param_file">smtpd_tls_dh512_param_file</a>)</b>
- File with DH parameters that the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server
+ File with DH parameters that the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server
should use with export-grade EDH ciphers.
<b><a href="postconf.5.html#tlsproxy_tls_dkey_file">tlsproxy_tls_dkey_file</a> ($<a href="postconf.5.html#smtpd_tls_dkey_file">smtpd_tls_dkey_file</a>)</b>
- File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server DSA private key in PEM
+ File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server DSA private key in PEM
format.
<b><a href="postconf.5.html#tlsproxy_tls_eccert_file">tlsproxy_tls_eccert_file</a> ($<a href="postconf.5.html#smtpd_tls_eccert_file">smtpd_tls_eccert_file</a>)</b>
- File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server ECDSA certificate in
+ File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server ECDSA certificate in
PEM format.
<b><a href="postconf.5.html#tlsproxy_tls_eckey_file">tlsproxy_tls_eckey_file</a> ($<a href="postconf.5.html#smtpd_tls_eckey_file">smtpd_tls_eckey_file</a>)</b>
- File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server ECDSA private key in
+ File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server ECDSA private key in
PEM format.
<b><a href="postconf.5.html#tlsproxy_tls_eecdh_grade">tlsproxy_tls_eecdh_grade</a> ($<a href="postconf.5.html#smtpd_tls_eecdh_grade">smtpd_tls_eecdh_grade</a>)</b>
- The Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server security grade for ephemeral
+ The Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server security grade for ephemeral
elliptic-curve Diffie-Hellman (EECDH) key exchange.
<b><a href="postconf.5.html#tlsproxy_tls_exclude_ciphers">tlsproxy_tls_exclude_ciphers</a> ($<a href="postconf.5.html#smtpd_tls_exclude_ciphers">smtpd_tls_exclude_ciphers</a>)</b>
- List
of ciphers or cipher types to exclude from the <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>
+ List
of ciphers or cipher types to exclude from the <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a>
server cipher list at all TLS security levels.
<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_fingerprint_digest</a>)</b>
- The message digest algorithm to construct remote SMTP
+ 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 private key in PEM
+ File with the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server RSA private key in PEM
format.
<b><a href="postconf.5.html#tlsproxy_tls_loglevel">tlsproxy_tls_loglevel</a> ($<a href="postconf.5.html#smtpd_tls_loglevel">smtpd_tls_loglevel</a>)</b>
- Enable additional Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server logging of TLS
+ Enable additional Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server logging of TLS
activity.
<b><a href="postconf.5.html#tlsproxy_tls_mandatory_ciphers">tlsproxy_tls_mandatory_ciphers</a> ($<a href="postconf.5.html#smtpd_tls_mandatory_ciphers">smtpd_tls_mandatory_ciphers</a>)</b>
<b><a href="postconf.5.html#tlsproxy_tls_mandatory_exclude_ciphers">tlsproxy_tls_mandatory_exclude_ciphers</a> ($<a href="postconf.5.html#smtpd_tls_mandatory_exclude_ciphers">smtpd_tls_manda</a>-</b>
<b><a href="postconf.5.html#smtpd_tls_mandatory_exclude_ciphers">tory_exclude_ciphers</a>)</b>
- Additional list of ciphers or cipher types to exclude from the
+ Additional list of ciphers or cipher types to exclude from the
<a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server cipher list at mandatory TLS security levels.
<b><a href="postconf.5.html#tlsproxy_tls_mandatory_protocols">tlsproxy_tls_mandatory_protocols</a> ($<a href="postconf.5.html#smtpd_tls_mandatory_protocols">smtpd_tls_mandatory_protocols</a>)</b>
with mandatory TLS encryption.
<b><a href="postconf.5.html#tlsproxy_tls_protocols">tlsproxy_tls_protocols</a> ($<a href="postconf.5.html#smtpd_tls_protocols">smtpd_tls_protocols</a>)</b>
- List of TLS protocols that the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server will
+ List of TLS protocols that the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server will
exclude or include with opportunistic TLS encryption.
<b><a href="postconf.5.html#tlsproxy_tls_req_ccert">tlsproxy_tls_req_ccert</a> ($<a href="postconf.5.html#smtpd_tls_req_ccert">smtpd_tls_req_ccert</a>)</b>
- With mandatory TLS encryption, require a trusted remote SMTP
+ With mandatory TLS encryption, require a trusted remote SMTP
client certificate in order to allow TLS connections to proceed.
<b><a href="postconf.5.html#tlsproxy_tls_security_level">tlsproxy_tls_security_level</a> ($<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a>)</b>
- The SMTP TLS security level for the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server;
+ The SMTP TLS security level for the Postfix <a href="tlsproxy.8.html"><b>tlsproxy</b>(8)</a> server;
when a non-empty value is specified, this overrides the obsolete
parameters <a href="postconf.5.html#smtpd_use_tls">smtpd_use_tls</a> and <a href="postconf.5.html#smtpd_enforce_tls">smtpd_enforce_tls</a>.
The name of the <a href="tlsmgr.8.html"><b>tlsmgr</b>(8)</a> service entry in <a href="master.5.html">master.cf</a>.
<b>OBSOLETE STARTTLS SUPPORT CONTROLS</b>
- These parameters are supported for compatibility with <a href="smtpd.8.html"><b>smtpd</b>(8)</a> legacy
+ These parameters are supported for compatibility with <a href="smtpd.8.html"><b>smtpd</b>(8)</a> legacy
parameters.
<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 remote SMTP
+ Opportunistic TLS: announce STARTTLS support to 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>
<b>MISCELLANEOUS CONTROLS</b>
<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 <a href="master.5.html">master.cf</a> con-
+ The default location of the Postfix <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> con-
figuration files.
<b><a href="postconf.5.html#process_id">process_id</a> (read-only)</b>
The syslog facility of Postfix logging.
<b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b>
- A prefix that is prepended to the process name in syslog
+ A prefix that is prepended to the process name in syslog
records, so that, for example, "smtpd" becomes "prefix/smtpd".
Available in Postfix 3.3 and later:
parameter. See there for details.
.PP
This feature is available in Postfix 2.6 and later.
+.SH lmtp_tls_connection_reuse (default: no)
+The LMTP\-specific version of the smtp_tls_connection_reuse configuration
+parameter. See there for details.
+.PP
+This feature is available in Postfix 3.4 and later.
.SH lmtp_tls_dcert_file (default: empty)
The LMTP\-specific version of the smtp_tls_dcert_file
configuration parameter. See there for details.
This feature is available in Postfix 2.6 and later. With earlier Postfix
releases only the smtp_tls_mandatory_ciphers parameter is implemented,
and opportunistic TLS always uses "export" or better (i.e. all) ciphers.
+.SH smtp_tls_connection_reuse (default: no)
+Try to make multiple deliveries per TLS connection. This uses
+the \fBtlsproxy\fR(8) service to make an outbound SMTP\-over\-TLS connection,
+uses the \fBscache\fR(8) service to save that connection, and relies on
+hints from the \fBqmgr\fR(8) daemon.
+.PP
+See "Client\-side
+TLS connection reuse" for background details.
+.PP
+This feature is available in Postfix 3.4 and later.
.SH smtp_tls_dane_insecure_mx_policy (default: dane)
The TLS policy for MX hosts with "secure" TLSA records when the
nexthop destination security level is \fBdane\fR, but the MX
.IP "\fBmay\fR"
Opportunistic TLS. Since sending in the clear is acceptable,
demanding stronger than default TLS security merely reduces
-interoperability. The optional "ciphers", "exclude" and "protocols"
+interoperability. The optional "ciphers", "exclude", and "protocols"
attributes (available for opportunistic TLS with Postfix >= 2.6)
-override the "smtp_tls_ciphers", "smtp_tls_exclude_ciphers" and
-"smtp_tls_protocols" configuration parameters. When opportunistic TLS
-handshakes fail, Postfix retries the connection with TLS disabled.
+and "connection_reuse" attribute (Postfix >= 3.4) override the
+"smtp_tls_ciphers", "smtp_tls_exclude_ciphers", "smtp_tls_protocols",
+and
+"smtp_tls_connection_reuse" configuration parameters. When opportunistic
+TLS handshakes fail, Postfix retries the connection with TLS disabled.
This allows mail delivery to sites with non\-interoperable TLS
implementations.
.br
Mandatory TLS encryption. At this level
and higher, the optional "protocols" attribute overrides the main.cf
smtp_tls_mandatory_protocols parameter, the optional "ciphers" attribute
-overrides the main.cf smtp_tls_mandatory_ciphers parameter, and the
+overrides the main.cf smtp_tls_mandatory_ciphers parameter, the
optional "exclude" attribute (Postfix >= 2.6) overrides the main.cf
-smtp_tls_mandatory_exclude_ciphers parameter. In the policy table,
+smtp_tls_mandatory_exclude_ciphers parameter, and the optional
+"connection_reuse" attribute (Postfix >= 3.4) overrides the
+main.cf smtp_tls_connection_reuse parameter. In the policy table,
multiple protocols or excluded ciphers must be separated by colons,
as attribute values may not contain whitespace or commas.
.br
TLSA records are obtained for the remote SMTP server, the
server certificate must match the TLSA records. RFC 7672 (DANE)
TLS authentication and DNSSEC support is available with Postfix
-2.11 and later.
+2.11 and later. The optional "connection_reuse" attribute (Postfix
+>= 3.4) overrides the main.cf smtp_tls_connection_reuse parameter.
.br
.IP "\fBdane\-only\fR"
Mandatory DANE TLS. The TLS policy for the destination is
usable TLSA records are obtained for the remote SMTP server, the
server certificate must match the TLSA records. RFC 7672 (DANE) TLS
authentication and DNSSEC support is available with Postfix 2.11
-and later.
+and later. The optional "connection_reuse" attribute (Postfix >=
+3.4) overrides the main.cf smtp_tls_connection_reuse parameter.
.br
.IP "\fBfingerprint\fR"
Certificate fingerprint
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.
+digits. The optional "connection_reuse" attribute (Postfix >= 3.4)
+overrides the main.cf smtp_tls_connection_reuse parameter.
.br
.IP "\fBverify\fR"
Mandatory TLS verification. At this security
the main.cf smtp_tls_verify_cert_match parameter. In the policy table,
multiple match patterns and strategies must be separated by colons.
In practice explicit control over matching is more common with the
-"secure" policy, described below.
+"secure" policy, described below. The optional "connection_reuse"
+attribute (Postfix >= 3.4) overrides the main.cf
+smtp_tls_connection_reuse parameter.
.br
.IP "\fBsecure\fR"
Secure\-channel TLS. At this security level, DNS
verification, they risk delivery to the wrong destination when domains
change hands or are re\-assigned to new gateways. With the "match"
attribute approach, routing is not perturbed, and mail is deferred if
-verification of a new MX host fails.
+verification of a new MX host fails. The optional "connection_reuse"
+attribute (Postfix >= 3.4) overrides the main.cf
+smtp_tls_connection_reuse parameter.
.br
.br
.PP
.PP
This feature is available in Postfix 2.2 and later. With
Postfix 2.3 and later use smtp_tls_security_level instead.
-.SH smtp_use_tlsproxy (default: no)
-The LMTP\-specific version of the smtp_use_tlsproxy configuration
-parameter. See there for details.
-.PP
-This feature is available in Postfix 3.4 and later.
.SH smtp_xforward_timeout (default: 300s)
The Postfix SMTP client time limit for sending the XFORWARD command,
and for receiving the remote SMTP server response.
The TLS policy for MX hosts with "secure" TLSA records when the
nexthop destination security level is \fBdane\fR, but the MX
record was found via an "insecure" MX lookup.
+.PP
+Available in Postfix version 3.4 and later:
+.IP "\fBsmtp_tls_connection_reuse (no)\fR"
+Try to make multiple deliveries per TLS connection.
.SH "OBSOLETE STARTTLS CONTROLS"
.na
.nf
that an SMTP session may be reused before it is closed, or zero (no
limit).
.PP
+Available in Postfix version 3.4 and later:
+.IP "\fBsmtp_tls_connection_reuse (no)\fR"
+Try to make multiple deliveries per TLS connection.
+.PP
Implemented in the qmgr(8) daemon:
.IP "\fBtransport_destination_concurrency_limit ($default_destination_concurrency_limit)\fR"
A transport\-specific override for the
.SH DESCRIPTION
.ad
.fi
-The \fBtlsproxy\fR(8) server implements a server\-side TLS
-proxy. It is used by \fBpostscreen\fR(8) to talk SMTP\-over\-TLS
+The \fBtlsproxy\fR(8) server implements a two\-way TLS proxy. It
+is used by the \fBpostscreen\fR(8) server to talk SMTP\-over\-TLS
with remote SMTP clients that are not whitelisted (including
-clients whose whitelist status has expired),
-but it should also work for non\-SMTP protocols.
+clients whose whitelist status has expired), and by the
+\fBsmtp\fR(8) client to support TLS connection reuse, but it
+should also work for non\-SMTP protocols.
Although one \fBtlsproxy\fR(8) process can serve multiple
sessions at the same time, it is a good idea to allow the
s;\bsmtp_per_record_deadline\b;<a href="postconf.5.html#smtp_per_record_deadline">$&</a>;g;
s;\bsmtp_send_dummy_mail_auth\b;<a href="postconf.5.html#smtp_send_dummy_mail_auth">$&</a>;g;
s;\bsmtp_balance_inet_protocols\b;<a href="postconf.5.html#smtp_balance_inet_protocols">$&</a>;g;
- s;\bsmtp_use_tlsproxy\b;<a href="postconf.5.html#smtp_use_tlsproxy">$&</a>;g;
- s;\blmtp_use_tlsproxy\b;<a href="postconf.5.html#lmtp_use_tlsproxy">$&</a>;g;
+ s;\bsmtp_tls_connection_reuse\b;<a href="postconf.5.html#smtp_tls_connection_reuse">$&</a>;g;
+ s;\blmtp_tls_connection_reuse\b;<a href="postconf.5.html#lmtp_tls_connection_reuse">$&</a>;g;
s;\bsmtpd_enforce_tls\b;<a href="postconf.5.html#smtpd_enforce_tls">$&</a>;g;
s;\bsmtpd_sasl_tls_security_options\b;<a href="postconf.5.html#smtpd_sasl_tls_security_options">$&</a>;g;
s;\bsmtpd_sasl_type\b;<a href="postconf.5.html#smtpd_sasl_type">$&</a>;g;
<p> This document describes the Postfix connection cache implementation,
which is available with Postfix version 2.2 and later. </p>
+<p> See <a href="TLS_README.html#client_tls_reuse">Client-side TLS
+connection reuse</a> for how this connection cache is used to
+implement multiple deliveries per TLS-encrypted connection. </p>
+
<p> Topics covered in this document: </p>
<ul>
<li><a href="#client_cert_key">Client-side certificate and private
key configuration </a>
+<li><a href="#client_tls_reuse">Client-side TLS connection reuse</a>
+
<li><a href="#client_tls_cache">Client-side TLS session cache</a>
<li><a href="#client_tls_limits"> Client TLS limitations </a>
</pre>
</blockquote>
+<h3><a name="client_tls_reuse">Client-side TLS connection reuse</a> </h3>
+
+<p> Historically, the Postfix SMTP client has supported multiple
+deliveries per connection only for plaintext connections. Postfix
+3.4 introduces the ability to make multiple deliveries per TLS-encrypted
+connection. This is primarily to improve mail delivery performance
+for destinations that throttle clients when they don't combine
+deliveries. </p>
+
+<p> To enable multiple deliveries per TLS connection, specify:</p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_tls_connection_reuse = yes
+</pre>
+</blockquote>
+
+<p> Alternatively, specify the attribute "connection_reuse=yes" in
+an smtp_tls_policy_maps entry. </p>
+
+<p> The implementation of TLS connection reuse relies on the same
+scache(8) service as used for delivering plaintext SMTP mail, the
+same tlsproxy(8) daemon as used by the postscreen(8) service, and
+relies on the same hints from the qmgr(8) daemon.
+
+See "<a href="CONNECTION_CACHE_README.html">Postfix Connection
+Cache</a>" for a description of the underlying connection reuse
+infrastructure. </p>
+
+<p> Initial SMTP handshake:</p>
+<pre> smtp(8) -> remote SMTP server</pre>
+
+<p> Reused SMTP/TLS connection, or new SMTP/TLS connection: </p>
+<pre> smtp(8) -> tlsproxy(8) -> remote SMTP server </pre>
+
+<p> Cached SMTP/TLS connection:</p>
+<pre> scache(8) -> tlsproxy(8) -> remote SMTP server</pre>
+
+<p> As of Postfix 3.4, TLS connection reuse is disabled by default.
+This may change once the impact on over-all performance is undestood.
+</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
<dt><b><a href="TLS_README.html#client_tls_may">may</a></b></dt>
<dd>Opportunistic TLS. Since sending in the clear is acceptable,
demanding stronger than default TLS security merely reduces
-interoperability. The optional "ciphers", "exclude" and "protocols"
+interoperability. The optional "ciphers", "exclude", and "protocols"
attributes (available for opportunistic TLS with Postfix ≥ 2.6)
-override the "smtp_tls_ciphers", "smtp_tls_exclude_ciphers" and
-"smtp_tls_protocols" configuration parameters. When opportunistic TLS
-handshakes fail, Postfix retries the connection with TLS disabled.
+and "connection_reuse" attribute (Postfix ≥ 3.4) override the
+"smtp_tls_ciphers", "smtp_tls_exclude_ciphers", "smtp_tls_protocols",
+and
+"smtp_tls_connection_reuse" configuration parameters. When opportunistic
+TLS handshakes fail, Postfix retries the connection with TLS disabled.
This allows mail delivery to sites with non-interoperable TLS
implementations.</dd>
<dd>Mandatory TLS encryption. At this level
and higher, the optional "protocols" attribute overrides the main.cf
smtp_tls_mandatory_protocols parameter, the optional "ciphers" attribute
-overrides the main.cf smtp_tls_mandatory_ciphers parameter, and the
+overrides the main.cf smtp_tls_mandatory_ciphers parameter, the
optional "exclude" attribute (Postfix ≥ 2.6) overrides the main.cf
-smtp_tls_mandatory_exclude_ciphers parameter. In the policy table,
+smtp_tls_mandatory_exclude_ciphers parameter, and the optional
+"connection_reuse" attribute (Postfix ≥ 3.4) overrides the
+main.cf smtp_tls_connection_reuse parameter. In the policy table,
multiple protocols or excluded ciphers must be separated by colons,
as attribute values may not contain whitespace or commas. </dd>
TLSA records are obtained for the remote SMTP server, the
server certificate must match the TLSA records. RFC 7672 (DANE)
TLS authentication and DNSSEC support is available with Postfix
-2.11 and later. </dd>
+2.11 and later. The optional "connection_reuse" attribute (Postfix
+≥ 3.4) overrides the main.cf smtp_tls_connection_reuse parameter.
+</dd>
<dt><b><a href="TLS_README.html#client_tls_dane">dane-only</a></b></dt>
<dd>Mandatory DANE TLS. The TLS policy for the destination is
usable TLSA records are obtained for the remote SMTP server, the
server certificate must match the TLSA records. RFC 7672 (DANE) TLS
authentication and DNSSEC support is available with Postfix 2.11
-and later. </dd>
+and later. The optional "connection_reuse" attribute (Postfix ≥
+3.4) overrides the main.cf smtp_tls_connection_reuse parameter.
+</dd>
<dt><b><a href="TLS_README.html#client_tls_fprint">fingerprint</a></b></dt>
<dd>Certificate fingerprint
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. </dd>
+digits. The optional "connection_reuse" attribute (Postfix ≥ 3.4)
+overrides the main.cf smtp_tls_connection_reuse parameter. </dd>
<dt><b><a href="TLS_README.html#client_tls_verify">verify</a></b></dt>
<dd>Mandatory TLS verification. At this security
the main.cf smtp_tls_verify_cert_match parameter. In the policy table,
multiple match patterns and strategies must be separated by colons.
In practice explicit control over matching is more common with the
-"secure" policy, described below. </dd>
+"secure" policy, described below. The optional "connection_reuse"
+attribute (Postfix ≥ 3.4) overrides the main.cf
+smtp_tls_connection_reuse parameter. </dd>
<dt><b><a href="TLS_README.html#client_tls_secure">secure</a></b></dt>
<dd>Secure-channel TLS. At this security level, DNS
verification, they risk delivery to the wrong destination when domains
change hands or are re-assigned to new gateways. With the "match"
attribute approach, routing is not perturbed, and mail is deferred if
-verification of a new MX host fails. </dd>
+verification of a new MX host fails. The optional "connection_reuse"
+attribute (Postfix ≥ 3.4) overrides the main.cf
+smtp_tls_connection_reuse parameter. </dd>
</dl>
<p> This feature is available in Postfix 3.0 and later. </p>
-%PARAM smtp_use_tlsproxy no
+%PARAM smtp_tls_connection_reuse no
-<p> Try to use a TLS session multiple times, without reconnecting.
-This uses the tlsproxy(8) service to make an outbound SMTP-over-TLS
-connection, and uses the sache(8) service to save that connection.
-</p>
+<p> Try to make multiple deliveries per TLS connection. This uses
+the tlsproxy(8) service to make an outbound SMTP-over-TLS connection,
+uses the scache(8) service to save that connection, and relies on
+hints from the qmgr(8) daemon. </p>
+
+<p> See "<a href="TLS_README.html#client_tls_reuse">Client-side
+TLS connection reuse</a>" for background details. </p>
<p> This feature is available in Postfix 3.4 and later. </p>
-%PARAM smtp_use_tlsproxy no
+%PARAM lmtp_tls_connection_reuse no
-<p> The LMTP-specific version of the smtp_use_tlsproxy configuration
+<p> The LMTP-specific version of the smtp_tls_connection_reuse configuration
parameter. See there for details. </p>
<p> This feature is available in Postfix 3.4 and later. </p>
/*
* Share TLS sessions through tlproxy(8).
*/
-#define VAR_SMTP_USE_TLSPROXY "smtp_use_tlsproxy"
-#define DEF_SMTP_USE_TLSPROXY 0
-#define VAR_LMTP_USE_TLSPROXY "lmtp_use_tlsproxy"
-#define DEF_LMTP_USE_TLSPROXY 0
-extern bool var_smtp_use_tlsproxy;
+#define VAR_SMTP_TLS_CONN_REUSE "smtp_tls_connection_reuse"
+#define DEF_SMTP_TLS_CONN_REUSE 0
+#define VAR_LMTP_TLS_CONN_REUSE "lmtp_tls_connection_reuse"
+#define DEF_LMTP_TLS_CONN_REUSE 0
+extern bool var_smtp_tls_conn_reuse;
/*
* Location of shared-library files.
* Patches change both the patchlevel and the release date. Snapshots have no
* patchlevel; they change the release date only.
*/
-#define MAIL_RELEASE_DATE "20180603"
+#define MAIL_RELEASE_DATE "20180605"
#define MAIL_VERSION_NUMBER "3.4"
#ifdef SNAPSHOT
VAR_LMTP_CACHE_DEMAND, DEF_LMTP_CACHE_DEMAND, &var_smtp_cache_demand,
VAR_LMTP_USE_TLS, DEF_LMTP_USE_TLS, &var_smtp_use_tls,
VAR_LMTP_ENFORCE_TLS, DEF_LMTP_ENFORCE_TLS, &var_smtp_enforce_tls,
- VAR_LMTP_USE_TLSPROXY, DEF_LMTP_USE_TLSPROXY, &var_smtp_use_tlsproxy,
+ VAR_LMTP_TLS_CONN_REUSE, DEF_LMTP_TLS_CONN_REUSE, &var_smtp_tls_conn_reuse,
#ifdef USE_TLS
VAR_LMTP_TLS_ENFORCE_PN, DEF_LMTP_TLS_ENFORCE_PN, &var_smtp_tls_enforce_peername,
VAR_LMTP_TLS_NOTEOFFER, DEF_LMTP_TLS_NOTEOFFER, &var_smtp_tls_note_starttls_offer,
/* The TLS policy for MX hosts with "secure" TLSA records when the
/* nexthop destination security level is \fBdane\fR, but the MX
/* record was found via an "insecure" MX lookup.
+/* .PP
+/* Available in Postfix version 3.4 and later:
+/* .IP "\fBsmtp_tls_connection_reuse (no)\fR"
+/* Try to make multiple deliveries per TLS connection.
/* OBSOLETE STARTTLS CONTROLS
/* .ad
/* .fi
/* that an SMTP session may be reused before it is closed, or zero (no
/* limit).
/* .PP
+/* Available in Postfix version 3.4 and later:
+/* .IP "\fBsmtp_tls_connection_reuse (no)\fR"
+/* Try to make multiple deliveries per TLS connection.
+/* .PP
/* Implemented in the qmgr(8) daemon:
/* .IP "\fBtransport_destination_concurrency_limit ($default_destination_concurrency_limit)\fR"
/* A transport-specific override for the
char *var_smtp_tls_per_site;
char *var_smtp_tls_policy;
bool var_smtp_tls_wrappermode;
-bool var_smtp_use_tlsproxy;
+bool var_smtp_tls_conn_reuse;
char *var_tlsproxy_service;
#ifdef USE_TLS
ARGV *matchargv; /* Cert match patterns */
DSN_BUF *why; /* Lookup error status */
TLS_DANE *dane; /* DANE TLSA digests */
+ int conn_reuse; /* enable connection reuse */
} SMTP_TLS_POLICY;
/*
_tls_policy_init_tmp->matchargv = 0; \
_tls_policy_init_tmp->why = (w); \
_tls_policy_init_tmp->dane = 0; \
+ _tls_policy_init_tmp->conn_reuse = 0; \
} while (0)
#endif
* for connection-cache lookup by request nexthop only.
*/
#ifdef USE_TLS
- if (var_smtp_use_tlsproxy) {
- if (!smtp_tls_policy_cache_query(why, state->tls, iter)) {
- msg_warn("TLS policy lookup error for %s/%s: %s",
- STR(iter->dest), STR(iter->host), STR(why->reason));
- return (0); /* XXX */
- }
- } else
- smtp_tls_policy_dummy(state->tls);
+ if (!smtp_tls_policy_cache_query(why, state->tls, iter)) {
+ msg_warn("TLS policy lookup error for %s/%s: %s",
+ STR(iter->dest), STR(iter->host), STR(why->reason));
+ return (0); /* XXX */
+ }
#endif
SMTP_ITER_SAVE_DEST(state->iterator);
if (*addr_list && SMTP_RCPT_LEFT(state) > 0
VAR_SMTP_CACHE_DEMAND, DEF_SMTP_CACHE_DEMAND, &var_smtp_cache_demand,
VAR_SMTP_USE_TLS, DEF_SMTP_USE_TLS, &var_smtp_use_tls,
VAR_SMTP_ENFORCE_TLS, DEF_SMTP_ENFORCE_TLS, &var_smtp_enforce_tls,
- VAR_SMTP_USE_TLSPROXY, DEF_SMTP_USE_TLSPROXY, &var_smtp_use_tlsproxy,
+ VAR_SMTP_TLS_CONN_REUSE, DEF_SMTP_TLS_CONN_REUSE, &var_smtp_tls_conn_reuse,
#ifdef USE_TLS
VAR_SMTP_TLS_ENFORCE_PN, DEF_SMTP_TLS_ENFORCE_PN, &var_smtp_tls_enforce_peername,
VAR_SMTP_TLS_NOTEOFFER, DEF_SMTP_TLS_NOTEOFFER, &var_smtp_tls_note_starttls_offer,
* SMTP connection either, because the conversation is in an unknown
* state.
*/
- if (var_smtp_use_tlsproxy == 0)
+ if (state->tls->conn_reuse == 0)
DONT_CACHE_THIS_SESSION;
/*
| SMTP_KEY_FLAG_HOSTNAME
| SMTP_KEY_FLAG_ADDR);
- if (var_smtp_use_tlsproxy) {
+ if (state->tls->conn_reuse) {
/*
* Send all our wishes in one big request.
*/
session->tls_context = tls_proxy_context_receive(session->stream);
}
- } else { /* var_smtp_tls_proxy */
+ } else { /* state->tls->conn_reuse */
/*
* As of Postfix 2.5, tls_client_start() tries hard to always
matchargv = state->tls->matchargv,
mdalg = var_smtp_tls_fpt_dgst,
dane = state->tls->dane);
- } /* var_smtp_use_tlsproxy */
+ } /* state->tls->conn_reuse */
vstring_free(serverid);
vstream_fflush(session->stream);
}
if (session->tls_context) {
- if (var_smtp_use_tlsproxy)
+ if (session->state->tls->conn_reuse)
tls_proxy_context_free(session->tls_context);
else
tls_client_stop(smtp_tls_ctx, session->stream,
}
continue;
}
+ /* Last one wins. */
+ if (!strcasecmp(name, "connection_reuse")) {
+ if (strcasecmp(val, "yes") == 0) {
+ tls->conn_reuse = 1;
+ } else if (strcasecmp(val, "no") == 0) {
+ tls->conn_reuse = 0;
+ } else {
+ msg_warn("%s: attribute \"%s\" has bad value: \"%s\"",
+ WHERE, name, val);
+ INVALID_RETURN(tls->why, site_level);
+ }
+ }
msg_warn("%s: invalid attribute name: \"%s\"", WHERE, name);
INVALID_RETURN(tls->why, site_level);
}
SMTP_TLS_POLICY *tls = (SMTP_TLS_POLICY *) mymalloc(sizeof(*tls));
smtp_tls_policy_init(tls, dsb_create());
+ tls->conn_reuse = var_smtp_tls_conn_reuse;
/*
* Compute the per-site TLS enforcement level. For compatibility with the
/* SYNOPSIS
/* \fBtlsproxy\fR [generic Postfix daemon options]
/* DESCRIPTION
-/* The \fBtlsproxy\fR(8) server implements a server-side TLS
-/* proxy. It is used by \fBpostscreen\fR(8) to talk SMTP-over-TLS
+/* The \fBtlsproxy\fR(8) server implements a two-way TLS proxy. It
+/* is used by the \fBpostscreen\fR(8) server to talk SMTP-over-TLS
/* with remote SMTP clients that are not whitelisted (including
-/* clients whose whitelist status has expired),
-/* but it should also work for non-SMTP protocols.
+/* clients whose whitelist status has expired), and by the
+/* \fBsmtp\fR(8) client to support TLS connection reuse, but it
+/* should also work for non-SMTP protocols.
/*
/* Although one \fBtlsproxy\fR(8) process can serve multiple
/* sessions at the same time, it is a good idea to allow the
* become part of the TLS library.
*
* Later in the life cycle, tlsproxy(8) has also become an enabler for TLS
- * session reuse across different SMTP client processes.
+ * connection reuse across different SMTP client processes.
*/
static void tlsp_ciphertext_event(int, void *);
{
/*
- * Currently, tls_server_post_accept() and tls_client_post_connect()
- * always succeed.
+ * Do not assume that tls_server_post_accept() and
+ * tls_client_post_connect() will always succeed.
*/
if (state->is_server_role)
state->tls_context = tls_server_post_accept(state->tls_context);
}
state->flags &= ~TLSP_FLAG_DO_HANDSHAKE;
if (tlsp_post_handshake(state) != TLSP_STAT_OK) {
+ /* At this point, state is a dangling pointer. */
return;
}
}
*/
if (tlsp_eval_tls_error(state, ssl_write_err != SSL_ERROR_NONE ?
ssl_write_err : ssl_read_err) < 0)
+ /* At this point, state is a dangling pointer. */
return;
/*
* want to read or write more plaintext.
*/
tlsp_strategy(state);
+ /* At this point, state could be a dangling pointer. */
}
/* tlsp_ciphertext_event - ciphertext is ready to read/write */
*/
if (event == EVENT_READ || event == EVENT_WRITE) {
tlsp_strategy(state);
+ /* At this point, state could be a dangling pointer. */
} else {
if (event == EVENT_TIME && state->ssl_last_err == SSL_ERROR_NONE)
msg_warn("deadlock on plaintext stream for %s",
event_cancel_timer(handler, context);
else
errno = ETIMEDOUT;
- /* tlsp_state_free() disables pre-handshake I/O events. */
+ /* tlsp_state_free() disables pre-handshake plaintext I/O events. */
}
/* tlsp_get_fd_event - receive final connection hand-off information */
int status;
/*
- * Disable I/O events on the plaintext stream until the TLS handshake is
- * completed.
+ * At this point we still manually manage plaintext read/write/timeout
+ * events. Disable I/O events on the plaintext stream until the TLS
+ * handshake is completed. Every code path must either destroy state, or
+ * request the next event, otherwise we have a file and memory leak.
*/
tlsp_accept_event(event, tlsp_get_fd_event, (void *) state);
event_disable_readwrite(plaintext_fd);
else
status = tlsp_client_start_pre_handshake(state);
if (status != TLSP_STAT_OK)
+ /* At this point, state is a dangling pointer. */
return;
/*
* Trigger the initial proxy server I/Os.
*/
tlsp_strategy(state);
+ /* At this point, state could be a dangling pointer. */
}
/*
if ((state->appl_state = (TLS_APPL_STATE *)
htable_find(tlsp_client_app_cache, key)) == 0
&& (state->appl_state =
- tls_client_init(state->client_init_props)) != 0)
+ tls_client_init(state->client_init_props)) != 0) {
(void) htable_enter(tlsp_client_app_cache, key,
(void *) state->appl_state);
+
+ /*
+ * To maintain sanity, allow partial SSL_write() operations, and
+ * allow SSL_write() buffer pointers to change after a WANT_READ or
+ * WANT_WRITE result. This is based on OpenSSL developers talking on
+ * a mailing list, but is not supported by documentation. If this
+ * code stops working then no-one can be held responsible.
+ */
+ if (state->appl_state)
+ SSL_CTX_set_mode(state->appl_state->ssl_ctx,
+ SSL_MODE_ENABLE_PARTIAL_WRITE
+ | SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER);
+ }
vstring_free(buf);
return (state->appl_state != 0);
}
/*
* At this point we still manually manage plaintext read/write/timeout
- * events.
+ * events. Every code path must either destroy state or request the next
+ * event, otherwise this pseudo-thread is idle until the client goes
+ * away.
*/
tlsp_accept_event(event, tlsp_get_request_event, (void *) state);
}
/*
- * We must send some data, after receiving the request attributes and
- * before receiving the remote file descriptor. We can't assume
- * UNIX-domain socket semantics here.
+ * Receive the initial request attributes. Receive the remainder after we
+ * figure out what role we are expected to play.
*/
if (event != EVENT_READ
|| attr_scan(plaintext_stream, ATTR_FLAG_STRICT,
* XXX We use the same fixed timeout throughout the entire session for
* both plaintext and ciphertext communication. This timeout is just a
* safety feature; the real timeout will be enforced by our plaintext
- * peer.
+ * peer (except during TLS the handshake, when we intentionally disable
+ * plaintext I/O).
*/
state->remote_endpt = mystrdup(STR(remote_endpt));
state->server_id = mystrdup(STR(server_id));
/*
* Receive the TLS preferences now, to reduce the number of protocol
- * roundtrips. To call the pre-handshake tls_*_start() before receiving
- * the ciphertext FD, pass in the FD through some other interface.
+ * roundtrips.
*/
switch (req_flags & (TLS_PROXY_FLAG_ROLE_CLIENT | TLS_PROXY_FLAG_ROLE_SERVER)) {
case TLS_PROXY_FLAG_ROLE_CLIENT:
}
/*
+ * For portability we must send some data, after receiving the request
+ * attributes and before receiving the remote file descriptor.
+ *
* If the requested TLS engine is unavailable, hang up after making sure
* that the plaintext peer has received our "sorry" indication.
*/
MAIL_VERSION_STAMP_ALLOCATE;
/*
- * Pass control to the single-threaded service skeleton.
+ * Pass control to the event-driven service skeleton.
*/
event_server_main(argc, argv, tlsp_service,
CA_MAIL_SERVER_INT_TABLE(int_table),
/* tlsp_state_create() initializes session context.
/*
/* tlsp_state_free() destroys session context. If the handshake
-/* was in progress, it sends a 'handshake failed' message to the
-/* plaintext peer.
+/* was in progress, it logs a 'handshake failed' message.
/*
/* Arguments:
/* .IP service
projects / thirdparty / postfix.git / commitdiff
