Docs: warn against using $local_part directly in delivery
[users/jgh/exim.git] / doc / doc-docbook / spec.xfpt
index abd15d452dbad0b940cd4a8f8666d01219e3ca1e..8b15227950c8f9c710b7ddfdfa629d4b15b99064 100644 (file)
@@ -4383,6 +4383,17 @@ written. When &%-oX%& is used with &%-bd%&, or when &%-q%& with a time is used
 without &%-bd%&, this is the only way of causing Exim to write a pid file,
 because in those cases, the normal pid file is not used.
 
+.new
+.vitem &%-oPX%&
+.oindex "&%-oPX%&"
+.cindex "pid (process id)" "of daemon"
+.cindex "daemon" "process id (pid)"
+This option is not intended for general use.
+The daemon uses it when terminating due to a SIGTEM, possibly in
+combination with &%-oP%&&~<&'path'&>.
+It causes the pid file to be removed.
+.wen
+
 .vitem &%-or%&&~<&'time'&>
 .oindex "&%-or%&"
 .cindex "timeout" "for non-SMTP input"
@@ -6351,7 +6362,7 @@ All other options are defaulted.
 .code
 local_delivery:
   driver = appendfile
-  file = /var/mail/$local_part
+  file = /var/mail/$home
   delivery_date_add
   envelope_to_add
   return_path_add
@@ -12374,6 +12385,18 @@ Global address rewriting happens when a message is received, so the value of
 because a message may have many recipients and the system filter is called just
 once.
 
+.new
+&*Warning*&: the content of this variable is provided by a potential attacker.
+Consider carefully the implications of using it unvalidated as a name
+for file access.
+This presents issues for users' &_.forward_& and filter files.
+For traditional full user accounts, use &%check_local_users%& and the &$home$&
+variable rather than this one.
+For virtual users, store a suitable pathname component in the database
+which is used for account name validation, and use that retrieved value
+rather than this variable.
+.wen
+
 .vindex "&$local_part_prefix$&"
 .vindex "&$local_part_suffix$&"
 .cindex affix variables
@@ -15111,15 +15134,22 @@ etc. are ignored. If IP literals are enabled, the &(ipliteral)& router declines
 to handle IPv6 literal addresses.
 
 
-.option dkim_verify_hashes main "string list" "sha256 : sha512 : sha1"
+.new
+.option dkim_verify_hashes main "string list" "sha256 : sha512"
 .cindex DKIM "selecting signature algorithms"
 This option gives a list of hash types which are acceptable in signatures,
+.wen
 and an order of processing.
 Signatures with algorithms not in the list will be ignored.
 
-Note that the presence of sha1 violates RFC 8301.
-Signatures using the rsa-sha1 are however (as of writing) still common.
-The default inclusion of sha1 may be dropped in a future release.
+Acceptable values include:
+.code
+sha1
+sha256
+sha512
+.endd
+
+Note that the acceptance of sha1 violates RFC 8301.
 
 .option dkim_verify_keytypes main "string list" "ed25519 : rsa"
 This option gives a list of key types which are acceptable in signatures,
@@ -20510,6 +20540,15 @@ is not the case when the file contains syntactically valid items that happen to
 yield empty addresses, for example, items containing only RFC 2822 address
 comments.
 
+.new
+&*Warning*&: It is unwise to use &$local_part$& or &$domain$&
+directly for redirection,
+as they are provided by a potential attacker.
+In the examples above, &$local_part$& is used for looking up data held locally
+on the system, and not used directly (the second example derives &$home$& via
+the passsword file or database, using &$local_part$&).
+.wen
+
 
 
 .section "Forward files and address verification" "SECID125"
@@ -24870,6 +24909,9 @@ unauthenticated. See also &%hosts_require_auth%&, and chapter
 .cindex "RFC 3030" "CHUNKING"
 This option provides a list of servers to which, provided they announce
 CHUNKING support, Exim will attempt to use BDAT commands rather than DATA.
+.new
+Unless DKIM signing is being done,
+.wen
 BDAT will not be used in conjunction with a transport filter.
 
 .option hosts_try_dane smtp "host list&!!" *
@@ -27342,7 +27384,7 @@ but it is present in many binary distributions.
 .scindex IIDdcotauth1 "&(dovecot)& authenticator"
 .scindex IIDdcotauth2 "authenticators" "&(dovecot)&"
 This authenticator is an interface to the authentication facility of the
-Dovecot POP/IMAP server, which can support a number of authentication methods.
+Dovecot POP/IMAP server, which can support a number of authentication methods.
 Note that Dovecot must be configured to use auth-client not auth-userdb.
 If you are using Dovecot to authenticate POP/IMAP clients, it might be helpful
 to use the same mechanisms for SMTP authentication. This is a server
@@ -27373,6 +27415,29 @@ option is passed in the Dovecot authentication command. If, for a TLS
 connection, a client certificate has been verified, the &"valid-client-cert"&
 option is passed. When authentication succeeds, the identity of the user
 who authenticated is placed in &$auth1$&.
