From: Viktor Dukhovni Date: Wed, 23 Jul 2014 00:28:49 +0000 (-0400) Subject: TLS fallback machine-generated doc update X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=157f5e0f77368abeedde9616a7471f0d69de187a;p=thirdparty%2Fpostfix.git TLS fallback machine-generated doc update --- diff --git a/postfix/README_FILES/TLS_README b/postfix/README_FILES/TLS_README index adca4c825..4d15aaf37 100644 --- a/postfix/README_FILES/TLS_README +++ b/postfix/README_FILES/TLS_README @@ -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 @@ ddaannee 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. ddaannee--oonnllyy Mandatory DANE TLS. The TLS policy for the destination is obtained via TLSA records in DNSSEC. If no TLSA records are found, or none are usable, no @@ -1640,7 +1648,9 @@ ddaannee--oonnllyy 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. ffiinnggeerrpprriinntt 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 @@ ffiinnggeerrpprriinntt 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. vveerriiffyy 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 @@ vveerriiffyy "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. sseeccuurree 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 @@ sseeccuurree "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 NNoottee:: The "hostname" strategy if listed in a non-default setting of smtp_tls_secure_cert_match or in the "match" attribute in the policy table can diff --git a/postfix/html/TLS_README.html b/postfix/html/TLS_README.html index 2548b9f57..a8d8cd1e5 100644 --- a/postfix/html/TLS_README.html +++ b/postfix/html/TLS_README.html @@ -1373,8 +1373,13 @@ for early adopters.

  • The "example.com" destination uses DANE, but if TLSA records are not present or are unusable, mail is deferred.

    -

  • The "example.org" destination uses DANE if possible, but if no TLSA -records are found opportunistic TLS is used.

    +

  • 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 ≥ 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.

    @@ -1394,26 +1399,16 @@ records are found opportunistic TLS is used.

    # default_transport = smtp, but some destinations are special: # transport_maps = ${indexed}transport - -
    -
    -
     transport:
     example.com dane
     example.org dane
-
    -
    -
    -
     tls_policy:
     example.com dane-only
-
    -
    + # Postfix ≥ 2.12, per-destination smtp_tls_fallback_level override + example.org dane fallback=encrypt -
    -
     master.cf:
     dane       unix  -       -       n       -       -       smtp
       -o smtp_dns_support_level=dnssec
@@ -2146,7 +2141,9 @@ href="#client_tls_encrypt">encrypt.  When usable TLSA records
 are 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.  
+and DNSSEC support is 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.  
 
 
    dane-only
     
    Mandatory DANE TLS.
 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 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.  
    
+DNSSEC support is 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.  
 
 
    fingerprint
     
    Certificate
 fingerprint verification. Available with Postfix 2.5 and
@@ -2164,13 +2163,14 @@ authorities. The certificate trust chain, expiration date, ... are
 not checked. Instead, the optional match attribute, or else
 the main.cf smtp_tls_fingerprint_cert_match 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
-smtp_tls_fingerprint_digest 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. 
    
+(Postfix 2.9 and later).  The digest algorithm used to calculate
+fingerprints is selected by the smtp_tls_fingerprint_digest
+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
+≥ 2.12 the optional "fallback" attribute can be used as a per-site
+override of the main.cf smtp_tls_fallback_level parameter.  
 
 
    verify
     
    Mandatory
 server certificate verification.  Mail is delivered only if the
