DKIM docs WIP

3 files changed, 77 insertions, 407 deletions

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index ec631523b..7b5d5c44a 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -1,4 +1,4 @@
-. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.49 2009/01/02 16:42:31 nm4 Exp $
+. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.50 2009/06/11 14:07:57 tom Exp $
 .
 . /////////////////////////////////////////////////////////////////////////////
 . This is the primary source of the Exim Manual. It is an xfpt document that is
@@ -34267,13 +34267,81 @@ unqualified domain &'foundation'&.
 .ecindex IIDforspo2
 .ecindex IIDforspo3
 
+. ////////////////////////////////////////////////////////////////////////////
+. ////////////////////////////////////////////////////////////////////////////
+
+.chapter "Support for DKIM (DomainKeys Identified Mail) - RFC4871" "CHID12" &&&
+         "DKIM Support"
+.cindex "DKIM"
+
+Since version 4.70, DKIM support is compiled into Exim by default. It can be
+disabled by setting DISABLE_DKIM=yes in Local/Makefile.
+
+Exim's DKIM implementation allows to
+.olist
+Sign outgoing messages: This function is implemented in the SMTP transport.
+It can co-exist with all other Exim features, including transport filters.
+.next
+Verify signatures in incoming messages: This is implemented by an additional
+ACL (acl_smtp_dkim), which can be called several times per message, with
+different signature context.
+.endlist
+
+.section "Signing outgoing messages" "SECID513"
+.cindex "DKIM" "signing"
+
+Signing is implemented by setting private options on the SMTP transport.
+These options take (expandable) strings as arguments.
+
+.vitem &%dkim_domain = <expanded string> [MANDATORY]%&
+The domain you want to sign with. The result of this expanded
+option is put into the $dkim_domain expansion variable.
+
+.vitem &%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.
+
+.vitem &%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
+.ulist
+be a valid RSA private key in ASCII armor, including line breaks.
+.next
+start with a slash, in which case it is treated as a file that contains
+the private key.
+.next
+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.
+.endlist
+
+.vitem &%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.
+
+.vitem &%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.
+
+.vitem &%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 headers recommended in RFC4871 will be used.
+
 
 
 
 . ////////////////////////////////////////////////////////////////////////////
 . ////////////////////////////////////////////////////////////////////////////
 
-.chapter "Adding new drivers or lookup types" "CHID12" &&&
+.chapter "Adding new drivers or lookup types" "CHID13" &&&
          "Adding drivers or lookups"
 .cindex "adding drivers"
 .cindex "new drivers, adding"
diff --git a/doc/doc-txt/ChangeLog b/doc/doc-txt/ChangeLog
index 7b1e85ef4..a3c09f801 100644
--- a/doc/doc-txt/ChangeLog
+++ b/doc/doc-txt/ChangeLog
@@ -1,4 +1,4 @@
-$Cambridge: exim/doc/doc-txt/ChangeLog,v 1.562 2009/01/02 17:22:12 nm4 Exp $
+$Cambridge: exim/doc/doc-txt/ChangeLog,v 1.563 2009/06/11 14:07:57 tom Exp $
 
 Change log file for Exim from version 4.21
 -------------------------------------------
@@ -94,6 +94,8 @@ NM/13 Bugzilla 590: Correct handling of Resent-Date headers.
 NM/14 Bugzilla 614: Added timeout setting to transport filter.
       Patch provided by Dean Brooks
 
+TK/05 Add native DKIM support (does not depend on external libraries).
+
 
 Exim version 4.69
 -----------------
diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt
index 4175173c3..be871d2b9 100644
--- a/doc/doc-txt/experimental-spec.txt
+++ b/doc/doc-txt/experimental-spec.txt
@@ -1,4 +1,4 @@
-$Cambridge: exim/doc/doc-txt/experimental-spec.txt,v 1.11 2008/02/12 12:52:51 nm4 Exp $
+$Cambridge: exim/doc/doc-txt/experimental-spec.txt,v 1.12 2009/06/11 14:07:57 tom Exp $
 
 From time to time, experimental features may be added to Exim.
 While a feature  is experimental, there  will be a  build-time
@@ -8,407 +8,7 @@ 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
---------------------------------------------------------------
-
-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>
-
-    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:
-
-    signsall        The target domain signs all outgoing email.
-    testing         The target domain is currently testing DK.
-
-
-  dk_domain_source = <colon separated list of keywords>
-
-    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:
-
-    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.
-
-
-
-1.2.) DK verification expansion variables
-
-  $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,7 +294,7 @@ 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://www.openspf.org. This
@@ -844,7 +444,7 @@ 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