git » chasquid » commit d53c1d2

docs: Add DKIM setup instructions

author Alberto Bertogli
2021-07-25 11:41:50 UTC
committer Alberto Bertogli
2021-07-25 13:59:37 UTC
parent 270a071c1e80e0c7612af54a51a741edb76fd849
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 +40 -3 
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/