]> git.ipfire.org Git - thirdparty/postfix.git/commitdiff
TLS fallback machine-generated doc update tlsfallback
authorViktor Dukhovni <postfix-users@dukhovni.org>
Wed, 23 Jul 2014 00:28:49 +0000 (20:28 -0400)
committerViktor Dukhovni <postfix-users@dukhovni.org>
Fri, 1 Aug 2014 06:40:47 +0000 (02:40 -0400)
postfix/README_FILES/TLS_README
postfix/html/TLS_README.html
postfix/html/postconf.5.html
postfix/html/smtp.8.html
postfix/man/man5/postconf.5
postfix/man/man8/smtp.8
postfix/src/smtp/smtp.c

index adca4c825557f59f130dfdbc9fd4debe82423a4d..4d15aaf3737d7778506d8bb6ea7e72537e435780 100644 (file)
@@ -1028,7 +1028,11 @@ default. This is the recommended configuration for early adopters.
     present or are unusable, mail is deferred.
 
   * The "example.org" destination uses DANE if possible, but if no TLSA records
-    are found opportunistic TLS is used.
+    are found opportunistic TLS is used. The "fallback" attribute supported
+    with Postfix >= 2.12, overrides the main.cf smtp_tls_fallback_level
+    parameter to employ unauthenticated mandatory encryption if DANE
+    authentication fails, after logging a warning. See smtp_tls_audit_template
+    for additional control over TLS security logging.
 
     main.cf:
         indexed = ${default_database_type}:${config_directory}/
@@ -1052,6 +1056,8 @@ default. This is the recommended configuration for early adopters.
 
     tls_policy:
         example.com dane-only
+        # Postfix >= 2.12, per-destination smtp_tls_fallback_level override
+        example.org dane fallback=encrypt
 
     master.cf:
         dane       unix  -       -       n       -       -       smtp
@@ -1632,7 +1638,9 @@ d\bda\ban\bne\be
     obtained for the remote SMTP server, SSLv2 is automatically disabled (see
     smtp_tls_mandatory_protocols), and the server certificate must match the
     TLSA records. RFC 6698 (DANE) TLS authentication and DNSSEC support is
-    available with Postfix 2.11 and later.
+    available with Postfix 2.11 and later. With Postfix >= 2.12 the optional
+    "fallback" attribute can be used as a per-site override of the main.cf
+    smtp_tls_fallback_level parameter.
 d\bda\ban\bne\be-\b-o\bon\bnl\bly\by
     Mandatory DANE TLS. The TLS policy for the destination is obtained via TLSA
     records in DNSSEC. If no TLSA records are found, or none are usable, no
@@ -1640,7 +1648,9 @@ d\bda\ban\bne\be-\b-o\bon\bnl\bly\by
     the remote SMTP server, SSLv2 is automatically disabled (see
     smtp_tls_mandatory_protocols), and the server certificate must match the
     TLSA records. RFC 6698 (DANE) TLS authentication and DNSSEC support is
-    available with Postfix 2.11 and later.
+    available with Postfix 2.11 and later. With Postfix >= 2.12 the optional
+    "fallback" attribute can be used as a per-site override of the main.cf
+    smtp_tls_fallback_level parameter.
 f\bfi\bin\bng\bge\ber\brp\bpr\bri\bin\bnt\bt
     Certificate fingerprint verification. Available with Postfix 2.5 and later.
     At this security level, there are no trusted certificate authorities. The
@@ -1653,7 +1663,8 @@ f\bfi\bin\bng\bge\ber\brp\bpr\bri\bin\bnt\bt
     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. With Postfix >= 2.12 the optional "fallback" attribute can be used
+    as a per-site override of the main.cf smtp_tls_fallback_level parameter.
 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
@@ -1664,7 +1675,8 @@ v\bve\ber\bri\bif\bfy\by
     "tafile" attribute optionally modifies trust chain verification in the same
     manner as the "smtp_tls_trust_anchor_file" parameter. The "tafile"
     attribute may be specified multiple times to load multiple trust-anchor
-    files.
+    files. With Postfix >= 2.12 the optional "fallback" attribute can be used
+    as a per-site override of the main.cf smtp_tls_fallback_level parameter.
 s\bse\bec\bcu\bur\bre\be
     Secure certificate verification. Mail is delivered only if the TLS
     handshake succeeds, if the remote SMTP server certificate can be validated
