Added docs for DomainKeys
authorTom Kistner <tom@duncanthrax.net>
Tue, 8 Mar 2005 15:33:05 +0000 (15:33 +0000)
committerTom Kistner <tom@duncanthrax.net>
Tue, 8 Mar 2005 15:33:05 +0000 (15:33 +0000)
doc/doc-txt/experimental-spec.txt

index 145fc42..682b60b 100644 (file)
-$Cambridge: exim/doc/doc-txt/experimental-spec.txt,v 1.1 2005/01/11 10:51:15 ph10 Exp $
+$Cambridge: exim/doc/doc-txt/experimental-spec.txt,v 1.2 2005/03/08 15:33:05 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
-order to include the feature. This file contains information
-about experimenatal features, all of which are unstable and
+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
+order to include the  feature. This file contains  information
+about experimenatal  features, all  of which  are unstable and
 liable to incompatibile change.
 
 
-1. Brighmail AntiSpam (BMI) suppport
+
+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. Brighmail AntiSpam (BMI) suppport
 --------------------------------------------------------------
 
 Brightmail  AntiSpam  is  a  commercial  package.  Please  see
@@ -294,7 +543,7 @@ These four steps are explained in more details below.
   
 
   
-2. Sender Policy Framework (SPF) support
+3. Sender Policy Framework (SPF) support
 --------------------------------------------------------------
 
 To learn  more  about  SPF, visit   http://spf.pobox.com. This
@@ -409,7 +658,7 @@ variables.
   
   
 
-3. SRS (Sender Rewriting Scheme) Support
+4. SRS (Sender Rewriting Scheme) Support
 --------------------------------------------------------------
 
 Exiscan  currently  includes SRS  support  via Miles  Wilton's