ChangeLog update for NTLM/server_set_id
[users/jgh/exim.git] / doc / doc-txt / experimental-spec.txt
index cff937f7fb0815d69bd43c5bf0a1a3c8d999b70e..5dd6832b1f6382cc71aa32f4f0736e99d5a161e8 100644 (file)
@@ -1,5 +1,3 @@
-$Cambridge: exim/doc/doc-txt/experimental-spec.txt,v 1.9 2007/10/04 13:21:06 tom Exp $
-
 From time to time, experimental features may be added to Exim.
 While a feature  is experimental, there  will be a  build-time
 option whose name starts  "EXPERIMENTAL_" that must be  set in
@@ -8,407 +6,67 @@ about experimenatal  features, all  of which  are unstable and
 liable to incompatibile change.
 
 
-0. DKIM support
---------------------------------------------------------------
-
-DKIM support is implemented via libdkim. A compatible version
-is available here:
-
-http://duncanthrax.net/exim-experimental/libdkim-1.0.15-tk.tar.gz
-
-Build the lib according to the instructions in the enclosed
-INSTALL file.
-
-To build Exim with DKIM support, specify this in Local/Makefile:
-
-EXPERIMENTAL_DKIM=yes
-CFLAGS  += -I/home/tom/libdkim/include
-LDFLAGS += -ldkim -lssl -lstdc++ -L/home/tom/libdkim/lib
-
-Remember to tweak  the CFLAGS and  LDFLAGS lines to  match the
-location of the libdomainkeys includes and lib on your system.
-
-The current experimental implementation supports two independent
-functions:
-
-o Validate incoming DKIM-signed email.
-o Sign outgoing email with DKIM.
-
-The former is implemented in the ACLs for SMTP, the latter  as
-an extension to the SMTP transport. That means both facilities
-are limited to SMTP I/O.
-
-
-1) Validate incoming email
-
-Incoming messages are fed to the DKIM validation process as they
-are received "on  the wire". This happens synchronously to Exim's
-buffering of the message in the spool.
-
-You must set "control = dkim_verify" in one of the ACLs preceding
-DATA (you will typically use acl_smtp_rcpt), at a point where
-non-local, non-relay, non-submission mail is processed. If that
-control flag is not set, the message will NOT be verified.
-
-Example:
-
-warn log_message = Feeding message to DKIM validator.
-     control = dk_verify
-
-You can then check for DKIM signatures in the ACL after data
-(acl_smtp_data), using the 'dkim' query-style lookup type. The
-query string should be a domain or DKIM identity:
-
-${lookup dkim{domain.example}}
-
-Such a lookup will yield one of the following strings:
-
-unverified: Exim did not (yet) verify the eventual DKIM
-            signatures in this message. This may happen
-            if a) You did not use control=dkim_verify
-            or b) You are using the lookup before
-            the DATA ACL.
-
-unsigned:   The message does not have a signature from
-            the specified domain.
-
-good:       The message has a signature from the specified
-            domain, and it verified successfully.
-
-bad:        The message has a signature from the specified
-            domain, but it did not verify.
-
-defer:      A temporary DNS problem was encountered while
-            trying to verify the signature.
-
-
-
-2) Sign outgoing email with DKIM
-
-Outgoing messages are  signed just before  Exim puts them  "on
-the wire".  The only  thing that happens after DKIM signing is
-eventual TLS encryption.
-
-Signing is implemented by setting private options on the  SMTP
-transport.  These   options  take   (expandable)  strings   as
-arguments.
-
-  dkim_domain = <expanded string> [MANDATORY]
-
-    The domain you want to sign with. Should optimally match
-    the domain in the "From:" header of the message, but
-    does not necessarily have to. The result of this expanded
-    option is put into the $dkim_domain expansion variable.
-
-  dkim_selector = <expanded string> [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  should be  used in  the dkim_private_key
-    option along with $dkim_domain.
-
-  dkim_private_key = <expanded string> [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
-
-      o be a valid RSA private key in ASCII armor, including
-        line breaks.
-      o start with a slash, in which case it is treated as
-        a file that contains the private key.
-      o 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.
-
-  dkim_canon = <expanded string> [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 support using the same canonicalization method for
-    both headers and body.
-
-  dkim_strict = <expanded string> [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.
-
-  dkim_sign_headers = <expanded string> [OPTIONAL]
-
-    When set, this option must expand to (or be specified as)
-    a colon-separated list of header names. These headers will
-    be included in the message signature. When unspecified,
-    the recommended headers will be used. Currently, these
-    are:
-
-    from:sender:reply-to:subject:date:
-    message-id:to:cc:mime-version:content-type:
-    content-transfer-encoding:content-id:
-    content-description:resent-date:resent-from:
-    resent-sender:resent-to:resent-cc:resent-message-id:
-    in-reply-to:references:
-    list-id:list-help:list-unsubscribe:
-    list-subscribe:list-post:list-owner:list-archive
-
-
-
-
-1. Yahoo DomainKeys support
+OCSP Stapling support
 --------------------------------------------------------------
 
-DomainKeys  (DK)  support  is   built  into  Exim  using   the
-"libdomainkeys"  reference   library  implementation.   It  is
-available at
-
-http://domainkeys.sf.net
-
-You must build  this library on  your system and  compile Exim
-against it. To build Exim with DK support, add these lines  to
-your Local/Makefile:
-
-EXPERIMENTAL_DOMAINKEYS=yes
-CFLAGS  += -I/home/tom/exim-cvs/extra/libdomainkeys
-LDFLAGS += -ldomainkeys -L/home/tom/exim-cvs/extra/libdomainkeys
-
-Remember to tweak  the CFLAGS and  LDFLAGS lines to  match the
-location of the libdomainkeys includes and lib on your system.
-
-The   current   experimental   implementation   supports   two
-independent functions:
-
-o Validate incoming DK-signed email.
-o Sign outgoing email with DK.
-
-The former is implemented in the ACLs for SMTP, the latter  as
-an extension to the SMTP transport. That means both facilities
-are limited to SMTP I/O.
-
-
-
-1) Validate incoming email
-
-Incoming messages are fed to the DK validation process as they
-are  received "on  the wire".  This happens  synchronously to
-Exim's buffering of the message in the spool.
-
-You  must  set  "control  =  dk_verify"  in  one  of  the ACLs
-preceding DATA  (you will  typically use  acl_smtp_rcpt), at a
-point  where  non-local,  non-relay,  non-submission  mail  is
-processed. If that control flag  is not set, the message  will
-NOT be verified.
-
-Example:
-
-warn log_message = Feeding message to DK validator.
-     control = dk_verify
-
-You can check for the outcome of the DK check in the ACL after
-data (acl_smtp_data), using a number of ACL conditions  and/or
-expansion variables.
-
-
-
-1.1.) DK ACL conditions
-
-  dk_sender_domains = <domain list>
-
-    This   condition   takes  a   domainlist  as argument  and
-    succeeds if the domain that DK has  been verifying  for is
-    found in the list.
-
-
-  dk_senders = <address list>
-
-    This  condition  takes  an  addresslist  as argument   and
-    succeeds  if  the address  that DK has been  verifying for
-    is  found in the list.
-
-
-  dk_sender_local_parts = <local part list>
-
-    This  condition  takes   a local_part  list   as  argument
-    and  succeeds   if  the   domain   that    DK   has   been
-    verifying  for is found in the list.
-
-
-  dk_status = <colon separated list of keywords>
-
-    This condition takes a  list of keywords as  argument, and
-    succeeds if one of the listed keywords matches the outcome
-    of the DK check. The available keywords are:
-
-    good            DK check succeeded, mail is verified.
-    bad             DK check failed.
-    no signature    Mail is not signed with DK.
-    no key          Public key missing in target domain DNS.
-    bad format      Public key available, but unuseable.
-    non-participant Target domain states not to participate in DK.
-    revoked         The signing key has been revoked by the domain.
-
-
-  dk_policy = <colon separated list of keywords>
+X509 PKI certificates expire and can be revoked; to handle this, the
+clients need some way to determine if a particular certificate, from a
+particular Certificate Authority (CA), is still valid.  There are three
+main ways to do so.
 
-    This condition takes a  list of keywords as  argument, and
-    succeeds if one of the listed keywords matches the  policy
-    announced  by the  target domain.  The available  keywords
-    are:
+The simplest way is to serve up a Certificate Revocation List (CRL) with
+an ordinary web-server, regenerating the CRL before it expires.  The
+downside is that clients have to periodically re-download a potentially
+huge file from every certificate authority it knows of.
 
-    signsall        The target domain signs all outgoing email.
-    testing         The target domain is currently testing DK.
+The way with most moving parts at query time is Online Certificate
+Status Protocol (OCSP), where the client verifies the certificate
+against an OCSP server run by the CA.  This lets the CA track all
+usage of the certs.  This requires running software with access to the
+private key of the CA, to sign the responses to the OCSP queries.  OCSP
+is based on HTTP and can be proxied accordingly.
 
+The only widespread OCSP server implementation (known to this writer)
+comes as part of OpenSSL and aborts on an invalid request, such as
+connecting to the port and then disconnecting.  This requires
+re-entering the passphrase each time some random client does this.
 
-  dk_domain_source = <colon separated list of keywords>
+The third way is OCSP Stapling; in this, the server using a certificate
+issued by the CA periodically requests an OCSP proof of validity from
+the OCSP server, then serves it up inline as part of the TLS
+negotiation.   This approach adds no extra round trips, does not let the
+CA track users, scales well with number of certs issued by the CA and is
+resilient to temporary OCSP server failures, as long as the server
+starts retrying to fetch an OCSP proof some time before its current
+proof expires.  The downside is that it requires server support.
 
-    This condition takes a  list of keywords as  argument, and
-    succeeds  if  one  of  the  listed  keywords  matches  the
-    location where DK found the sender domain it verified for.
-    The available keywords are:
+If Exim is built with EXPERIMENTAL_OCSP and it was built with OpenSSL,
+then it gains one new option: "tls_ocsp_file".
 
-    from            The domain came from the "From:" header.
-    sender          The domain came from the "Sender:" header.
-    none            DK was unable to find the responsible domain.
+The file specified therein is expected to be in DER format, and contain
+an OCSP proof.  Exim will serve it as part of the TLS handshake.  This
+option will be re-expanded for SNI, if the tls_certificate option
+contains $tls_sni, as per other TLS options.
 
+Exim does not at this time implement any support for fetching a new OCSP
+proof.  The burden is on the administrator to handle this, outside of
+Exim.  The file specified should be replaced atomically, so that the
+contents are always valid.  Exim will expand the "tls_ocsp_file" option
+on each connection, so a new file will be handled transparently on the
+next connection.
 
+Exim will check for a valid next update timestamp in the OCSP proof;
+if not present, or if the proof has expired, it will be ignored.
 
-1.2.) DK verification expansion variables
+At this point in time, we're gathering feedback on use, to determine if
+it's worth adding complexity to the Exim daemon to periodically re-fetch
+OCSP files and somehow handling multiple files.  There is no client support
+for OCSP in Exim, this is feature expected to be used by mail clients.
 
-  $dk_sender_domain
 
-    Contains the domain that DK has verified for.
 
 
-  $dk_sender
-
-    Contains the address that DK has verified for.
-
-
-  $dk_sender_local_part
-
-    Contains the local part that DK has verified for.
-
-
-  $dk_sender_source
-
-    Contains the "source" of the above three variables, one of
-
-      "from"    The address came from the "From:" header.
-      "sender"  The address came from the "Sender:" header.
-
-    When DK was unable to find a valid address, this variable
-    is "0".
-
-
-  $dk_signsall
-
-    Is "1" if the target domain signs all outgoing email,
-    "0" otherwise.
-
-
-  $dk_testing
-
-    Is "1" if the target domain is testing DK, "0" otherwise.
-
-
-  $dk_is_signed
-
-    Is "1" if the message is signed, "0" otherwise.
-
-
-  $dk_status
-
-    Contains the outcome of the DK check as a string, commonly
-    used to add a "DomainKey-Status:" header to messages. Will
-    contain one of:
-
-    good            DK check succeeded, mail is verified.
-    bad             DK check failed.
-    no signature    Mail is not signed with DK.
-    no key          Public key missing in target domain DNS.
-    bad format      Public key available, but unuseable.
-    non-participant Target domain states not to participate in DK.
-    revoked         The signing key has been revoked by the domain.
-
-
-  $dk_result
-
-    Contains a  human-readable result  of the  DK check,  more
-    verbose than $dk_status. Useful for logging purposes.
-
-
-
-2) Sign outgoing email with DK
-
-Outgoing messages are  signed just before  Exim puts them  "on
-the wire".  The only  thing that  happens after  DK signing is
-eventual TLS encryption.
-
-Signing is implemented by setting private options on the  SMTP
-transport.  These   options  take   (expandable)  strings   as
-arguments.  The  most  important  variable  to  use  in  these
-expansions is $dk_domain. It contains the domain that DK wants
-to sign for.
-
-
-  dk_selector = <expanded string> [MANDATORY]
-
-    This  sets  the  key  selector  string.  You  can  use the
-    $dk_domain  expansion  variable  to  look  up  a  matching
-    selector.  The result  is put  in the  expansion  variable
-    $dk_selector which  should be  used in  the dk_private_key
-    option along with $dk_domain.
-
-
-  dk_private_key = <expanded string> [MANDATORY]
-
-    This  sets the  private key  to use.  You SHOULD  use  the
-    $dk_domain   and  $dk_selector   expansion  variables   to
-    determine the private key to use. The result can either
-
-      o be a valid RSA private key in ASCII armor, including
-        line breaks.
-      o start with a slash, in which case it is treated as
-        a file that contains the private key.
-      o 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 dk_strict is set.
-
-
-  dk_canon = <expanded string> [OPTIONAL]
-
-    This  option sets  the canonicalization  method used  when
-    signing a  message. The  DK draft  currently supports  two
-    methods:  "simple"  and "nofws".  The  option defaults  to
-    "simple" when unset.
-
-
-  dk_strict = <expanded string> [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  and  should use  the  $dk_domain   and   $dk_selector
-    expansion  variables here.
-
-
-  dk_domain = <expanded string> [NOT RECOMMENDED]
-
-    This  option overrides  DKs autodetection  of the  signing
-    domain. You should only use  this option if you know  what
-    you are doing. The result of the string expansion is  also
-    put in $dk_domain.
-
-
-
-
-2. Brightmail AntiSpam (BMI) suppport
+Brightmail AntiSpam (BMI) suppport
 --------------------------------------------------------------
 
 Brightmail  AntiSpam  is  a  commercial  package.  Please  see
@@ -694,10 +352,10 @@ These four steps are explained in more details below.
 
 
 
-3. Sender Policy Framework (SPF) support
+Sender Policy Framework (SPF) support
 --------------------------------------------------------------
 
-To learn  more  about  SPF, visit   http://spf.pobox.com. This
+To learn  more  about  SPF, visit   http://www.openspf.org. This
 document does   not explain  the SPF  fundamentals, you should
 read and understand the implications of deploying SPF on  your
 system before doing so.
@@ -761,11 +419,12 @@ the SPF check, the condition  succeeds. If none of the  listed
 strings matches the  outcome of the  SPF check, the  condition
 fails.
 
-Here is a simple example to fail forgery attempts from domains
-that publish SPF records:
+Here is an example to fail forgery attempts from domains that
+publish SPF records:
 
 /* -----------------
-deny message = $sender_host_address is not allowed to send mail from $sender_address_domain
+deny message = $sender_host_address is not allowed to send mail from ${if def:sender_address_domain {$sender_address_domain}{$sender_helo_name}}.  \
+              Please see http://www.openspf.org/Why?scope=${if def:sender_address_domain {mfrom}{helo}};identity=${if def:sender_address_domain {$sender_address}{$sender_helo_name}};ip=$sender_host_address
      spf = fail
 --------------------- */
 
@@ -798,6 +457,9 @@ variables.
   draft, this header must be added at the top of the header
   list. Please see section 10 on how you can do this.
 
+  Note: in case of "Best-guess" (see below), the convention is
+  to put this string in a header called X-SPF-Guess: instead.
+
   $spf_result
   This contains the outcome of the SPF check in string form,
   one of pass, fail, softfail, none, neutral, err_perm or
@@ -807,9 +469,40 @@ variables.
   This contains a string that can be used in a SMTP response
   to the calling party. Useful for "fail".
 
+In addition to SPF, you can also perform checks for so-called
+"Best-guess".  Strictly speaking, "Best-guess" is not standard
+SPF, but it is supported by the same framework that enables SPF
+capability.  Refer to http://www.openspf.org/FAQ/Best_guess_record
+for a description of what it means.
+
+To access this feature, simply use the spf_guess condition in place
+of the spf one.  For example:
+
+/* -----------------
+deny message = $sender_host_address doesn't look trustworthy to me
+     spf_guess = fail
+--------------------- */
+
+In case you decide to reject messages based on this check, you
+should note that although it uses the same framework, "Best-guess"
+is NOT SPF, and therefore you should not mention SPF at all in your
+reject message.
+
+When the spf_guess condition has run, it sets up the same expansion
+variables as when spf condition is run, described above.
+
+Additionally, since Best-guess is not standarized, you may redefine
+what "Best-guess" means to you by redefining spf_guess variable in
+global config.  For example, the following:
+
+/* -----------------
+spf_guess = v=spf1 a/16 mx/16 ptr ?all
+--------------------- */
+
+would relax host matching rules to a broader network range.
 
 
-4. SRS (Sender Rewriting Scheme) Support
+SRS (Sender Rewriting Scheme) Support
 --------------------------------------------------------------
 
 Exiscan  currently  includes SRS  support  via Miles  Wilton's
@@ -828,6 +521,60 @@ EXPERIMENTAL_SRS=yes
 in your Local/Makefile.
 
 
+DCC Support
+--------------------------------------------------------------
+
+*) Building exim
+
+In order to build exim with DCC support add
+
+EXPERIMENTAL_DCC=yes
+
+to your Makefile. (Re-)build/install exim. exim -d should show
+EXPERIMENTAL_DCC under "Support for".
+
+
+*) Configuration
+
+In the main section of exim.cf add at least
+  dccifd_address = /usr/local/dcc/var/dccifd
+or
+  dccifd_address = <ip> <port>
+
+In the DATA ACL you can use the new condition
+        dcc = *
+
+After that "$dcc_header" contains the X-DCC-Header.
+
+Returnvalues are:
+  fail    for overall "R", "G" from dccifd
+  defer   for overall "T" from dccifd
+  accept  for overall "A", "S" from dccifd
+
+dcc = */defer_ok works as for spamd.
+
+The "$dcc_result" variable contains the overall result from DCC
+answer.  There will an X-DCC: header added to the mail.
+
+Usually you'll use
+  defer   !dcc = *
+to greylist with DCC.
+
+If you set, in the main section,
+  dcc_direct_add_header = true
+then the dcc header will be added "in deep" and if the spool
+file was already written it gets removed. This forces Exim to
+write it again if needed.  This helps to get the DCC Header
+through to eg. SpamAssassin.
+
+If you want to pass even more headers in the middle of the
+DATA stage you can set
+  $acl_m_dcc_add_header
+to tell the DCC routines add more information; eg, you might set
+this to some results from ClamAV.  Be careful.  Header syntax is
+not checked and is added "as is".
+
+
 --------------------------------------------------------------
 End of file
 --------------------------------------------------------------