@@ -1674,7 +1686,9 @@ s\bse\bec\bcu\bur\bre\be
     "match" attribute is specified). With Postfix >= 2.11 the "tafile"
     attribute optionally modifies trust chain verification in the same manner
     as the "smtp_tls_trust_anchor_file" parameter. The "tafile" attribute may
-    be specified multiple times to load multiple trust-anchor files.
+    be specified multiple times to load multiple trust-anchor files. With
+    Postfix >= 2.12 the optional "fallback" attribute can be used as a per-site
+    override of the main.cf smtp_tls_fallback_level parameter.
 Notes:
 
   * The "match" attribute is especially useful to verify TLS certificates for
@@ -1708,6 +1722,7 @@ Example:
         smtp_tls_policy_maps = hash:/etc/postfix/tls_policy
         # Postfix 2.5 and later
         smtp_tls_fingerprint_digest = md5
+
     /etc/postfix/tls_policy:
         example.edu             none
         example.mil             may
@@ -1723,6 +1738,8 @@ Example:
         # Postfix 2.6 and later
         example.info            may protocols=!SSLv2 ciphers=medium
     exclude=3DES
+        # Postfix 2.12 and later override of smtp_tls_fallback_level
+        fallback.example        secure fallback=encrypt
 
 N\bNo\bot\bte\be:\b: The "hostname" strategy if listed in a non-default setting of
 smtp_tls_secure_cert_match or in the "match" attribute in the policy table can
index 2548b9f5761584241e216f36b255abe65d66ebc0..a8d8cd1e5e16f926392d86f65d506a8f8f281e15 100644 (file)
@@ -1373,8 +1373,13 @@ for early adopters. <p>
 <li> <p> The "example.com" destination uses DANE, but if TLSA records
 are not present or are unusable, mail is deferred. </p>
 
-<li> <p> The "example.org" destination uses DANE if possible, but if no TLSA
-records are found opportunistic TLS is used. </p>
+<li> <p> The "example.org" destination uses DANE if possible, but
+if no TLSA records are found opportunistic TLS is used.  The
+"fallback" attribute supported with Postfix &ge; 2.12, overrides
+the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_fallback_level">smtp_tls_fallback_level</a> parameter to employ unauthenticated
+mandatory encryption if DANE authentication fails, after logging a
+warning.  See <a href="postconf.5.html#smtp_tls_audit_template">smtp_tls_audit_template</a> for additional control over TLS
+security logging.  </p>
 </ul>
 
 <blockquote>
@@ -1394,26 +1399,16 @@ records are found opportunistic TLS is used. </p>
     # <a href="postconf.5.html#default_transport">default_transport</a> = smtp, but some destinations are special:
     #
     <a href="postconf.5.html#transport_maps">transport_maps</a> = ${indexed}transport
-</pre>
-</blockquote>
 
-<blockquote>
-<pre>
 transport:
     example.com dane
     example.org dane
-</pre>
-</blockquote>
 
-<blockquote>
-<pre>
 tls_policy:
     example.com dane-only
-</pre>
-</blockquote>
+    # Postfix &ge; 2.12, per-destination <a href="postconf.5.html#smtp_tls_fallback_level">smtp_tls_fallback_level</a> override
+    example.org dane fallback=encrypt
 
-<blockquote>
-<pre>
 <a href="master.5.html">master.cf</a>:
     dane       unix  -       -       n       -       -       smtp
       -o <a href="postconf.5.html#smtp_dns_support_level">smtp_dns_support_level</a>=dnssec
@@ -2146,7 +2141,9 @@ href="#client_tls_encrypt">encrypt</a>.  When usable TLSA records
 are obtained for the remote SMTP server, SSLv2 is automatically
 disabled (see <a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a>), and the server certificate
 must match the TLSA records.  <a href="http://tools.ietf.org/html/rfc6698">RFC 6698</a> (DANE) TLS authentication
