DKIM docs WIP

1 files changed, 70 insertions, 2 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"