+
+.new
+The Dovecot configuration to match the above wil look
+something like:
+.code
+conf.d/10-master.conf :-
+
+service auth {
+...
+#SASL
+  unix_listener auth-client {
+    mode = 0660
+    user = mail
+  }
+...
+}
+
+conf.d/10-auth.conf :-
+
+auth_mechanisms = plain login ntlm
+.endd
+.wen
+
 .ecindex IIDdcotauth1
 .ecindex IIDdcotauth2
 
@@ -27391,19 +27456,45 @@ who authenticated is placed in &$auth1$&.
 .cindex "authentication" "DIGEST-MD5"
 .cindex "authentication" "CRAM-MD5"
 .cindex "authentication" "SCRAM-SHA-1"
-The &(gsasl)& authenticator provides server integration for the GNU SASL
+.cindex "authentication" "SCRAM-SHA-1-PLUS"
+.cindex "authentication" "SCRAM-SHA-256"
+.cindex "authentication" "SCRAM-SHA-256-PLUS"
+The &(gsasl)& authenticator provides integration for the GNU SASL
 library and the mechanisms it provides.  This is new as of the 4.80 release
 and there are a few areas where the library does not let Exim smoothly
 scale to handle future authentication mechanisms, so no guarantee can be
 made that any particular new authentication mechanism will be supported
 without code changes in Exim.
 
-Exim's &(gsasl)& authenticator does not have client-side support at this
-time; only the server-side support is implemented.  Patches welcome.
+.new
+The library is expected to add support in an upcoming
+realease for the SCRAM-SHA-256 method.
+The macro _HAVE_AUTH_GSASL_SCRAM_SHA_256 will be defined
+when this happens.
+
 
+.option client_authz gsasl string&!! unset
+This option can be used to supply an &'authorization id'&
+which is different to the &'authentication_id'& provided
+by &%client_username%& option.
+If unset or (after expansion) empty it is not used,
+which is the common case.
+
+.option client_channelbinding gsasl boolean false
+See &%server_channelbinding%& below.
+
+.option client_password gsasl string&!! unset
+This option is exapanded before use, and should result in
+the password to be used, in clear.
+
+.option client_username gsasl string&!! unset
+This option is exapanded before use, and should result in
+the account name to be used.
+.wen
 
 .option server_channelbinding gsasl boolean false
-Do not set this true without consulting a cryptographic engineer.
+Do not set this true and rely on the properties
+without consulting a cryptographic engineer.
 
 Some authentication mechanisms are able to use external context at both ends
 of the session to bind the authentication to that context, and fail the
@@ -27415,15 +27506,18 @@ This should have meant that certificate identity and verification becomes a
 non-issue, as a man-in-the-middle attack will cause the correct client and
 server to see different identifiers and authentication will fail.
 
-This is currently only supported when using the GnuTLS library.  This is
+.new
+This is
 only usable by mechanisms which support "channel binding"; at time of
 writing, that's the SCRAM family.
+When using this feature the "-PLUS" variants of the method names need to be used.
+.wen
 
 This defaults off to ensure smooth upgrade across Exim releases, in case
 this option causes some clients to start failing.  Some future release
 of Exim might have switched the default to be true.
 
-However, Channel Binding in TLS has proven to be broken in current versions.
+However, Channel Binding in TLS has proven to be vulnerable in current versions.
 Do not plan to rely upon this feature for security, ever, without consulting
 with a subject matter expert (a cryptographic engineer).
 
@@ -27471,16 +27565,28 @@ This specifies the SASL realm that the server claims to be in.
 Some mechanisms will use this data.
 
 
-.option server_scram_iter gsasl string&!! unset
+.option server_scram_iter gsasl string&!! 4096
 This option provides data for the SCRAM family of mechanisms.
-&$auth1$& is not available at evaluation time.
-(This may change, as we receive feedback on use)
+.new
+The &$auth1$&, &$auth2$& and &$auth3$& variables are available for expansion.
+
+The result of expansion should be a decimal number,
+and represents both a lower-bound on the security, and
+a compute cost factor imposed on the client
+(if it does not cache results, or the server changes
+either the iteration count or the salt).
+A minimum value of 4096 is required by the standards
+for all current CRAM mechanism variants.
+.wen
 
 
 .option server_scram_salt gsasl string&!! unset
 This option provides data for the SCRAM family of mechanisms.
-&$auth1$& is not available at evaluation time.
-(This may change, as we receive feedback on use)
+.new
+The &$auth1$&, &$auth2$& and &$auth3$& variables are available for expansion.
+If unset or empty after expansion the library will provides a value for the
+protocol conversation.
+.wen
 
 
 .option server_service gsasl string &`smtp`&
@@ -30351,6 +30457,13 @@ This control turns off DKIM verification processing entirely.  For details on
 the operation and configuration of DKIM, see section &<<SECDKIM>>&.
 
 