-and DNSSEC support is available with Postfix 2.11 and later.  </dd>
+and DNSSEC support is available with Postfix 2.11 and later.  With Postfix
+&ge; 2.12 the optional "fallback" attribute can be used as a per-site override
+of the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_fallback_level">smtp_tls_fallback_level</a> parameter.  </dd>
 
 <dt><b>dane-only</b></dt> <dd><a href="#client_tls_dane">Mandatory DANE TLS</a>.
 The TLS policy for the destination is obtained via TLSA records in
@@ -2155,7 +2152,9 @@ connection is made to the server.  When usable TLSA records are
 obtained for the remote SMTP server, SSLv2 is automatically disabled
 (see <a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a>), and the server certificate must
 match the TLSA records.  <a href="http://tools.ietf.org/html/rfc6698">RFC 6698</a> (DANE) TLS authentication and
-DNSSEC support is available with Postfix 2.11 and later.  </dd>
+DNSSEC support is available with Postfix 2.11 and later.  With Postfix
+&ge; 2.12 the optional "fallback" attribute can be used as a per-site override
+of the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_fallback_level">smtp_tls_fallback_level</a> parameter.  </dd>
 
 <dt><b>fingerprint</b></dt> <dd><a href="#client_tls_fprint">Certificate
 fingerprint verification.</a> Available with Postfix 2.5 and
