X-Git-Url: https://git.netwichtig.de/gitweb/?a=blobdiff_plain;f=doc%2Fdoc-docbook%2Fspec.xfpt;h=be3e7c925a23b8e5ee50dccb1a879d0afc4f53cd;hb=7dd52d1ff8cd5e8914172d3131412bf1c2ceaf92;hp=4069c29dbb5300d0f54e9773185b1dd51a65db72;hpb=b6df68c68ad86cafb9531bb6c25fac648d0e706b;p=user%2Fhenk%2Fcode%2Fexim.git diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 4069c29db..be3e7c925 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -6641,6 +6641,8 @@ file that is searched could contain lines like this: .endd When the lookup succeeds, the result of the expansion is a list of domains (and possibly other types of item that are allowed in domain lists). +.cindex "tainted data" "de-tainting" +The result of the expansion is not tainted. In the second example, the lookup is a single item in a domain list. It causes Exim to use a lookup to see if the domain that is being processed can be found @@ -10595,6 +10597,14 @@ ${sort {${lookup dnsdb{>:,,mx=example.com}}} {<} {${listextract{1}{<,$item}}}} will sort an MX lookup into priority order. + +.new +.vitem &*${srs_encode&~{*&<&'secret'&>&*}{*&<&'return&~path'&>&*}{*&<&'original&~domain'&>&*}}*& +SRS encoding. See SECT &<>& for details. +.wen + + + .vitem &*${substr{*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*& .cindex "&%substr%& expansion item" .cindex "substring extraction" @@ -11657,6 +11667,13 @@ includes the case of letters, whereas for &%gti%& the comparison is case-independent. Case and collation order are defined per the system C locale. + +.new +.vitem &*inbound_srs&~{*&<&'local&~part'&>&*}{*&<&'secret'&>&*}*& +SRS decode. See SECT &<>& for details. +.wen + + .vitem &*inlist&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&& &*inlisti&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& .cindex "string" "comparison" @@ -13749,6 +13766,17 @@ the value of the Distinguished Name of the certificate is made available in the If certificate verification fails it may refer to a failing chain element which is not the leaf. + +.new +.vitem &$tls_in_resumption$& &&& + &$tls_out_resumption$& +.vindex &$tls_in_resumption$& +.vindex &$tls_out_resumption$& +.cindex TLS resumption +Observability for TLS session resumption. See &<>& for details. +.wen + + .vitem &$tls_in_sni$& .vindex "&$tls_in_sni$&" .vindex "&$tls_sni$&" @@ -15631,6 +15659,10 @@ and RET and ORCPT options on MAIL FROM commands. A NOTIFY=SUCCESS option requests success-DSN messages. A NOTIFY= option with no argument requests that no delay or failure DSNs are sent. +.new +&*Note*&: Supplying success-DSN messages has been criticised +on privacy grounds; it can leak details of internal forwarding. +.wen .option dsn_from main "string&!!" "see below" .cindex "&'From:'& header line" "in bounces" @@ -18253,6 +18285,14 @@ preference order of the available ciphers. Details are given in sections &<>& and &<>&. +.new +.option tls_resumption_hosts main "host list&!!" unset +.cindex TLS resumption +This option controls which connections to offer the TLS resumption feature. +See &<>& for details. +.wen + + .option tls_try_verify_hosts main "host list&!!" unset .cindex "TLS" "client certificate verification" .cindex "certificate" "verification of client" @@ -25573,6 +25613,14 @@ is used in different ways by OpenSSL and GnuTLS (see sections ciphers is a preference order. +.new +.option tls_resumption_hosts smtp "host list&!!" unset +.cindex TLS resumption +This option controls which connections to use the TLS resumption feature. +See &<>& for details. +.wen + + .option tls_sni smtp string&!! unset .cindex "TLS" "Server Name Indication" @@ -25672,7 +25720,7 @@ The &%tls_verify_certificates%& option must also be set. If both this option and &%tls_try_verify_hosts%& are unset operation is as if this option selected all hosts. -.option utf8_downconvert smtp integer&!! unset +.option utf8_downconvert smtp integer&!! -1 .cindex utf8 "address downconversion" .cindex i18n "utf8 address downconversion" If built with internationalization support, @@ -25680,7 +25728,8 @@ this option controls conversion of UTF-8 in message envelope addresses to a-label form. If, after expansion, the value is 1, 0, or -1 then this value overrides any value previously set for the message. Otherwise, any previously -set value is used. +set value is used. To permit use of a previous value, +set this option to an empty string. For details on the values see section &<>&. @@ -29402,6 +29451,100 @@ Open-source PKI book, available online at .ecindex IIDencsmtp2 +.new +.section "TLS Resumption" "SECTresumption" +.cindex TLS resumption +TLS Session Resumption for TLS 1.2 and TLS 1.3 connections can be used (defined +in RFC 5077 for 1.2). The support for this requires GnuTLS 3.6.3 or OpenSSL 1.1.1 +(or later). + +Session resumption (this is the "stateless" variant) involves the server sending +a "session ticket" to the client on one connection, which can be stored by the +client and used for a later session. The ticket contains sufficient state for +the server to reconstruct the TLS session, avoiding some expensive crypto +calculation and (on TLS1.2) one full packet roundtrip time. + +.ilist +Operational cost/benefit: + + The extra data being transmitted costs a minor amount, and the client has + extra costs in storing and retrieving the data. + + In the Exim/Gnutls implementation the extra cost on an initial connection + which is TLS1.2 over a loopback path is about 6ms on 2017-laptop class hardware. + The saved cost on a subsequent connection is about 4ms; three or more + connections become a net win. On longer network paths, two or more + connections will have an average lower startup time thanks to the one + saved packet roundtrip. TLS1.3 will save the crypto cpu costs but not any + packet roundtrips. + +.cindex "hints database" tls + Since a new hints DB is used on the TLS client, + the hints DB maintenance should be updated to additionally handle "tls". + +.next +Security aspects: + + The session ticket is encrypted, but is obviously an additional security + vulnarability surface. An attacker able to decrypt it would have access + all connections using the resumed session. + The session ticket encryption key is not committed to storage by the server + and is rotated regularly (OpenSSL: 1hr, and one previous key is used for + overlap; GnuTLS 6hr but does not specify any overlap). + Tickets have limited lifetime (2hr, and new ones issued after 1hr under + OpenSSL. GnuTLS 2hr, appears to not do overlap). + + There is a question-mark over the security of the Diffie-Helman parameters + used for session negotiation. + +.next +Observability: + + The &%log_selector%& "tls_resumption" appends an asterisk to the tls_cipher "X=" + element. + + The variables &$tls_in_resumption$& and &$tls_out_resumption$& + have bits 0-4 indicating respectively + support built, client requested ticket, client offered session, + server issued ticket, resume used. A suitable decode list is provided + in the builtin macro _RESUME_DECODE for in &%listextract%& expansions. + +.next +Control: + +The &%tls_resumption_hosts%& main option specifies a hostlist for which +exim, operating as a server, will offer resumption to clients. +Current best practice is to not offer the feature to MUA connection. +Commonly this can be done like this: +.code +tls_resumption_hosts = ${if inlist {$received_port}{587:465} {:}{*}} +.endd +If the peer host matches the list after expansion then resumption +is offered and/or accepted. + +The &%tls_resumption_hosts% smtp transport option performs the +equivalent function for operation as a client. +If the peer host matches the list after expansion then resumption +is attempted (if a stored session is available) or the information +stored (if supplied by the peer). + + +.next +Issues: + + In a resumed session: +.ilist + The variables &$tls_{in,out}_cipher$& will have values different + to the original (under GnuTLS). +.next + The variables &$tls_{in,out}_ocsp$& will be "not requested" or "no response", + and the &%hosts_require_ocsp%& smtp trasnport option will fail. +. XXX need to do something with that hosts_require_ocsp +.endlist + +.endlist +.wen + .section DANE "SECDANE" .cindex DANE @@ -38021,6 +38164,7 @@ selection marked by asterisks: &`*tls_certificate_verified `& certificate verification status &`*tls_cipher `& TLS cipher suite on <= and => lines &` tls_peerdn `& TLS peer DN on <= and => lines +&` tls_resumption `& append * to cipher field &` tls_sni `& TLS SNI on <= lines &` unknown_in_list `& DNS lookup failed in list match @@ -38422,6 +38566,14 @@ connection, the cipher suite used is added to the log line, preceded by X=. connection, and a certificate is supplied by the remote host, the peer DN is added to the log line, preceded by DN=. .next +.cindex "log" "TLS resumption" +.cindex "TLS" "logging session resumption" +.new +&%tls_resumption%&: When a message is sent or received over an encrypted +connection and the TLS session resumed one used on a previous TCP connection, +an asterisk is appended to the X= cipher field in the log line. +.wen +.next .cindex "log" "TLS SNI" .cindex "TLS" "logging SNI" &%tls_sni%&: When a message is received over an encrypted connection, and @@ -38967,6 +39119,10 @@ for remote hosts .next &'ratelimit'&: the data for implementing the ratelimit ACL condition .next +.new +&'tls'&: TLS session resumption data +.wen +.next &'misc'&: other hints data .endlist @@ -41071,6 +41227,108 @@ The lookup will return the same result strings as can appear in +.section "SRS (Sender Rewriting Scheme)" SECTSRS +.cindex SRS "sender rewriting scheme" + +.new +SRS can be used to modify sender addresses when forwarding so that +SPF verification does not object to them. +It operates by encoding the original envelope sender in a new +sender local part and using a domain run by the forwarding site +as the new domain for the sender. Any DSN message should be returned +to this new sender at the forwarding site, which can extract the +original sender from the coded local part and forward the DSN to +the originator. + +This is a way of avoiding the breakage that SPF does to forwarding. +The constructed local-part will be longer than the original, +leading to possible problems with very long addresses. +The changing of the sender address also hinders the tracing of mail +problems. + +Exim can be built to include native SRS support. To do this +SUPPORT_SRS=yes must be defined in &_Local/Makefile_&. +If this has been done, the macros _HAVE_SRS and _HAVE_NATIVE_SRS +will be defined. +The support is limited to SRS0-encoding; SRS1 is not supported. + +.cindex SRS excoding +To encode an address use this expansion item: +.vlist +.vitem &*${srs_encode&~{*&<&'secret'&>&*}{*&<&'return&~path'&>&*}{*&<&'original&~domain'&>&*}}*& +.cindex "&%srs_encode%& expansion item" +.cindex SRS "expansion item" +The first argument should be a secret known and used by all systems +handling the recipient domain for the original message. +There is no need to periodically change this key; a timestamp is also +encoded. +The second argument should be given as the envelope sender address before this +encoding operation. +The third argument should be the recipient domain of the message when +it arrived at this system. +.endlist + +.cindex SRS decoding +To decode an address use this expansion condition: +.vlist +.vitem &*inbound_srs&~{*&<&'local&~part'&>&*}{*&<&'secret'&>&*}*& +The first argument should be the recipient local prt as is was received. +The second argument is the site secret. + +If the messages is not for an SRS-encoded recipient the condition will +return false. If it is, the condition will return true and the variable +&$srs_recipient$& will be set to the decoded (original) value. +.endlist + +Example usage: +.code + #macro + SRS_SECRET = + + #routers + + outbound: + driver = dnslookup + # if outbound, and forwarding has been done, use an alternate transport + domains = ! +my_domains + transport = ${if eq {$local_part@$domain} \ + {$original_local_part@$original_domain} \ + {remote_smtp} {remote_forwarded_smtp}} + + inbound_srs: + driver = redirect + senders = : + domains = +my_domains + # detect inbound bounces which are SRS'd, and decode them + condition = ${if inbound_srs {$local_part} {SRS_SECRET}} + data = $srs_recipient + + inbound_srs_failure: + driver = redirect + senders = : + domains = +my_domains + # detect inbound bounces which look SRS'd but are invalid + condition = ${if inbound_srs {$local_part} {}} + allow_fail + data = :fail: Invalid SRS recipient address + + #... further routers here + + + # transport; should look like the non-forward outbound + # one, plus the max_rcpt and return_path options + remote_forwarded_smtp: + driver = smtp + # modify the envelope from, for mails that we forward + max_rcpt = 1 + return_path = ${srs_encode {SRS_SECRET} {$return_path} {$original_domain}} +.endd + + +.wen + + + .section DMARC SECDMARC .cindex DMARC verification