certextract tidying
[users/heiko/exim.git] / doc / doc-docbook / spec.xfpt
index 6497157f618c7da3f1c8f853aeb276a17659337d..17c69a7a56e51b4fe6691a5547c3a4157ce96776 100644 (file)
@@ -5557,16 +5557,21 @@ unreachable.
 The next two lines are concerned with &'ident'& callbacks, as defined by RFC
 1413 (hence their names):
 .code
-rfc1413_hosts = *
-rfc1413_query_timeout = 5s
+rfc1413_query_hosts = *
+rfc1413_query_timeout = 0s
+.endd
+These settings cause Exim to avoid ident callbacks for all incoming SMTP calls.
+Few hosts offer RFC1413 service these days; calls have to be
+terminated by a timeout and this needlessly delays the startup
+of an incoming SMTP connection.
+If you have hosts for which you trust RFC1413 and need this
+information, you can change this.
+
+This line enables an efficiency SMTP option.  It is negociated by clients
+and not expected to cause problems but can be disabled if needed.
+.code
+prdr_enable = true
 .endd
-These settings cause Exim to make ident callbacks for all incoming SMTP calls.
-You can limit the hosts to which these calls are made, or change the timeout
-that is used. If you set the timeout to zero, all ident calls are disabled.
-Although they are cheap and can provide useful information for tracing problem
-messages, some hosts and firewalls have problems with ident calls. This can
-result in a timeout instead of an immediate refused connection, leading to
-delays on starting up an incoming SMTP session.
 
 When Exim receives messages over SMTP connections, it expects all addresses to
 be fully qualified with a domain, as required by the SMTP definition. However,
@@ -6002,9 +6007,14 @@ One remote transport and four local transports are defined.
 .code
 remote_smtp:
   driver = smtp
+  hosts_try_prdr = *
 .endd
-This transport is used for delivering messages over SMTP connections. All its
-options are defaulted. The list of remote hosts comes from the router.
+This transport is used for delivering messages over SMTP connections.
+The list of remote hosts comes from the router.
+The &%hosts_try_prdr%& option enables an efficiency SMTP option.
+It is negotiated between client and server
+and not expected to cause problems but can be disabled if needed.
+All other options are defaulted.
 .code
 local_delivery:
   driver = appendfile
@@ -8887,8 +8897,8 @@ the certificate.  Supported fields are:
 .display
 &`version        `&
 &`serial_number  `&
-&`subject        `&
-&`issuer         `&
+&`subject        `& RFC4514 DN
+&`issuer         `& RFC4514 DN
 &`notbefore      `&
 &`notafter       `&
 &`sig_algorithm  `&
@@ -8921,6 +8931,12 @@ Elements of only one type may be selected by a modifier
 which is one of "dns", "uri" or "mail";
 if so the elenment tags are omitted.
 
+The field selectors marked as "RFC4514" above
+output a Distinguished Name string which is
+not quite
+parseable by Exim as a comma-separated tagged list
+(the exceptions being elements containin commas).
+
 Field values are generally presented in human-readable form.
 .wen
 
@@ -10036,6 +10052,7 @@ Letters in IPv6 addresses are always output in lower case.
 .vitem &*${md5:*&<&'string'&>&*}*&
 .cindex "MD5 hash"
 .cindex "expansion" "MD5 hash"
+.cindex "certificate fingerprint"
 .cindex "&%md5%& expansion item"
 The &%md5%& operator computes the MD5 hash value of the string, and returns it
 as a 32-digit hexadecimal number, in which any letters are in lower case.
@@ -10173,11 +10190,24 @@ variables or headers inside regular expressions.
 .vitem &*${sha1:*&<&'string'&>&*}*&
 .cindex "SHA-1 hash"
 .cindex "expansion" "SHA-1 hashing"
+.cindex "certificate fingerprint"
 .cindex "&%sha2%& expansion item"
 The &%sha1%& operator computes the SHA-1 hash value of the string, and returns
 it as a 40-digit hexadecimal number, in which any letters are in upper case.
 
 
+.vitem &*${sha256:*&<&'certificate'&>&*}*&
+.cindex "SHA-256 hash"
+.cindex "certificate fingerprint"
+.cindex "expansion" "SHA-256 hashing"
+.cindex "&%sha256%& expansion item"
+The &%sha256%& operator computes the SHA-256 hash fingerprint of the
+certificate,
+and returns
+it as a 64-digit hexadecimal number, in which any letters are in upper case.
+Only arguments which are a single variable of certificate type are supported.
+
+
 .vitem &*${stat:*&<&'string'&>&*}*&
 .cindex "expansion" "statting a file"
 .cindex "file" "extracting characteristics"
