maddy

  1# DKIM signing
  2
  3modify.dkim module is a modifier that signs messages using DKIM
  4protocol (RFC 6376).
  5
  6Each configuration block specifies a single selector
  7and one or more domains.
  8
  9A key will be generated or read for each domain, the key to use
 10for each message will be selected based on the SMTP envelope sender. Exception
 11for that is that for domain-less postmaster address and null address, the
 12key for the first domain will be used. If domain in envelope sender
 13does not match any of loaded keys, message will not be signed.
 14Additionally, for each messages From header is checked to 
 15match MAIL FROM and authorization identity (username sender is logged in as).
 16This can be controlled using require_sender_match directive.
 17
 18Generated private keys are stored in unencrypted PKCS#8 format
 19in state_directory/dkim_keys (`/var/lib/maddy/dkim_keys`).
 20In the same directory .dns files are generated that contain
 21public key for each domain formatted in the form of a DNS record.
 22
 23## Arguments
 24
 25domains and selector can be specified in arguments, so actual modify.dkim use can
 26be shortened to the following:
 27
 28```
 29modify {
 30    dkim example.org selector
 31}
 32```
 33
 34## Configuration directives
 35
 36```
 37modify.dkim {
 38    debug no
 39    domains example.org example.com
 40    selector default
 41    key_path dkim-keys/{domain}-{selector}.key
 42    oversign_fields ...
 43    sign_fields ...
 44    header_canon relaxed
 45    body_canon relaxed
 46    sig_expiry 120h # 5 days
 47    hash sha256
 48    newkey_algo rsa2048
 49}
 50```
 51
 52### debug _boolean_
 53Default: global directive value
 54
 55Enable verbose logging.
 56
 57---
 58
 59### domains _string-list_
 60**Required**. <br>
 61Default: not specified
 62
 63
 64ADministrative Management Domains (ADMDs) taking responsibility for messages.
 65
 66Should be specified either as a directive or as an argument.
 67
 68---
 69
 70### selector _string_
 71**Required**. <br>
 72Default: not specified
 73
 74Identifier of used key within the ADMD.
 75Should be specified either as a directive or as an argument.
 76
 77---
 78
 79### key_path _string_
 80Default: `dkim_keys/{domain}_{selector}.key`
 81
 82Path to private key. It should be in PKCS#8 format wrapped in PAM encoding.
 83If key does not exist, it will be generated using algorithm specified
 84in newkey_algo.
 85
 86Placeholders '{domain}' and '{selector}' will be replaced with corresponding
 87values from domain and selector directives.
 88
 89Additionally, keys in PKCS#1 ("RSA PRIVATE KEY") and
 90RFC 5915 ("EC PRIVATE KEY") can be read by modify.dkim. Note, however that
 91newly generated keys are always in PKCS#8.
 92
 93---
 94
 95### oversign_fields _list..._
 96Default: see below
 97
 98Header fields that should be signed n+1 times where n is times they are
 99present in the message. This makes it impossible to replace field
100value by prepending another field with the same name to the message.
101
102Fields specified here don't have to be also specified in `sign_fields`.
103
104Default set of oversigned fields:
105
106- Subject
107- To
108- From
109- Date
110- MIME-Version
111- Content-Type
112- Content-Transfer-Encoding
113- Reply-To
114- Message-Id
115- References
116- Autocrypt
117- Openpgp
118
119---
120
121### sign_fields _list..._
122Default: see below
123
124Header fields that should be signed n times where n is times they are
125present in the message. For these fields, additional values can be prepended
126by intermediate relays, but existing values can't be changed.
127
128Default set of signed fields:
129
130- List-Id
131- List-Help
132- List-Unsubscribe
133- List-Post
134- List-Owner
135- List-Archive
136- Resent-To
137- Resent-Sender
138- Resent-Message-Id
139- Resent-Date
140- Resent-From
141- Resent-Cc
142
143---
144
145### header_canon `relaxed` | `simple`
146Default: `relaxed`
147
148Canonicalization algorithm to use for header fields. With `relaxed`, whitespace within
149fields can be modified without breaking the signature, with `simple` no
150modifications are allowed.
151
152---
153
154### body_canon `relaxed` | `simple`
155Default: `relaxed`
156
157Canonicalization algorithm to use for message body. With `relaxed`, whitespace within
158can be modified without breaking the signature, with `simple` no
159modifications are allowed.
160
161---
162
163### sig_expiry _duration_
164Default: `120h`
165
166Time for which signature should be considered valid. Mainly used to prevent
167unauthorized resending of old messages.
168
169---
170
171### hash _hash_
172Default: `sha256`
173
174Hash algorithm to use when computing body hash.
175
176sha256 is the only supported algorithm now.
177
178---
179
180### newkey_algo `rsa4096` | `rsa2048` | `ed25519`
181Default: `rsa2048`
182
183Algorithm to use when generating a new key.
184
185Currently ed25519 is **not** supported by most platforms.
186
187---
188
189### require_sender_match _ids..._
190Default: `envelope auth`
191
192Require specified identifiers to match From header field and key domain,
193otherwise - don't sign the message.
194
195If From field contains multiple addresses, message will not be
196signed unless `allow_multiple_from` is also specified. In that
197case only first address will be compared.
198
199Matching is done in a case-insensitive way.
200
201Valid values:
202
203- `off` – Disable check, always sign.
204- `envelope` – Require MAIL FROM address to match From header.
205- `auth` – If authorization identity contains @ - then require it to
206  fully match From header. Otherwise, check only local-part
207  (username).
208
209---
210
211### allow_multiple_from _boolean_
212Default: `no`
213
214Allow multiple addresses in From header field for purposes of
215`require_sender_match` checks. Only first address will be checked, however.
216
217---
218
219### sign_subdomains _boolean_
220Default: `no`
221
222Sign emails from subdomains using a top domain key.
223
224Allows only one domain to be specified (can be worked around by using `modify.dkim`
225multiple times).