@@ -2164,13 +2163,14 @@ 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 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
-match attributes can be employed. The ":" character is not used as a
-delimiter as it occurs between each pair of fingerprint (hexadecimal)
-digits. </dd>
+(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 match attributes can be
+employed. The ":" character is not used as a delimiter as it occurs
+between each pair of fingerprint (hexadecimal) digits.  With Postfix
+&ge; 2.12 the optional "fallback" attribute can be used as a per-site
+override of the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_fallback_level">smtp_tls_fallback_level</a> parameter.  </dd>
 
 <dt><b>verify</b></dt> <dd><a href="#client_tls_verify">Mandatory
 server certificate verification</a>.  Mail is delivered only if the
@@ -2181,9 +2181,11 @@ the optional "match" attribute (or the <a href="postconf.5.html">main.cf</a> <a
 parameter value when no optional "match" attribute is specified).
 With Postfix &ge; 2.11 the "tafile" attribute optionally modifies
 trust chain verification in the same manner as the
-"<a href="postconf.5.html#smtp_tls_trust_anchor_file">smtp_tls_trust_anchor_file</a>" parameter.  The "tafile" attribute
-may be specified multiple times to load multiple trust-anchor
-files.  </dd>
+"<a href="postconf.5.html#smtp_tls_trust_anchor_file">smtp_tls_trust_anchor_file</a>" parameter.  The "tafile" attribute may
+be specified multiple times to load multiple trust-anchor files.
+With Postfix &ge; 2.12 the optional "fallback" attribute can be
+used as a per-site override of the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_fallback_level">smtp_tls_fallback_level</a>
+parameter.  </dd>
 
 <dt><b>secure</b></dt> <dd><a href="#client_tls_secure">Secure certificate
 verification.</a> Mail is delivered only if the TLS handshake succeeds,
@@ -2195,7 +2197,9 @@ server certificate name matches the optional "match" attribute (or the
 attribute optionally modifies trust chain verification in the same manner
 as the "<a href="postconf.5.html#smtp_tls_trust_anchor_file">smtp_tls_trust_anchor_file</a>" parameter.  The "tafile" attribute
 may be specified multiple times to load multiple trust-anchor
-files.  </dd>
+files.  With Postfix &ge; 2.12 the optional "fallback" attribute
+can be used as a per-site override of the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_fallback_level">smtp_tls_fallback_level</a>
+parameter.  </dd>
 
 </dl>
 
@@ -2242,6 +2246,7 @@ Example:
     <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> = <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/tls_policy
     # Postfix 2.5 and later
     <a href="postconf.5.html#smtp_tls_fingerprint_digest">smtp_tls_fingerprint_digest</a> = md5
+
 /etc/postfix/tls_policy:
     example.edu             none
     example.mil             may
@@ -2256,6 +2261,8 @@ Example:
         match=3D:95:34:51:24:66:33:B9:D2:40:99:C0:C1:17:0B:D1
     # Postfix 2.6 and later
     example.info            may protocols=!SSLv2 ciphers=medium exclude=3DES
+    # Postfix 2.12 and later override of <a href="postconf.5.html#smtp_tls_fallback_level">smtp_tls_fallback_level</a>
+    fallback.example        secure fallback=encrypt
 </pre>
 </blockquote>
 
index 9a714e7b17d1c49900c33a309095d634b07c6adb..211d450904542a7f56c92364d0daf8315f38d1ee 100644 (file)
@@ -4822,6 +4822,17 @@ configuration parameter.  See there for details. </p>
 <p> This feature is available in Postfix 2.3 and later. </p>
 
 
+</DD>
+
+<DT><b><a name="lmtp_tls_audit_template">lmtp_tls_audit_template</a>
+(default: empty)</b></DT><DD>
+
+<p> The LMTP-specific version of the <a href="postconf.5.html#smtp_tls_audit_template">smtp_tls_audit_template</a>
+configuration parameter.  See there for details. </p>
+
+<p> This feature is available in Postfix 2.12 and later. </p>
+
+
 </DD>
 
 <DT><b><a name="lmtp_tls_block_early_mail_reply">lmtp_tls_block_early_mail_reply</a>
@@ -4923,6 +4934,17 @@ configuration parameter.  See there for details. </p>
 <p> This feature is available in Postfix 2.3 and later. </p>
 
 
+</DD>
+
+<DT><b><a name="lmtp_tls_fallback_level">lmtp_tls_fallback_level</a>
+(default: empty)</b></DT><DD>
+
+<p> The LMTP-specific version of the <a href="postconf.5.html#smtp_tls_fallback_level">smtp_tls_fallback_level</a>
+configuration parameter.  See there for details. </p>
+
+<p> This feature is available in Postfix 2.12 and later. </p>
+
+
 </DD>
 
 <DT><b><a name="lmtp_tls_fingerprint_cert_match">lmtp_tls_fingerprint_cert_match</a>
@@ -11264,6 +11286,73 @@ certificates. </p>
 <p> This feature is available in Postfix 2.2 and later.  </p>
 
 
+</DD>
+
+<DT><b><a name="smtp_tls_audit_template">smtp_tls_audit_template</a>
+(default: empty)</b></DT><DD>
+
+<p> Optional template for tls audit logging at the completion of each
+message data transfer.  If empty (the default setting) no TLS audit log
+entries are generated.  </p>
+
+<p> The following $name expansions are done on <a href="postconf.5.html#smtp_tls_audit_template">smtp_tls_audit_template</a>: </p>
+
+<dl>
+
+<dt><b>$relay</b></dt>
+<dd>The remote SMTP server. </dd>
+
+<dt><b>$level</b></dt>
+<dd>The effective TLS security level after any fallback. </dd>
+
+<dt><b>$policy</b></dt>
+<dd>The desired TLS security level before any fallback, undefined
+if no fallback took place. </dd>
+
+<dt><b>$auth</b></dt>
+<dd>The authentication level of the remote SMTP server.  One of
+"Cleartext", "Anonymous", "Untrusted", "Trusted" or "Verified".
+</dd>
+
+<dt><b>$protocol</b></dt>
+<dd>The TLS protocol version, defined only when TLS is used. </dd>
+
+<dt><b>$cipher</b></dt>
+<dd>The TLS cipher name, defined only when TLS is used. </dd>
+
+<dt><b>$cert_digest</b></dt>
+<dd>The digest of the remote SMTP server's certificate, defined
+only when TLS is used and the remote server presented a certificate.
+The digest algorithm is that specified via <a href="postconf.5.html#smtp_tls_fingerprint_digest">smtp_tls_fingerprint_digest</a>.
+</dd>
+
+<dt><b>$spki_digest</b></dt>
+<dd>The digest of the remote SMTP server's public key (Subject
+Public Key Info or SPKI from X.509), defined only when TLS is used
+and the remote server presented a certificate.  The digest algorithm
+is that specified via <a href="postconf.5.html#smtp_tls_fingerprint_digest">smtp_tls_fingerprint_digest</a>.  </dd>
+
+<dt><b>${name?value}</b></dt>
+
+<dd>Expands to <i>value</i> when <i>$name</i> is non-empty. </dd>
+
+<dt><b>${name:value}</b></dt>
+
+<dd>Expands to <i>value</i> when <i>$name</i> is empty. </dd>
+
+</dl>
+
+<p> Example: </p>
+
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+    <a href="postconf.5.html#smtp_tls_audit_template">smtp_tls_audit_template</a> =
+        tlsaudit: relay=${relay}${auth?, auth=${auth}}${level?, level=${level}}${policy?, policy=${policy}}${protocol?, protocol=${protocol}}${cipher?, cipher=${cipher}}
+</pre>
+
+<p> This feature is available in Postfix 2.12 and later. </p>
+
+
 </DD>
 
 <DT><b><a name="smtp_tls_block_early_mail_reply">smtp_tls_block_early_mail_reply</a>
@@ -11517,6 +11606,62 @@ key exchange with RSA authentication. </p>
 <p> This feature is available in Postfix 2.3 and later. </p>
 
 
+</DD>
+
+<DT><b><a name="smtp_tls_fallback_level">smtp_tls_fallback_level</a>
+(default: empty)</b></DT><DD>
+
+<p> Optional fallback levels for authenticated TLS levels.  Specify
+a white-space or comma-separate list of
+<b>policy_level</b>=<b>fallback_level</b> pairs.  The <b>policy_level</b>
+must require authentication (be one of dane, dane-only, fingerprint,
+verify, secure).  The <b>fallback_level</b> must be "encrypt" or
+"may".  When an authenticated connection with a policy level equal
+to one of the specified values cannot be established, delivery will
+proceed at the fallback level if possible.  A warning will be logged
+indicating the fallback reason.  You can use <a href="postconf.5.html#smtp_tls_audit_template">smtp_tls_audit_template</a>
+to record the TLS security status for each delivery. </p>
+
+<p> The TLS <a href="TLS_README.html#client_tls_policy">policy</a> table
+can be used to specify a destination-specific fallback strategy via the
+"fallback" policy attribute.  The value of the "fallback" attribute, if
+specified, must be "may", "encrypt" or "none".  If not "none", this
+specifies the fallback level for the destination in question.  If the
+attribute value is "none", fallback is suppressed for the destination
+even if enabled via a global setting of <a href="postconf.5.html#smtp_tls_fallback_level">smtp_tls_fallback_level</a>.  </p>
+
+<p> Example: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+    # When authentication fails, log a warning and deliver anyway
+    # over an unauthenticated TLS connection.
+    #
+    <a href="postconf.5.html#smtp_tls_fallback_level">smtp_tls_fallback_level</a> =
+        dane=encrypt,
+        dane-only=encrypt,
+        fingerprint=encrypt,
+        verify=encrypt,
+        secure=encrypt
+    indexed = ${<a href="postconf.5.html#default_database_type">default_database_type</a>}:${<a href="postconf.5.html#config_directory">config_directory</a>}/
+    <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> = ${indexed}tls-policy
+</pre>
+</blockquote>
+
+<blockquote>
+<pre>
+/etc/postfix/tls-policy:
+    # No fallback for example.com
+    example.com secure fallback=none
+    # For example.net tolerate cleartext fallback
+    example.net dane fallback=may
+</pre>
+</blockquote>
+
+<p> This feature is available in Postfix 2.12 and later. </p>
+
+
 </DD>
 
 <DT><b><a name="smtp_tls_fingerprint_cert_match">smtp_tls_fingerprint_cert_match</a>
index b05dc45cd8225a9a8627efbd09b60cee03f3429c..7e05c638efe605503ff5ab760e0ffdb26b660def 100644 (file)
@@ -552,6 +552,15 @@ SMTP(8)                                                                SMTP(8)
        <b><a href="postconf.5.html#tlsmgr_service_name">tlsmgr_service_name</a> (tlsmgr)</b>
               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>.
 
+       Available in Postfix version 2.12 and later:
+
+       <b><a href="postconf.5.html#smtp_tls_audit_template">smtp_tls_audit_template</a> (empty)</b>
+              Optional  template  for  tls  audit logging at the completion of
+              each message data transfer.
+
+       <b><a href="postconf.5.html#smtp_tls_fallback_level">smtp_tls_fallback_level</a> (empty)</b>
+              Optional fallback levels for authenticated TLS levels.
+
 <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
index 73ba99ed2d5a905724e06a5c098ffa0054543b77..bfc2ac21559055c6a332173d9c72905c3b992b0f 100644 (file)
@@ -2818,6 +2818,11 @@ The LMTP-specific version of the smtp_tls_CApath
 configuration parameter.  See there for details.
 .PP
 This feature is available in Postfix 2.3 and later.
+.SH lmtp_tls_audit_template (default: empty)
+The LMTP-specific version of the smtp_tls_audit_template
+configuration parameter.  See there for details.
+.PP
+This feature is available in Postfix 2.12 and later.
 .SH lmtp_tls_block_early_mail_reply (default: empty)
 The LMTP-specific version of the smtp_tls_block_early_mail_reply
 configuration parameter.  See there for details.
@@ -2865,6 +2870,11 @@ The LMTP-specific version of the smtp_tls_exclude_ciphers
 configuration parameter.  See there for details.
 .PP
 This feature is available in Postfix 2.3 and later.
+.SH lmtp_tls_fallback_level (default: empty)
+The LMTP-specific version of the smtp_tls_fallback_level
+configuration parameter.  See there for details.
+.PP
+This feature is available in Postfix 2.12 and later.
 .SH lmtp_tls_fingerprint_cert_match (default: empty)
 The LMTP-specific version of the smtp_tls_fingerprint_cert_match
 configuration parameter.  See there for details.
@@ -6974,6 +6984,64 @@ smtp_tls_CApath = /etc/postfix/certs
 .ft R
 .PP
 This feature is available in Postfix 2.2 and later.
+.SH smtp_tls_audit_template (default: empty)
+Optional template for tls audit logging at the completion of each
+message data transfer.  If empty (the default setting) no TLS audit log
+entries are generated.
+.PP
+The following $name expansions are done on smtp_tls_audit_template:
+.IP "\fB$relay\fR"
+The remote SMTP server.
+.br
+.IP "\fB$level\fR"
+The effective TLS security level after any fallback.
+.br
+.IP "\fB$policy\fR"
+The desired TLS security level before any fallback, undefined
+if no fallback took place.
+.br
+.IP "\fB$auth\fR"
+The authentication level of the remote SMTP server.  One of
+"Cleartext", "Anonymous", "Untrusted", "Trusted" or "Verified".
+.br
+.IP "\fB$protocol\fR"
+The TLS protocol version, defined only when TLS is used.
+.br
+.IP "\fB$cipher\fR"
+The TLS cipher name, defined only when TLS is used.
+.br
+.IP "\fB$cert_digest\fR"
+The digest of the remote SMTP server's certificate, defined
+only when TLS is used and the remote server presented a certificate.
+The digest algorithm is that specified via smtp_tls_fingerprint_digest.
+.br
+.IP "\fB$spki_digest\fR"
+The digest of the remote SMTP server's public key (Subject
+Public Key Info or SPKI from X.509), defined only when TLS is used
+and the remote server presented a certificate.  The digest algorithm
+is that specified via smtp_tls_fingerprint_digest.
+.br
+.IP "\fB${name?value}\fR"
+Expands to \fIvalue\fR when \fI$name\fR is non-empty.
+.br
+.IP "\fB${name:value}\fR"
+Expands to \fIvalue\fR when \fI$name\fR is empty.
+.br
+.br
+.PP
+Example:
+.PP
+.nf
+.na
+.ft C
+/etc/postfix/main.cf:
+    smtp_tls_audit_template =
+        tlsaudit: relay=${relay}${auth?, auth=${auth}}${level?, level=${level}}${policy?, policy=${policy}}${protocol?, protocol=${protocol}}${cipher?, cipher=${cipher}}
+.fi
+.ad
+.ft R
+.PP
+This feature is available in Postfix 2.12 and later.
 .SH smtp_tls_block_early_mail_reply (default: no)
 Try to detect a mail hijacking attack based on a TLS protocol
 vulnerability (CVE-2009-3555), where an attacker prepends malicious