@@ -12308,7 +12338,8 @@ If TLS has not been negotiated, the value will be 0.
 This variable refers to the certificate presented to the peer of an
 inbound connection when the message was received.
 It is only useful as the argument of a
-&%certextract%& expansion item or the name for a &%def%& expansion condition.
+&%certextract%& expansion item, &%md5%& or &%sha1%& operator,
+or a &%def%& condition.
 .wen
 
 .new
@@ -12317,7 +12348,8 @@ It is only useful as the argument of a
 This variable refers to the certificate presented by the peer of an
 inbound connection when the message was received.
 It is only useful as the argument of a
-&%certextract%& expansion item or the name for a &%def%& expansion condition.
+&%certextract%& expansion item, &%md5%& or &%sha1%& operator,
+or a &%def%& condition.
 .wen
 
 .new
@@ -12325,7 +12357,8 @@ It is only useful as the argument of a
 .vindex "&$tls_out_ourcert$&"
 This variable refers to the certificate presented to the peer of an
 outbound connection.  It is only useful as the argument of a
-&%certextract%& expansion item or the name for a &%def%& expansion condition.
+&%certextract%& expansion item, &%md5%& or &%sha1%& operator,
+or a &%def%& condition.
 .wen
 
 .new
@@ -12333,7 +12366,8 @@ outbound connection.  It is only useful as the argument of a
 .vindex "&$tls_out_peercert$&"
 This variable refers to the certificate presented by the peer of an
 outbound connection.  It is only useful as the argument of a
-&%certextract%& expansion item or the name for a &%def%& expansion condition.
+&%certextract%& expansion item, &%md5%& or &%sha1%& operator,
+or a &%def%& condition.
 .wen
 
 .vitem &$tls_in_certificate_verified$&
@@ -13117,6 +13151,7 @@ listed in more than one group.
 .row &%acl_smtp_auth%&               "ACL for AUTH"
 .row &%acl_smtp_connect%&            "ACL for connection"
 .row &%acl_smtp_data%&               "ACL for DATA"
+.row &%acl_smtp_data_prdr%&          "ACL for DATA, per-recipient"
 .row &%acl_smtp_dkim%&               "ACL for DKIM verification"
 .row &%acl_smtp_etrn%&               "ACL for ETRN"
 .row &%acl_smtp_expn%&               "ACL for EXPN"
@@ -13272,6 +13307,7 @@ See also the &'Policy controls'& section above.
 .row &%ignore_fromline_hosts%&       "allow &""From ""& from these hosts"
 .row &%ignore_fromline_local%&       "allow &""From ""& from local SMTP"
 .row &%pipelining_advertise_hosts%&  "advertise pipelining to these hosts"
+.row &%prdr_enable%&                 "advertise PRDR to all hosts"
 .row &%tls_advertise_hosts%&         "advertise TLS to these hosts"
 .endtable
 
@@ -13423,6 +13459,16 @@ This option defines the ACL that is run after an SMTP DATA command has been
 processed and the message itself has been received, but before the final
 acknowledgment is sent. See chapter &<<CHAPACL>>& for further details.
 
+.option acl_smtp_data_prdr main string&!! unset
+.cindex "DATA" "ACL for"
+.cindex "&ACL;" "PRDR-related"
+.cindex "&ACL;" "per-user data processing"
+This option defines the ACL that,
+if the PRDR feature has been negotiated,
+is run for each recipient after an SMTP DATA command has been
+processed and the message itself has been received, but before the
+acknowledgment is sent. See chapter &<<CHAPACL>>& for further details.
+
 .option acl_smtp_etrn main string&!! unset
 .cindex "ETRN" "ACL for"
 This option defines the ACL that is run when an SMTP ETRN command is
@@ -15065,6 +15111,15 @@ that clients will use it; &"out of order"& commands that are &"expected"& do
 not count as protocol errors (see &%smtp_max_synprot_errors%&).
 
 
+.option prdr_enable main boolean false
+.cindex "PRDR" "enabling on server"
+This option can be used to enable the Per-Recipient Data Response extension
+to SMTP, defined by Eric Hall.
+If the option is set, PRDR is advertised by Exim when operating as a server.
+If the client requests PRDR, and more than one recipient, for a message 
+an additional ACL is called for each recipient after the message content
+is recieved.  See section &<<SECTPRDRACL>>&.
+
 .option preserve_message_logs main boolean false
 .cindex "message logs" "preserving"
 If this option is set, message log files are not deleted when messages are