@@ -2181,9 +2181,11 @@ the optional "match" attribute (or the main.cf smtp_tls_trust_anchor_file" parameter.  The "tafile" attribute
-may be specified multiple times to load multiple trust-anchor
-files.  
    
+"smtp_tls_trust_anchor_file" parameter.  The "tafile" attribute may
+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.  
 
 
    secure
     
    Secure certificate
 verification. 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 "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.  
 
 
 
@@ -2242,6 +2246,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
@@ -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 smtp_tls_fallback_level
+    fallback.example        secure fallback=encrypt
    diff --git a/postfix/html/postconf.5.html b/postfix/html/postconf.5.html index 9a714e7b1..211d45090 100644 --- a/postfix/html/postconf.5.html +++ b/postfix/html/postconf.5.html @@ -4822,6 +4822,17 @@ configuration parameter. See there for details.

    This feature is available in Postfix 2.3 and later.

    + + +
    lmtp_tls_audit_template +(default: empty)
    + +

    The LMTP-specific version of the smtp_tls_audit_template +configuration parameter. See there for details.

    + +

    This feature is available in Postfix 2.12 and later.

    + +
    lmtp_tls_block_early_mail_reply @@ -4923,6 +4934,17 @@ configuration parameter. See there for details.

    This feature is available in Postfix 2.3 and later.

    + + +
    lmtp_tls_fallback_level +(default: empty)
    + +

    The LMTP-specific version of the smtp_tls_fallback_level +configuration parameter. See there for details.

    + +

    This feature is available in Postfix 2.12 and later.

    + +
    lmtp_tls_fingerprint_cert_match @@ -11264,6 +11286,73 @@ certificates.

    This feature is available in Postfix 2.2 and later.

    + + +
    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.

    + +

    The following $name expansions are done on smtp_tls_audit_template:

    + +
    + +
    $relay
    +
    The remote SMTP server.
    + +
    $level
    +
    The effective TLS security level after any fallback.
    + +
    $policy
    +
    The desired TLS security level before any fallback, undefined +if no fallback took place.
    + +
    $auth
    +
    The authentication level of the remote SMTP server. One of +"Cleartext", "Anonymous", "Untrusted", "Trusted" or "Verified". +
    + +
    $protocol
    +
    The TLS protocol version, defined only when TLS is used.
    + +
    $cipher
    +
    The TLS cipher name, defined only when TLS is used.
    + +
    $cert_digest
    +
    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. +
    + +
    $spki_digest
    +
    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.
    + +
    ${name?value}
    + +
    Expands to value when $name is non-empty.
    + +
    ${name:value}
    + +
    Expands to value when $name is empty.
    + +
    + +

    Example:

    + +
    +/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}}
+
    + +

    This feature is available in Postfix 2.12 and later.

    + +
    smtp_tls_block_early_mail_reply @@ -11517,6 +11606,62 @@ key exchange with RSA authentication.

    This feature is available in Postfix 2.3 and later.

    + + +
    smtp_tls_fallback_level +(default: empty)
    + +

    Optional fallback levels for authenticated TLS levels. Specify +a white-space or comma-separate list of +policy_level=fallback_level pairs. The policy_level +must require authentication (be one of dane, dane-only, fingerprint, +verify, secure). The fallback_level 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.

    + +

    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.

    + +

    Example:

    + +
    +
    +/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
+
    +
    + +
    +
    +/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
+
    +
    + +

    This feature is available in Postfix 2.12 and later.

    + +
    smtp_tls_fingerprint_cert_match diff --git a/postfix/html/smtp.8.html b/postfix/html/smtp.8.html index b05dc45cd..7e05c638e 100644 --- a/postfix/html/smtp.8.html +++ b/postfix/html/smtp.8.html @@ -552,6 +552,15 @@ SMTP(8) SMTP(8) tlsmgr_service_name (tlsmgr) The name of the tlsmgr(8) service entry in master.cf. + Available in Postfix version 2.12 and later: + + smtp_tls_audit_template (empty) + Optional template for tls audit logging at the completion of + each message data transfer. + + smtp_tls_fallback_level (empty) + Optional fallback levels for authenticated TLS levels. + OBSOLETE STARTTLS CONTROLS The following configuration parameters exist for compatibility with Postfix versions before 2.3. Support for these will be removed in a diff --git a/postfix/man/man5/postconf.5 b/postfix/man/man5/postconf.5 index 73ba99ed2..bfc2ac215 100644 --- a/postfix/man/man5/postconf.5 +++ b/postfix/man/man5/postconf.5 @@ -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 = diff --git a/postfix/man/man8/smtp.8 b/postfix/man/man8/smtp.8 index 6d8d116b7..698502336 100644 --- a/postfix/man/man8/smtp.8 +++ b/postfix/man/man8/smtp.8 @@ -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 diff --git a/postfix/src/smtp/smtp.c b/postfix/src/smtp/smtp.c index 08ad2e534..130b251f9 100644 --- a/postfix/src/smtp/smtp.c +++ b/postfix/src/smtp/smtp.c @@ -588,8 +588,8 @@ /* 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