@@ -7189,6 +7257,64 @@ and "DES-CBC3-MD5". The last setting disables ciphers that use "EDH"
 key exchange with RSA authentication.
 .PP
 This feature is available in Postfix 2.3 and later.
+.SH smtp_tls_fallback_level (default: empty)
+Optional fallback levels for authenticated TLS levels.  Specify
+a white-space or comma-separate list of
+\fBpolicy_level\fR=\fBfallback_level\fR pairs.  The \fBpolicy_level\fR
+must require authentication (be one of dane, dane-only, fingerprint,
+verify, secure).  The \fBfallback_level\fR must be "encrypt" or
+"may".  When an authenticated connection with a policy level equal
+to one of the specified values cannot be established, delivery will
+proceed at the fallback level if possible.  A warning will be logged
+indicating the fallback reason.  You can use smtp_tls_audit_template
+to record the TLS security status for each delivery.
+.PP
+The TLS policy table
+can be used to specify a destination-specific fallback strategy via the
+"fallback" policy attribute.  The value of the "fallback" attribute, if
+specified, must be "may", "encrypt" or "none".  If not "none", this
+specifies the fallback level for the destination in question.  If the
+attribute value is "none", fallback is suppressed for the destination
+even if enabled via a global setting of smtp_tls_fallback_level.
+.PP
+Example:
+.sp
+.in +4
+.nf
+.na
+.ft C
+/etc/postfix/main.cf:
+    # When authentication fails, log a warning and deliver anyway
+    # over an unauthenticated TLS connection.
+    #
+    smtp_tls_fallback_level =
+        dane=encrypt,
+        dane-only=encrypt,
+        fingerprint=encrypt,
+        verify=encrypt,
+        secure=encrypt
+    indexed = ${default_database_type}:${config_directory}/
+    smtp_tls_policy_maps = ${indexed}tls-policy
+.fi
+.ad
+.ft R
+.in -4
+.sp
+.in +4
+.nf
+.na
+.ft C
+/etc/postfix/tls-policy:
+    # No fallback for example.com
+    example.com secure fallback=none
+    # For example.net tolerate cleartext fallback
+    example.net dane fallback=may
+.fi
+.ad
+.ft R
+.in -4
+.PP
+This feature is available in Postfix 2.12 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 =
index 6d8d116b7bf719ccbe1f176f49905aa7dc0bcd98..6985023368a20941a070dfc6eae9b4f62b2ef977 100644 (file)
@@ -492,6 +492,13 @@ not an alias and its address records lie in an unsigned zone.
 RFC 6698 trust-anchor digest support in the Postfix TLS library.
 .IP "\fBtlsmgr_service_name (tlsmgr)\fR"
 The name of the \fBtlsmgr\fR(8) service entry in master.cf.