@@ -22955,6 +23010,12 @@ connects. If authentication fails, Exim will try to transfer the message
 unauthenticated. See also &%hosts_require_auth%&, and chapter
 &<<CHAPSMTPAUTH>>& for details of authentication.
 
+.option hosts_try_prdr smtp "host list&!!" unset
+.cindex "PRDR" "enabling, optional in client"
+This option provides a list of servers to which, provided they announce
+PRDR support, Exim will attempt to negotiate PRDR
+for multi-recipient messages.
+
 .option interface smtp "string list&!!" unset
 .cindex "bind IP address"
 .cindex "IP address" "binding"
@@ -23211,6 +23272,11 @@ in clear.
 This option gives a list of hosts for which, on encrypted connections,
 certificate verification will be tried but need not succeed.
 The &%tls_verify_certificates%& option must also be set.
+Note that unless the host is in this list
+TLS connections will be denied to hosts using self-signed certificates
+when &%tls_verify_certificates%& is set.
+The &$tls_out_certificate_verified$& variable is set when
+certificate verification succeeds.
 
 
 .option tls_verify_certificates smtp string&!! unset
@@ -26442,6 +26508,7 @@ options in the main part of the configuration. These options are:
 .cindex "SMTP" "connection, ACL for"
 .cindex "non-SMTP messages" "ACLs for"
 .cindex "MIME content scanning" "ACL for"
+.cindex "PRDR" "ACL for"
 
 .table2 140pt
 .irow &%acl_not_smtp%&         "ACL for non-SMTP messages"
@@ -26450,6 +26517,7 @@ options in the main part of the configuration. These options are:
 .irow &%acl_smtp_auth%&        "ACL for AUTH"
 .irow &%acl_smtp_connect%&     "ACL for start of SMTP connection"
 .irow &%acl_smtp_data%&        "ACL after DATA is complete"
+.irow &%acl_smtp_data_prdr%&   "ACL for each recipient, after DATA is complete"
 .irow &%acl_smtp_etrn%&        "ACL for ETRN"
 .irow &%acl_smtp_expn%&        "ACL for EXPN"
 .irow &%acl_smtp_helo%&        "ACL for HELO or EHLO"
@@ -26564,8 +26632,10 @@ before or after the data) correctly &-- they keep the message on their queues
 and try again later, but that is their problem, though it does waste some of
 your resources.
 
-The &%acl_smtp_data%& ACL is run after both the &%acl_smtp_dkim%& and
-the &%acl_smtp_mime%& ACLs.
+The &%acl_smtp_data%& ACL is run after
+the &%acl_smtp_data_prdr%&,
+the &%acl_smtp_dkim%&
+and the &%acl_smtp_mime%& ACLs.
 
 .section "The SMTP DKIM ACL" "SECTDKIMACL"
 The &%acl_smtp_dkim%& ACL is available only when Exim is compiled with DKIM support
@@ -26587,6 +26657,36 @@ content-scanning extension. For details, see chapter &<<CHAPexiscan>>&.
 This ACL is evaluated after &%acl_smtp_dkim%& but before &%acl_smtp_data%&.
 
 
+.section "The SMTP PRDR ACL" "SECTPRDRACL"
+.oindex "&%prdr_enable%&"
+The &%acl_smtp_data_prdr%& ACL is available only when Exim is compiled
+with PRDR support enabled (which is the default).
+It becomes active only when the PRDR feature is negotiated between
+client and server for a message, and more than one recipient
+has been accepted.
+
+The ACL test specfied by &%acl_smtp_data_prdr%& happens after a message
+has been recieved, and is executed for each recipient of the message.
+The test may accept or deny for inividual recipients.
+The &%acl_smtp_data%& will still be called after this ACL and
+can reject the message overall, even if this ACL has accepted it
+for some or all recipients.
+
+PRDR may be used to support per-user content filtering.  Without it
+one must defer any recipient after the first that has a different
+content-filter configuration.  With PRDR, the RCPT-time check
+for this can be disabled when the MAIL-time $smtp_command included
+"PRDR".  Any required difference in behaviour of the main DATA-time
+ACL should however depend on the PRDR-time ACL having run, as Exim
+will avoid doing so in some situations (eg.  single-recipient mails).
+
+See also the &%prdr_enable%& global option
+and the &%hosts_try_prdr%& smtp transport option.
+
+This ACL is evaluated after &%acl_smtp_dkim%& but before &%acl_smtp_data%&.
+If the ACL is not defined, processing completes as if
+the feature was not requested by the client.
+
 .section "The QUIT ACL" "SECTQUITACL"
 .cindex "QUIT, ACL for"
 The ACL for the SMTP QUIT command is anomalous, in that the outcome of the ACL