+.vitem &*control&~=&~dmarc_disable_verify*&
+.cindex "disable DMARC verify"
+.cindex "DMARC" "disable verify"
+This control turns off DMARC verification processing entirely.  For details on
+the operation and configuration of DMARC, see section &<<SECDMARC>>&.
+
+
 .vitem &*control&~=&~dscp/*&<&'value'&>
 .cindex "&ACL;" "setting DSCP value"
 .cindex "DSCP" "inbound"
@@ -33618,7 +33731,12 @@ directory, so you might set
 HAVE_LOCAL_SCAN=yes
 LOCAL_SCAN_SOURCE=Local/local_scan.c
 .endd
-for example. The function must be called &[local_scan()]&. It is called by
+for example. The function must be called &[local_scan()]&;
+.new
+the source file(s) for it should first #define LOCAL_SCAN
+and then #include "local_scan.h".
+.wen
+It is called by
 Exim after it has received a message, when the success return code is about to
 be sent. This is after all the ACLs have been run. The return code from your
 function controls whether the message is actually accepted or not. There is a
@@ -34297,12 +34415,18 @@ dropping of a TCP/IP connection), you can call &'smtp_fflush()'&, which has no
 arguments. It flushes the output stream, and returns a non-zero value if there
 is an error.
 
-.vitem &*void&~*store_get(int)*&
+.new
+.vitem &*void&~*store_get(int,BOOL)*&
 This function accesses Exim's internal store (memory) manager. It gets a new
-chunk of memory whose size is given by the argument. Exim bombs out if it ever
+chunk of memory whose size is given by the first argument.
+The second argument should be given as TRUE if the memory will be used for
+data possibly coming from an attacker (eg. the message content),
+FALSE if it is locally-sourced.
+Exim bombs out if it ever
 runs out of memory. See the next section for a discussion of memory handling.
+.wen
 
-.vitem &*void&~*store_get_perm(int)*&
+.vitem &*void&~*store_get_perm(int,BOOL)*&
 This function is like &'store_get()'&, but it always gets memory from the
 permanent pool. See the next section for a discussion of memory handling.
 
@@ -37273,7 +37397,7 @@ the following table:
 &`DKIM`&        domain verified in incoming message
 &`DN  `&        distinguished name from peer certificate
 &`DS  `&        DNSSEC secured lookups
-&`DT  `&        on &`=>`& lines: time taken for a delivery
+&`DT  `&        on &`=>`&, &'=='& and &'**'& lines: time taken for, or to attempt, a delivery
 &`F   `&        sender address (on delivery lines)
 &`H   `&        host name and IP address
 &`I   `&        local interface used
@@ -37371,7 +37495,7 @@ selection marked by asterisks:
 &` arguments                  `&  command line arguments
 &`*connection_reject          `&  connection rejections
 &`*delay_delivery             `&  immediate delivery delayed
-&` deliver_time               `&  time taken to perform delivery
+&` deliver_time               `&  time taken to attempt delivery
 &` delivery_size              `&  add &`S=`&&'nnn'& to => lines
 &`*dkim                       `&  DKIM verified domain on <= lines
 &` dkim_verbose               `&  separate full DKIM verification result line, per signature
@@ -40489,10 +40613,12 @@ defines the location of a text file of valid
 top level domains the opendmarc library uses
 during domain parsing. Maintained by Mozilla,
 the most current version can be downloaded
-from a link at &url(https://publicsuffix.org/list/, currently pointing
-at https://publicsuffix.org/list/public_suffix_list.dat)
-See also util/renew-opendmarc-tlds.sh script.
-The default for the option is /etc/exim/opendmarc.tlds.
+from a link at &url(https://publicsuffix.org/list/public_suffix_list.dat).
+See also the util/renew-opendmarc-tlds.sh script.
+.new
+The default for the option is unset.
+If not set, DMARC processing is disabled.
+.wen
 
 
 The &%dmarc_history_file%& option, if set
@@ -41015,14 +41141,17 @@ Events have names which correspond to the point in process at which they fire.
 The name is placed in the variable &$event_name$& and the event action
 expansion must check this, as it will be called for every possible event type.
 
+.new
 The current list of events is:
+.wen
 .display
 &`dane:fail              after    transport  `& per connection
 &`msg:complete           after    main       `& per message
+&`msg:defer              after    transport  `& per message per delivery try
 &`msg:delivery           after    transport  `& per recipient
 &`msg:rcpt:host:defer    after    transport  `& per recipient per host
 &`msg:rcpt:defer         after    transport  `& per recipient
-&`msg:host:defer         after    transport  `& per attempt
+&`msg:host:defer         after    transport  `& per host per delivery try; host errors
 &`msg:fail:delivery      after    transport  `& per recipient
 &`msg:fail:internal      after    main       `& per recipient
 &`tcp:connect            before   transport  `& per connection
@@ -41048,12 +41177,13 @@ An additional variable, &$event_data$&, is filled with information varying
 with the event type:
 .display
 &`dane:fail            `& failure reason
+&`msg:defer            `& error string
 &`msg:delivery         `& smtp confirmation message
 &`msg:fail:internal    `& failure reason
 &`msg:fail:delivery    `& smtp error message
+&`msg:host:defer       `& error string
 &`msg:rcpt:host:defer  `& error string
 &`msg:rcpt:defer       `& error string
-&`msg:host:defer       `& error string
 &`tls:cert             `& verification chain depth
 &`smtp:connect         `& smtp banner
 &`smtp:ehlo            `& smtp ehlo response