+.PP
+Available in Postfix version 2.12 and later:
+.IP "\fBsmtp_tls_audit_template (empty)\fR"
+Optional template for tls audit logging at the completion of each
+message data transfer.
+.IP "\fBsmtp_tls_fallback_level (empty)\fR"
+Optional fallback levels for authenticated TLS levels.
 .SH "OBSOLETE STARTTLS CONTROLS"
 .na
 .nf
@@ -617,8 +624,8 @@ Preliminary SMTPUTF8 support is introduced with Postfix 2.12.
 Enable experimental SMTPUTF8 support for the protocols described
 in RFC 6531..6533.
 .IP "\fBsmtputf8_autodetect_classes (sendmail, verify)\fR"
-Enable SMTPUTF8 autodetection for the specified mail origin
-classes.
+Detect that a message requires SMTPUTF8 support for the specified
+mail origin classes.
 .SH "TROUBLE SHOOTING CONTROLS"
 .na
 .nf
index 08ad2e53465caf5c03e26c88f1ba64d4fe94ad22..130b251f98b96d903cb8e0e2e4149b19f278084e 100644 (file)
 /*     Enable experimental SMTPUTF8 support for the protocols described
 /*     in RFC 6531..6533.
 /* .IP "\fBsmtputf8_autodetect_classes (sendmail, verify)\fR"
-/*     Enable SMTPUTF8 autodetection for the specified mail origin
-/*     classes.
+/*     Detect that a message requires SMTPUTF8 support for the specified
+/*     mail origin classes.
 /* TROUBLE SHOOTING CONTROLS
 /* .ad
 /* .fi