From d53c1d2b881b39e9d8d06827d7967ad5d8111bea Mon Sep 17 00:00:00 2001
From: Alberto Bertogli <albertito@blitiri.com.ar>
Date: Sun, 25 Jul 2021 12:41:50 +0100
Subject: [PATCH] docs: Add DKIM setup instructions

This patch adds some basic instructions to the documentation on how to
set up DKIM, using the tools supported by the example hook.

It's not meant to be a full DKIM how-to, but to help someone who already
knows enough, or who is complementing it with a more general purpose
DKIM guide.
---
 docs/dkim.md | 43 ++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 40 insertions(+), 3 deletions(-)

diff --git a/docs/dkim.md b/docs/dkim.md
index a6b8655..757731b 100644
--- a/docs/dkim.md
+++ b/docs/dkim.md
@@ -7,9 +7,8 @@ mechanism.
 
 ## Signing
 
-The example hook in this repository contains an example of integration with
-[driusan/dkim](https://github.com/driusan/dkim) and
-[dkimpy](https://launchpad.net/dkimpy/), and assumes the following:
+The [example hook] includes integration with [driusan/dkim] and [dkimpy], and
+assumes the following:
 
 - The [selector](https://tools.ietf.org/html/rfc6376#section-3.1) for a domain
   can be found in the file `domains/$DOMAIN/dkim_selector`.
@@ -19,6 +18,41 @@ The example hook in this repository contains an example of integration with
 Only authenticated email will be signed.
 
 
+### Setup with [driusan/dkim]
+
+1. Install the [driusan/dkim] tools with something like the following (adjust
+   to your local environment):
+
+     ```
+     for i in dkimsign dkimverify dkimkeygen; do
+     	go get github.com/driusan/dkim/cmd/$i
+     	go install github.com/driusan/dkim/cmd/$i
+     done
+     sudo cp ~/go/bin/{dkimsign,dkimverify,dkimkeygen} /usr/local/bin
+     ```
+
+1. Generate the domain key for your domain using `dkimkeygen`.
+1. Publish the DNS record from `dns.txt`
+   ([guide](https://support.dnsimple.com/articles/dkim-record/)).
+1. Write the selector you chose to `domains/$DOMAIN/dkim_selector`.
+1. Copy `private.pem` to `/etc/chasquid/certs/$DOMAIN/dkim_privkey.pem`.
+1. Verify the setup using one of the publicly available tools, like
+   [mail-tester](https://www.mail-tester.com/spf-dkim-check).
+
+
+### Setup with [dkimpy]
+
+1. Install [dkimpy] with `apt install python3-dkim` or the equivalent for your
+   environment.
+1. Generate the domain key for your domain using `dknewkey dkim`.
+1. Publish the DNS record from `dkim.dns`
+   ([guide](https://support.dnsimple.com/articles/dkim-record/)).
+1. Write the selector you chose to `domains/$DOMAIN/dkim_selector`.
+1. Copy `dkim.key` to `/etc/chasquid/certs/$DOMAIN/dkim_privkey.pem`.
+1. Verify the setup using one of the publicly available tools, like
+   [mail-tester](https://www.mail-tester.com/spf-dkim-check).
+
+
 ## Verification
 
 Verifying signatures is technically supported as well, and can be done in the
@@ -31,3 +65,6 @@ included in the example.
 
 [chasquid]: https://blitiri.com.ar/p/chasquid
 [DKIM]: https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail
+[example hook]: https://blitiri.com.ar/git/r/chasquid/b/next/t/etc/chasquid/hooks/f=post-data.html
+[driusan/dkim]: https://github.com/driusan/dkim
+[dkimpy]: https://launchpad.net/dkimpy/