Add driusan/dkim integration example and tests

This patch adds DKIM signing using https://github.com/driusan/dkim tools
to the example hook.

It also adds an optional integration test to exercise signing and
verification, and corresponding documentation.

test/util/smtpc.py

@@ -5,6 +5,7 @@
 import argparse
 import email.parser
 import email.policy
+import re
 import smtplib
 import sys
 
@@ -16,15 +17,27 @@ args = ap.parse_args()
 
 # Parse the email using the "default" policy, which is not really the default.
 # If unspecified, compat32 is used, which does not support UTF8.
-msg = email.parser.Parser(policy=email.policy.default).parse(sys.stdin)
+rawmsg = sys.stdin.buffer.read()
+msg = email.parser.Parser(policy=email.policy.default).parsestr(
+        rawmsg.decode('utf8'))
 
 s = smtplib.SMTP(args.server)
 s.starttls()
-s.login(args.user, args.password)
+if args.user:
+    s.login(args.user, args.password)
 
-# Note this does NOT support non-ascii message payloads transparently (headers
-# are ok).
-s.send_message(msg)
+# Send the raw message, not parsed, because the parser does not handle some
+# corner cases that well (for example, DKIM-Signature headers get mime-encoded
+# incorrectly).
+# Replace \n with \r\n, which is normally done by the library, but will not do
+# it in this case because we are giving it bytes and not a string (which we
+# cannot do because it tries to incorrectly escape the headers).
+crlfmsg = re.sub(br'(?:\r\n|\n|\r(?!\n))', b"\r\n", rawmsg)
+
+s.sendmail(
+        from_addr=msg['from'], to_addrs=msg.get_all('to'),
+        msg=crlfmsg,
+        mail_options=['SMTPUTF8'])
 s.quit()