+. ////////////////////////////////////////////////////////////////////////////
+. ////////////////////////////////////////////////////////////////////////////
+
+.chapter "Support for DKIM (DomainKeys Identified Mail)" "CHAPdkim" &&&
+ "DKIM Support"
+.cindex "DKIM"
+
+DKIM is a mechanism by which messages sent by some entity can be provably
+linked to a domain which that entity controls. It permits reputation to
+be tracked on a per-domain basis, rather than merely upon source IP address.
+DKIM is documented in RFC 4871.
+
+DKIM support is compiled into Exim by default if TLS support is present.
+It can be disabled by setting DISABLE_DKIM=yes in &_Local/Makefile_&.
+
+Exim's DKIM implementation allows for
+.olist
+Signing outgoing messages: This function is implemented in the SMTP transport.
+It can co-exist with all other Exim features
+(including transport filters)
+except cutthrough delivery.
+.next
+Verifying signatures in incoming messages: This is implemented by an additional
+ACL (acl_smtp_dkim), which can be called several times per message, with
+different signature contexts.
+.endlist
+
+In typical Exim style, the verification implementation does not include any
+default "policy". Instead it enables you to build your own policy using
+Exim's standard controls.
+
+Please note that verification of DKIM signatures in incoming mail is turned
+on by default for logging purposes. For each signature in incoming email,
+exim will log a line displaying the most important signature details, and the
+signature status. Here is an example (with line-breaks added for clarity):
+.code
+2009-09-09 10:22:28 1MlIRf-0003LU-U3 DKIM:
+ d=facebookmail.com s=q1-2009b
+ c=relaxed/relaxed a=rsa-sha1
+ i=@facebookmail.com t=1252484542 [verification succeeded]
+.endd
+You might want to turn off DKIM verification processing entirely for internal
+or relay mail sources. To do that, set the &%dkim_disable_verify%& ACL
+control modifier. This should typically be done in the RCPT ACL, at points
+where you accept mail from relay sources (internal hosts or authenticated
+senders).
+
+
+.section "Signing outgoing messages" "SECDKIMSIGN"
+.cindex "DKIM" "signing"
+
+Signing is enabled by setting private options on the SMTP transport.
+These options take (expandable) strings as arguments.
+
+.option dkim_domain smtp string&!! unset
+MANDATORY:
+The domain you want to sign with. The result of this expanded
+option is put into the &%$dkim_domain%& expansion variable.
+If it is empty after expansion, DKIM signing is not done.
+
+.option dkim_selector smtp string&!! unset
+MANDATORY:
+This sets the key selector string. You can use the &%$dkim_domain%& expansion
+variable to look up a matching selector. The result is put in the expansion
+variable &%$dkim_selector%& which may be used in the &%dkim_private_key%&
+option along with &%$dkim_domain%&.
+
+.option dkim_private_key smtp string&!! unset
+MANDATORY:
+This sets the private key to use. You can use the &%$dkim_domain%& and
+&%$dkim_selector%& expansion variables to determine the private key to use.
+The result can either
+.ilist
+be a valid RSA private key in ASCII armor, including line breaks.
+.next
+start with a slash, in which case it is treated as a file that contains
+the private key.
+.next
+be "0", "false" or the empty string, in which case the message will not
+be signed. This case will not result in an error, even if &%dkim_strict%&
+is set.
+.endlist
+
+.option dkim_canon smtp string&!! unset
+OPTIONAL:
+This option sets the canonicalization method used when signing a message.
+The DKIM RFC currently supports two methods: "simple" and "relaxed".
+The option defaults to "relaxed" when unset. Note: the current implementation
+only supports using the same canonicalization method for both headers and body.
+
+.option dkim_strict smtp string&!! unset
+OPTIONAL:
+This option defines how Exim behaves when signing a message that
+should be signed fails for some reason. When the expansion evaluates to
+either "1" or "true", Exim will defer. Otherwise Exim will send the message
+unsigned. You can use the &%$dkim_domain%& and &%$dkim_selector%& expansion
+variables here.
+
+.option dkim_sign_headers smtp string&!! unset
+OPTIONAL:
+When set, this option must expand to (or be specified as) a colon-separated
+list of header names. Headers with these names will be included in the message
+signature. When unspecified, the header names recommended in RFC4871 will be
+used.
+
+
+.section "Verifying DKIM signatures in incoming mail" "SECID514"
+.cindex "DKIM" "verification"
+
+Verification of DKIM signatures in SMTP incoming email is implemented via the
+&%acl_smtp_dkim%& ACL. By default, this ACL is called once for each
+syntactically(!) correct signature in the incoming message.
+A missing ACL definition defaults to accept.
+If any ACL call does not accept, the message is not accepted.
+If a cutthrough delivery was in progress for the message it is
+summarily dropped (having wasted the transmission effort).
+
+To evaluate the signature in the ACL a large number of expansion variables
+containing the signature status and its details are set up during the
+runtime of the ACL.
+
+Calling the ACL only for existing signatures is not sufficient to build
+more advanced policies. For that reason, the global option
+&%dkim_verify_signers%&, and a global expansion variable
+&%$dkim_signers%& exist.
+
+The global option &%dkim_verify_signers%& can be set to a colon-separated
+list of DKIM domains or identities for which the ACL &%acl_smtp_dkim%& is
+called. It is expanded when the message has been received. At this point,
+the expansion variable &%$dkim_signers%& already contains a colon-separated
+list of signer domains and identities for the message. When
+&%dkim_verify_signers%& is not specified in the main configuration,
+it defaults as:
+.code
+dkim_verify_signers = $dkim_signers
+.endd
+This leads to the default behaviour of calling &%acl_smtp_dkim%& for each
+DKIM signature in the message. Current DKIM verifiers may want to explicitly
+call the ACL for known domains or identities. This would be achieved as follows:
+.code
+dkim_verify_signers = paypal.com:ebay.com:$dkim_signers
+.endd
+This would result in &%acl_smtp_dkim%& always being called for "paypal.com"
+and "ebay.com", plus all domains and identities that have signatures in the message.
+You can also be more creative in constructing your policy. For example:
+.code
+dkim_verify_signers = $sender_address_domain:$dkim_signers
+.endd
+
+If a domain or identity is listed several times in the (expanded) value of
+&%dkim_verify_signers%&, the ACL is only called once for that domain or identity.
+
+
+Inside the &%acl_smtp_dkim%&, the following expansion variables are
+available (from most to least important):
+
+
+.vlist
+.vitem &%$dkim_cur_signer%&
+The signer that is being evaluated in this ACL run. This can be a domain or
+an identity. This is one of the list items from the expanded main option
+&%dkim_verify_signers%& (see above).
+
+.vitem &%$dkim_verify_status%&
+A string describing the general status of the signature. One of
+.ilist
+&%none%&: There is no signature in the message for the current domain or
+identity (as reflected by &%$dkim_cur_signer%&).
+.next
+&%invalid%&: The signature could not be verified due to a processing error.
+More detail is available in &%$dkim_verify_reason%&.
+.next
+&%fail%&: Verification of the signature failed. More detail is
+available in &%$dkim_verify_reason%&.
+.next
+&%pass%&: The signature passed verification. It is valid.
+.endlist
+
+.vitem &%$dkim_verify_reason%&
+A string giving a little bit more detail when &%$dkim_verify_status%& is either
+"fail" or "invalid". One of
+.ilist
+&%pubkey_unavailable%& (when &%$dkim_verify_status%&="invalid"): The public
+key for the domain could not be retrieved. This may be a temporary problem.
+.next
+&%pubkey_syntax%& (when &%$dkim_verify_status%&="invalid"): The public key
+record for the domain is syntactically invalid.
+.next
+&%bodyhash_mismatch%& (when &%$dkim_verify_status%&="fail"): The calculated
+body hash does not match the one specified in the signature header. This
+means that the message body was modified in transit.
+.next
+&%signature_incorrect%& (when &%$dkim_verify_status%&="fail"): The signature
+could not be verified. This may mean that headers were modified,
+re-written or otherwise changed in a way which is incompatible with
+DKIM verification. It may of course also mean that the signature is forged.
+.endlist
+
+.vitem &%$dkim_domain%&
+The signing domain. IMPORTANT: This variable is only populated if there is
+an actual signature in the message for the current domain or identity (as
+reflected by &%$dkim_cur_signer%&).
+
+.vitem &%$dkim_identity%&
+The signing identity, if present. IMPORTANT: This variable is only populated
+if there is an actual signature in the message for the current domain or
+identity (as reflected by &%$dkim_cur_signer%&).
+
+.vitem &%$dkim_selector%&
+The key record selector string.
+
+.vitem &%$dkim_algo%&
+The algorithm used. One of 'rsa-sha1' or 'rsa-sha256'.
+
+.vitem &%$dkim_canon_body%&
+The body canonicalization method. One of 'relaxed' or 'simple'.
+
+.vitem &%dkim_canon_headers%&
+The header canonicalization method. One of 'relaxed' or 'simple'.
+
+.vitem &%$dkim_copiedheaders%&
+A transcript of headers and their values which are included in the signature
+(copied from the 'z=' tag of the signature).
+Note that RFC6376 requires that verification fail if the From: header is
+not included in the signature. Exim does not enforce this; sites wishing
+strict enforcement should code the check explicitly.
+
+.vitem &%$dkim_bodylength%&
+The number of signed body bytes. If zero ("0"), the body is unsigned. If no
+limit was set by the signer, "9999999999999" is returned. This makes sure
+that this variable always expands to an integer value.
+
+.vitem &%$dkim_created%&
+UNIX timestamp reflecting the date and time when the signature was created.
+When this was not specified by the signer, "0" is returned.
+
+.vitem &%$dkim_expires%&
+UNIX timestamp reflecting the date and time when the signer wants the
+signature to be treated as "expired". When this was not specified by the
+signer, "9999999999999" is returned. This makes it possible to do useful
+integer size comparisons against this value.
+
+.vitem &%$dkim_headernames%&
+A colon-separated list of names of headers included in the signature.
+
+.vitem &%$dkim_key_testing%&
+"1" if the key record has the "testing" flag set, "0" if not.
+
+.vitem &%$dkim_key_nosubdomains%&
+"1" if the key record forbids subdomaining, "0" otherwise.
+
+.vitem &%$dkim_key_srvtype%&
+Service type (tag s=) from the key record. Defaults to "*" if not specified
+in the key record.
+
+.vitem &%$dkim_key_granularity%&
+Key granularity (tag g=) from the key record. Defaults to "*" if not specified
+in the key record.
+
+.vitem &%$dkim_key_notes%&
+Notes from the key record (tag n=).
+
+.vitem &%$dkim_key_length%&
+Number of bits in the key.
+.endlist
+
+In addition, two ACL conditions are provided:
+
+.vlist
+.vitem &%dkim_signers%&
+ACL condition that checks a colon-separated list of domains or identities
+for a match against the domain or identity that the ACL is currently verifying
+(reflected by &%$dkim_cur_signer%&). This is typically used to restrict an ACL
+verb to a group of domains or identities. For example:
+
+.code
+# Warn when Mail purportedly from GMail has no gmail signature
+warn log_message = GMail sender without gmail.com DKIM signature
+ sender_domains = gmail.com
+ dkim_signers = gmail.com
+ dkim_status = none
+.endd
+
+Note that the above does not check for a total lack of DKIM signing;
+for that check for empty &$h_DKIM-Signature:$& in the data ACL.
+
+.vitem &%dkim_status%&
+ACL condition that checks a colon-separated list of possible DKIM verification
+results against the actual result of verification. This is typically used
+to restrict an ACL verb to a list of verification outcomes, for example:
+
+.code
+deny message = Mail from Paypal with invalid/missing signature
+ sender_domains = paypal.com:paypal.de
+ dkim_signers = paypal.com:paypal.de
+ dkim_status = none:invalid:fail
+.endd
+
+The possible status keywords are: 'none','invalid','fail' and 'pass'. Please
+see the documentation of the &%$dkim_verify_status%& expansion variable above
+for more information of what they mean.
+.endlist
+
+. ////////////////////////////////////////////////////////////////////////////
+. ////////////////////////////////////////////////////////////////////////////
+
+.chapter "Proxies" "CHAPproxies" &&&
+ "Proxy support"
+.cindex "proxy support"
+.cindex "proxy" "access via"
+
+A proxy is an intermediate system through which communication is passed.
+Proxies may provide a security, availability or load-distribution function.
+
+
+.section "Inbound proxies" SECTproxyInbound
+.cindex proxy inbound
+.cindex proxy "server side"
+.cindex proxy "Proxy protocol"
+.cindex "Proxy protocol" proxy
+
+Exim has support for receiving inbound SMTP connections via a proxy
+that uses &"Proxy Protocol"& to speak to it.
+To include this support, include &"SUPPORT_PROXY=yes"&
+in Local/Makefile.
+
+It was built on specifications from:
+(&url(http://haproxy.1wt.eu/download/1.5/doc/proxy-protocol.txt)).
+That URL was revised in May 2014 to version 2 spec:
+(&url(http://git.1wt.eu/web?p=haproxy.git;a=commitdiff;h=afb768340c9d7e50d8e)).
+
+The purpose of this facility is so that an application load balancer,
+such as HAProxy, can sit in front of several Exim servers
+to distribute load.
+Exim uses the local protocol communication with the proxy to obtain
+the remote SMTP system IP address and port information.
+There is no logging if a host passes or
+fails Proxy Protocol negotiation, but it can easily be determined and
+recorded in an ACL (example is below).
+
+Use of a proxy is enabled by setting the &%hosts_proxy%&
+main configuration option to a hostlist; connections from these
+hosts will use Proxy Protocol.
+
+The following expansion variables are usable
+(&"internal"& and &"external"& here refer to the interfaces
+of the proxy):
+.display
+&'proxy_external_address '& IP of host being proxied or IP of remote interface of proxy
+&'proxy_external_port '& Port of host being proxied or Port on remote interface of proxy
+&'proxy_local_address '& IP of proxy server inbound or IP of local interface of proxy
+&'proxy_local_port '& Port of proxy server inbound or Port on local interface of proxy
+&'proxy_session '& boolean: SMTP connection via proxy
+.endd
+If &$proxy_session$& is set but &$proxy_external_address$& is empty
+there was a protocol error.
+
+Since the real connections are all coming from the proxy, and the
+per host connection tracking is done before Proxy Protocol is
+evaluated, &%smtp_accept_max_per_host%& must be set high enough to
+handle all of the parallel volume you expect per inbound proxy.
+With the option set so high, you lose the ability
+to protect your server from many connections from one IP.
+In order to prevent your server from overload, you
+need to add a per connection ratelimit to your connect ACL.
+A possible solution is:
+.display
+ # Set max number of connections per host
+ LIMIT = 5
+ # Or do some kind of IP lookup in a flat file or database
+ # LIMIT = ${lookup{$sender_host_address}iplsearch{/etc/exim/proxy_limits}}
+
+ defer message = Too many connections from this IP right now
+ ratelimit = LIMIT / 5s / per_conn / strict
+.endd
+
+
+
+.section "Outbound proxies" SECTproxySOCKS
+.cindex proxy outbound
+.cindex proxy "client side"
+.cindex proxy SOCKS
+.cindex SOCKS proxy
+Exim has support for sending outbound SMTP via a proxy
+using a protocol called SOCKS5 (defined by RFC1928).
+The support can be optionally included by defining SUPPORT_SOCKS=yes in
+Local/Makefile.
+
+Use of a proxy is enabled by setting the &%socks_proxy%& option
+on an smtp transport.
+The option value is expanded and should then be a list
+(colon-separated by default) of proxy specifiers.
+Each proxy specifier is a list
+(space-separated by default) where the initial element
+is an IP address and any subsequent elements are options.
+
+Options are a string <name>=<value>.
+The list of options is in the following table:
+.display
+&'auth '& authentication method
+&'name '& authentication username
+&'pass '& authentication password
+&'port '& tcp port
+&'tmo '& connection timeout
+&'pri '& priority
+&'weight '& selection bias
+.endd
+
+More details on each of these options follows:
+
+.ilist
+.cindex authentication "to proxy"
+.cindex proxy authentication
+&%auth%&: Either &"none"& (default) or &"name"&.
+Using &"name"& selects username/password authentication per RFC 1929
+for access to the proxy.
+Default is &"none"&.
+.next
+&%name%&: sets the username for the &"name"& authentication method.
+Default is empty.
+.next
+&%pass%&: sets the password for the &"name"& authentication method.
+Default is empty.
+.next
+&%port%&: the TCP port number to use for the connection to the proxy.
+Default is 1080.
+.next
+&%tmo%&: sets a connection timeout in seconds for this proxy.
+Default is 5.
+.next
+&%pri%&: specifies a priority for the proxy within the list,
+higher values being tried first.
+The default priority is 1.
+.next
+&%weight%&: specifies a selection bias.
+Within a priority set servers are queried in a random fashion,
+weighted by this value.
+The default value for selection bias is 1.
+.endlist
+
+Proxies from the list are tried according to their priority
+and weight settings until one responds. The timeout for the
+overall connection applies to the set of proxied attempts.
+
+.section Logging SECTproxyLog
+To log the (local) IP of a proxy in the incoming or delivery logline,
+add &"+proxy"& to the &%log_selector%& option.
+This will add a component tagged with &"PRX="& to the line.
+
+. ////////////////////////////////////////////////////////////////////////////
+. ////////////////////////////////////////////////////////////////////////////
+
+.chapter "Internationalisation" "CHAPi18n" &&&
+ "Internationalisation""
+.cindex internationalisation "email address"
+.cindex EAI
+.cindex i18n
+.cindex UTF-8 "mail name handling"
+
+Exim has support for Internationalised mail names.
+To include this it must be built with SUPPORT_I18N and the libidn library.
+Standards supported are RFCs 2060, 5890, 6530 and 6533.
+
+.section "MTA operations" SECTi18nMTA
+.cindex SMTPUTF8 "ESMTP option"
+The main configuration option &%smtputf8_advertise_hosts%& specifies
+a host list. If this matches the sending host and
+accept_8bitmime is true (the default) then the ESMTP option
+SMTPUTF8 will be advertised.
+
+If the sender specifies the SMTPUTF8 option on a MAIL command
+international handling for the message is enabled and
+the expansion variable &$message_smtputf8$& will have value TRUE.
+
+The option &%allow_utf8_domains%& is set to true for this
+message. All DNS lookups are converted to a-label form
+whatever the setting of &%allow_utf8_domains%&
+when Exim is built with SUPPORT_I18N.
+
+Both localparts and domain are maintained as the original
+UTF-8 form internally; any comparison or regular-expression use will
+require appropriate care. Filenames created, eg. by
+the appendfile transport, will have UTF-8 names.
+
+HELO names sent by the smtp transport will have any UTF-8
+components expanded to a-label form,
+and any certificate name checks will be done using the a-label
+form of the name.
+
+.cindex log protocol
+.cindex SMTPUTF8 logging
+Log lines and Received-by: header lines will acquire a "utf8"
+prefix on the protocol element, eg. utf8esmtp.
+
+The following expansion operators can be used:
+.code
+${utf8_domain_to_alabel:str}
+${utf8_domain_from_alabel:str}
+${utf8_localpart_to_alabel:str}
+${utf8_localpart_from_alabel:str}
+.endd
+
+ACLs may use the following modifier:
+.display
+control = utf8_downconvert
+control = utf8_downconvert/<value>
+.endd
+This sets a flag requiring that addresses are converted to
+a-label form before smtp delivery, for use in a
+Message Submission Agent context.
+If a value is appended it may be:
+.display
+&`1 `& (default) mandatory downconversion
+&`0 `& no downconversion
+&`-1 `& if SMTPUTF8 not supported by destination host
+.endd
+
+If mua_wrapper is set, the utf8_downconvert control
+is initially set to -1.
+
+
+There is no explicit support for VRFY and EXPN.
+Configurations supporting these should inspect
+&$smtp_command_argument$& for an SMTPUTF8 argument.
+
+There is no support for LMTP on Unix sockets.
+Using the "lmtp" protocol option on an smtp transport,
+for LMTP over TCP, should work as expected.
+
+There is no support for DSN unitext handling,
+and no provision for converting logging from or to UTF-8.
+
+
+
+.section "MDA operations" SECTi18nMDA
+To aid in constructing names suitable for IMAP folders
+the following expansion operator can be used:
+.code
+${imapfolder {<string>} {<sep>} {<specials>}}
+.endd
+
+The string is converted from the charset specified by
+the "headers charset" command (in a filter file)
+or &%headers_charset%& main configuration option (otherwise),
+to the
+modified UTF-7 encoding specified by RFC 2060,
+with the following exception: All occurences of <sep>
+(which has to be a single character)
+are replaced with periods ("."), and all periods and slashes that are not
+<sep> and are not in the <specials> string are BASE64 encoded.
+
+The third argument can be omitted, defaulting to an empty string.
+The second argument can be omitted, defaulting to "/".
+
+This is the encoding used by Courier for Maildir names on disk, and followed
+by many other IMAP servers.
+
+Examples:
+.display
+&`${imapfolder {Foo/Bar}} `& yields &`Foo.Bar`&
+&`${imapfolder {Foo/Bar}{.}{/}} `& yields &`Foo&&AC8-Bar`&
+&`${imapfolder {Räksmörgås}} `& yields &`R&&AOQ-ksm&&APY-rg&&AOU-s`&
+.endd
+
+Note that the source charset setting is vital, and also that characters
+must be representable in UTF-16.
+
git://git.exim.org / exim.git / blobdiff