[pmg-devel] [PATCH pmg-docs v3 1/1] Add DKIM documentation

[Stoiko Ivanov]

Add a short section explaining DKIM and the specifics of Signing in PMG.

Additionally gen-pmg.conf.5-opts.pl was extended to create
'pmg.admin-dkim-conf-opts.adoc' for inclusion below the documentation.

Signed-off-by: Stoiko Ivanov <s.ivanov at proxmox.com>
---
 asciidoc/asciidoc-pmg.conf |  1 +
 gen-pmg.conf.5-opts.pl     |  6 ++++
 pmgconfig.adoc             | 56 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 63 insertions(+)

diff --git a/asciidoc/asciidoc-pmg.conf b/asciidoc/asciidoc-pmg.conf
index df15987..46838c0 100644
--- a/asciidoc/asciidoc-pmg.conf
+++ b/asciidoc/asciidoc-pmg.conf
@@ -16,6 +16,7 @@ systemd=https://www.freedesktop.org/wiki/Software/systemd/[systemd]
 clamav=https://www.clamav.net[ClamAV(R)]
 debian=https://www.debian.org[Debian]
 tts=http://www.template-toolkit.org[Template Toolkit]
+dkim_rfc=https://tools.ietf.org/html/rfc6376[RFC 6376]
 ifndef::docinfo1[]
 author=Proxmox Server Solutions Gmbh
 email=support at proxmox.com
diff --git a/gen-pmg.conf.5-opts.pl b/gen-pmg.conf.5-opts.pl
index f689ec0..3a80698 100755
--- a/gen-pmg.conf.5-opts.pl
+++ b/gen-pmg.conf.5-opts.pl
@@ -57,6 +57,12 @@ my $key_groups = {
 	    smarthost => 1,
 	    smarthostport => 1,
 	}],
+    'admin-dkim' => [
+	'admin' , {
+	    dkim_selector => 1,
+	    dkim_sign => 1,
+	    dkim_sign_all_mail => 1,
+	}],
 };
 
 if (1) {
diff --git a/pmgconfig.adoc b/pmgconfig.adoc
index 384fa2b..ee92aad 100644
--- a/pmgconfig.adoc
+++ b/pmgconfig.adoc
@@ -362,6 +362,62 @@ using the following configuration keys:
 include::pmg.mail-tls-conf-opts.adoc[]
 
 
+[[pmgconfig_mailproxy_dkim]]
+DKIM Signing
+~~~~~~~~~~~~
+
+DomainKeys Identified Mail (DKIM) Signatures (see {dkim_rfc}) is a method to
+cryptographically authenticate a mail as originating from a particular domain.
+Before sending the mail a hash over certain header fields and the body is
+computed, signed with a private key and added in the `DKIM-Signature` header of
+the mail. The 'selector' (a short identifier chosen by you, used to identify
+which system and private key were used for signing) is also included in the
+`DKIM-Signature` header.
+
+The verification is done by the receiver: The public key is fetched
+via DNS TXT lookup for `yourselector._domainkey.yourdomain.example` and used
+for verifying the hash. You can publish multiple selectors for your domain,
+each use by a system which sends e-mail from your domain, without the need to
+share the private key.
+
+{pmg} verifies DKIM Signatures for inbound mail in the Spam Filter by default.
+
+Additionally it supports conditionally signing outbound mail if configured.
+It uses one private key and selector per PMG deployment (all nodes in a cluster
+use the same key). The key has a minimal size of 1024 bits and rsa-sha256 is
+used as signing algorithm.
+
+The headers included in the signature are taken from the list of
+`Mail::DKIM::Signer`. Additionally `Content-Type` (if present), `From`, `To`,
+`CC`, `Reply-To` and `Subject` get oversigned.
+
+You can either sign all mails received on the internal port using the domain of
+the envelope sender address or create a list of domains, for which e-mails
+should be signed, defaulting to the list of relay domains.
+
+
+Selector::
+
+The selector used for signing the mail. The private key used for signing is
+saved under `/etc/pmg/yourselector.private`. You can display the DNS TXT
+record which you need to add to all domains signed by {pmg} by clicking on the
+'View DNS Record' Button.
+
+Sign Outbound Mail::
+
+Controls whether outbound mail should get DKIM signed.
+
+Ignore Sender Domain::
+
+Controls whether all outbound mail should get signed or only mails from domains
+listed in `/etc/pmg/dkim/domains` if it exists and `/etc/pmg/domains` otherwise.
+
+Those settings are saved to subsection 'admin' in `/etc/pmg/pmg.conf`,
+using the following configuration keys:
+
+include::pmg.admin-dkim-conf-opts.adoc[]
+
+
 Whitelist
 ~~~~~~~~~
 
-- 
2.20.1