Docs: typo
[users/jgh/exim.git] / doc / doc-txt / experimental-spec.txt
index 373d9dc4c583b016fcefb6939ffaa8dfe7b6987a..2569ad3af2b76f7d0ea371a8b00703805932fed5 100644 (file)
@@ -292,10 +292,11 @@ These four steps are explained in more details below.
 
 
 
-SRS (Sender Rewriting Scheme) Support
+SRS (Sender Rewriting Scheme) Support (using libsrs_alt)
 --------------------------------------------------------------
+See also below, for an alternative native support implementation.
 
-Exiscan  currently  includes SRS  support  via Miles  Wilton's
+Exim  currently  includes SRS  support  via Miles  Wilton's
 libsrs_alt library. The current version of the supported
 library is 0.5, there are reports of 1.0 working.
 
@@ -343,6 +344,76 @@ For configuration information see https://github.com/Exim/exim/wiki/SRS .
 
 
 
+SRS (Sender Rewriting Scheme) Support (native)
+--------------------------------------------------------------
+This is less full-featured than the libsrs_alt version above.
+
+The Exim build needs to be done with this in Local/Makefile:
+EXPERIMENTAL_SRS_NATIVE=yes
+
+The following are provided:
+- an expansion item "srs_encode"
+  This takes three arguments:
+  - a site SRS secret
+  - the return_path
+  - the pre-forwarding domain
+
+- an expansion condition "inbound_srs"
+  This takes two arguments: the local_part to check, and a site SRS secret.
+  If the secret is zero-length, only the pattern of the local_part is checked.
+  The $srs_recipient variable is set as a side-effect.
+
+- an expansion variable $srs_recipient
+  This gets the original return_path encoded in the SRS'd local_part
+
+- predefined macros _HAVE_SRS and _HAVE_NATIVE_SRS
+
+Sample usage:
+
+  #macro
+  SRS_SECRET = <pick something unique for your site for this>
+  
+  #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}}
+
+
+
+
 DCC Support
 --------------------------------------------------------------
 Distributed Checksum Clearinghouse; http://www.rhyolite.com/dcc/
@@ -571,6 +642,9 @@ ARC support
 Specification: https://tools.ietf.org/html/draft-ietf-dmarc-arc-protocol-11
 Note that this is not an RFC yet, so may change.
 
+[RFC 8617 was published 2019/06.  Draft 11 was 2018/01.  A review of the
+changes has not yet been done]
+
 ARC is intended to support the utility of SPF and DKIM in the presence of
 intermediaries in the transmission path - forwarders and mailinglists -
 by establishing a cryptographically-signed chain in headers.
@@ -579,10 +653,18 @@ Normally one would only bother doing ARC-signing when functioning as
 an intermediary.  One might do verify for local destinations.
 
 ARC uses the notion of a "ADministrative Management Domain" (ADMD).
-Described in RFC 5598 (section 2.3), this is essentially the set of
-mail-handling systems that the mail transits.  A label should be chosen to
-identify the ADMD.  Messages should be ARC-verified on entry to the ADMD,
-and ARC-signed on exit from it.
+Described in RFC 5598 (section 2.3), this is essentially a set of
+mail-handling systems that mail transits that are all under the control
+of one organisation.  A label should be chosen to identify the ADMD.
+Messages should be ARC-verified on entry to the ADMD, and ARC-signed on exit
+from it.
+
+
+Building with ARC Support
+--
+Enable using EXPERIMENTAL_ARC=yes in your Local/Makefile.
+You must also have DKIM present (not disabled), and you very likely
+want to have SPF enabled.
 
 
 Verification