Enable operator md5 and sha1 use on certificate variables. Bug 1170

[users/jgh/exim.git] / doc / doc-docbook / spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 623ce535ae952ec466b30325c98361baf83e7aa6..3dd72e9f93b023f19e625b21bf9e3f89fd19e39f 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -8875,6 +8875,55 @@ the expansion result is an empty string.
 If the ACL returns defer the result is a forced-fail.  Otherwise the expansion fails.
 
 
 If the ACL returns defer the result is a forced-fail.  Otherwise the expansion fails.
 
 

+.new
+.vitem "&*${certextract{*&<&'field'&>&*}{*&<&'certificate'&>&*}&&&
+       {*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&"
+.cindex "expansion" "extracting cerificate fields"
+.cindex "&%certextract%&" "certificate fields"
+.cindex "certificate" "extracting fields"
+The <&'certificate'&> must be a variable of type certificate.
+The field name is expanded and used to retrive the relevant field from
+the certificate.  Supported fields are:
+.display
+&`version        `&
+&`serial_number  `&
+&`subject        `&
+&`issuer         `&
+&`notbefore      `&
+&`notafter       `&
+&`sig_algorithm  `&
+&`signature      `&
+&`subj_altname   `& tagged list
+&`ocsp_uri       `& list
+&`crl_uri        `& list
+.endd
+If the field is found,
+<&'string2'&> is expanded, and replaces the whole item;
+otherwise <&'string3'&> is used. During the expansion of <&'string2'&> the
+variable &$value$& contains the value that has been extracted. Afterwards, it
+is restored to any previous value it might have had.
+
+If {<&'string3'&>} is omitted, the item is replaced by an empty string if the
+key is not found. If {<&'string2'&>} is also omitted, the value that was
+extracted is used.
+
+Some field names take optional modifiers, appended and separated by commas.
+
+The field selectors marked as "list" above return a list,
+newline-separated by default,
+(embedded separator characters in elements are doubled).
+The separator may be changed by a modifier of
+a right angle-bracket followed immediately by the new separator.
+
+The field selectors marked as "tagged" above
+prefix each list element with a type string and an equals sign.
+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.
+
+Field values are generally presented in human-readable form.
+.wen
+

 .vitem "&*${dlfunc{*&<&'file'&>&*}{*&<&'function'&>&*}{*&<&'arg'&>&*}&&&
        {*&<&'arg'&>&*}...}*&"
 .cindex &%dlfunc%&
 .vitem "&*${dlfunc{*&<&'file'&>&*}{*&<&'function'&>&*}{*&<&'arg'&>&*}&&&
        {*&<&'arg'&>&*}...}*&"
 .cindex &%dlfunc%&


@@ -11471,7 +11520,7 @@ the space value is -1. See also the &%check_log_space%& option.
 .vitem &$lookup_dnssec_authenticated$&
 .vindex "&$lookup_dnssec_authenticated$&"
 This variable is set after a DNS lookup done by
 .vitem &$lookup_dnssec_authenticated$&
 .vindex "&$lookup_dnssec_authenticated$&"
 This variable is set after a DNS lookup done by

-either a dnslookup router or a dnsdb lookup expansion.
+a dnsdb lookup expansion, dnslookup router or smtp transport.

 It will be empty if &(DNSSEC)& was not requested,
 &"no"& if the result was not labelled as authenticated data
 and &"yes"& if it was.
 It will be empty if &(DNSSEC)& was not requested,
 &"no"& if the result was not labelled as authenticated data
 and &"yes"& if it was.


@@ -12253,6 +12302,44 @@ on an outbound SMTP connection; the meaning of
 this depends upon the TLS implementation used.
 If TLS has not been negotiated, the value will be 0.
 
 this depends upon the TLS implementation used.
 If TLS has not been negotiated, the value will be 0.
 

+.new
+.vitem &$tls_in_ourcert$&
+.vindex "&$tls_in_ourcert$&"
+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, &%md5%& or &%sha1%& operator,
+or a &%def%& condition.
+.wen
+
+.new
+.vitem &$tls_in_peercert$&
+.vindex "&$tls_in_peercert$&"
+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, &%md5%& or &%sha1%& operator,
+or a &%def%& condition.
+.wen
+
+.new
+.vitem &$tls_out_ourcert$&
+.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, &%md5%& or &%sha1%& operator,
+or a &%def%& condition.
+.wen
+
+.new
+.vitem &$tls_out_peercert$&
+.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, &%md5%& or &%sha1%& operator,
+or a &%def%& condition.
+.wen
+

 .vitem &$tls_in_certificate_verified$&
 .vindex "&$tls_in_certificate_verified$&"
 This variable is set to &"1"& if a TLS certificate was verified when the
 .vitem &$tls_in_certificate_verified$&
 .vindex "&$tls_in_certificate_verified$&"
 This variable is set to &"1"& if a TLS certificate was verified when the


@@ -17687,8 +17774,6 @@ when there is a DNS lookup error.
 DNS lookups for domains matching &%dnssec_request_domains%& will be done with
 the dnssec request bit set.
 This applies to all of the SRV, MX A6, AAAA, A lookup sequence.
 DNS lookups for domains matching &%dnssec_request_domains%& will be done with
 the dnssec request bit set.
 This applies to all of the SRV, MX A6, AAAA, A lookup sequence.

-
-See also the &$lookup_dnssec_authenticated$& variable.

 .wen
 
 
 .wen
 
 


@@ -22610,6 +22695,33 @@ See the &%search_parents%& option in chapter &<<CHAPdnslookup>>& for more
 details.
 
 
 details.
 
 

+.new
+.option dnssec_request_domains smtp "domain list&!!" unset
+.cindex "MX record" "security"
+.cindex "DNSSEC" "MX lookup"
+.cindex "security" "MX lookup"
+.cindex "DNS" "DNSSEC"
+DNS lookups for domains matching &%dnssec_request_domains%& will be done with
+the dnssec request bit set.
+This applies to all of the SRV, MX A6, AAAA, A lookup sequence.
+.wen
+
+
+
+.new
+.option dnssec_require_domains smtp "domain list&!!" unset
+.cindex "MX record" "security"
+.cindex "DNSSEC" "MX lookup"
+.cindex "security" "MX lookup"
+.cindex "DNS" "DNSSEC"
+DNS lookups for domains matching &%dnssec_request_domains%& will be done with
+the dnssec request bit set.  Any returns not having the Authenticated Data bit
+(AD bit) set wil be ignored and logged as a host-lookup failure.
+This applies to all of the SRV, MX A6, AAAA, A lookup sequence.
+.wen
+
+
+

 .option dscp smtp string&!! unset
 .cindex "DCSP" "outbound"
 This option causes the DSCP value associated with a socket to be set to one
 .option dscp smtp string&!! unset
 .cindex "DCSP" "outbound"
 This option causes the DSCP value associated with a socket to be set to one