SYNOPSIS
qmail-dksign host sender recip [ recip ... ]
DESCRIPTION
qmail-dksign is a stub routine to be invoked by qmail-spawn in place of
qmail-remote and is required to customize the signing policy for
outgoing emails according to RFC 6893/8463 by means of qmail-dkim and
finally to invoke qmail-remote for subsequent message delivery.
qmail-dksign is also an extension to qmail-queue (with comparable
permissions) using queue/dkim/<n>/<m> to provide a temporary but
persistent staging area for outgoing messages to be DKIM signed.
CONTROL FILE
qmail-dksign will be only called by qmail-rspawn if
/var/qmail/control/dkimdomains is present.
dkimdomains: ´domain:selector[,selector2]|sdid|[auid|~]|expire|c:z:l´
allows multitenant and hybrid DKIM signing settings per sending domain.
domain is the sender's envelope domain in order to fetch the
individually tailored DKIM signing paramaters for these.
The following DKIM parameters can be specified:
selector
is used as prepending name label for domain:
selector._domainkey.domain. If not explicitely given, it defaults
to default and is mostly used to support the key roll-over.
selector,selector2
defines a hybrid selector and allows to provide two different
selectors together with their private keys for concurrently
signing of messages according to both the RSA-SHA256 and the
Ed25519 algorithm.
sdid Here, you can overwrite the 'Signing Domain Identifier' (SDID),
thus decouple the information given in the DKIM header from the
envelope domain sender. This allows to setup common DNS public
keys for several domains irrespectively of the sending domain.
auid is the 'Agent/User Identifier' of the signer, in case it is not
the sending domain. In most cases it can be neglected and is
obsolete. Rather, you can specifiy that the auid is always
included as originator of the mail while providing the tilde
symbol ~ here as generic substitude.
expire
determins the validity period of the signature in DKIM signed
message. Due to the assumed key-rollover, it is limited and
defaults to 604800 secs since the email was signed.
(after canonicalization) to the DKIM header. This might be useful
to cope with programs like mailing list servers adding a 'footer'
to the mail after the signing operation has been completed.
c is the 'canonicalization'; thus how a validation client should
deal with signature verification of the received message header
and/or body. Here, the choices are r relax (allow mangling of
whitespaces and cases; default) s simple (=strict) t relax on
header, simple on body, u simple on header, relax on body.
z The signature algorithm can be specified as 1 RSA with sha1, 2 RSA
with sha256 (as default), or 3 providing both signature values in
the mail header; 4 Ed25519 ECC signatures. 5 tells qmail-dksign
to include both RSA-SHA256 and Ed25519 signatures in the mail
header. Here, you need two different selectors and private keys.
Finally, setting
l (literal) advices qmail-dkim to include the body hash length
(after canonicalization) to the DKIM header. This might be useful
to cope with programs like mailing list servers adding a 'footer'
to the mail after the signing operation has been completed.
RSA and Ed25519 signatures can now be used simultaneously while
providing different keys available as distinct selectors. Those
settings are handed-over to qmail-dkim to provide the signing of
emails. qmail-dksign calls qmail-dkim to automatically include the
query method q=dns/txt in the DKIM header.
SELECTING DOMAINS FOR SIGNING
qmail-dksign can be instructed to sign all outgoing mails with the
MTA's private key. This is achieved by simply using *: in
control/dkimdomains. Rather, the signing operation can be restricted
for domains s/qmail has responsibility for, as given in rcpthosts.
This is commanded via =:. Alternatively, in multitenant mode
qmail-dksign may use domain specific DKIM settings and private keys for
the sending domains and permitting parenting. Particular domains for
which outgoing emails shall not be DKIM signed can be given as:
!nodkim.org.
*:
=:default,eddy||~||:5
.heaven.com:||me@devil.com|500000|r:3
cloud1.com:january|postmaster@cloud.com|||t::l
cloud7.com:february|postmaster@cloud.com|||u:1
mybuddy.org:eddy||||:4
!nodkim.org:
Note: The owner of the crypto material (public and private keys) is
qmailq.
CRYPTO MATERIAL
qmail-dksign follows the conventions from qmail-remote to use the
directory /var/qmail/ssl/domainkeys to store public and private keys.
Each domain may have its own key material resulting in a structure
/var/qmail/ssl/domainkeys/<domain>/, where the following keyfiles are
expected:
<selector> ('default')
is a mandatory symbolic link to [rsa|ed25519].private_<selector>
used for signing.
rsa.public_<selector>
is the DER-header enriched and base64 encoded RSA public key.
ed25519.public_<selector>
is the 'naked' base64 encoded Ed25519 public key.
In case of hybrid signatures different selectors need to be given for
the RSA and the Ed25519 keys each. They have to be provided
concatinated by a colon in dkimdomains. White spaces are not allowed.
If the RSA selector is default, it can be omitted while followed by the
colon and the Ed25519 selector name.
SHARING KEYS FOR DIFFERENT DOMAINS
Different domains may however share common keys for signing and
verification. In order to allow a common private key for signing,
simply create symlinks for the others domains under
/var/qmail/ssl/domainkeys/ to the master one. qmail-dksign will now
pick up those and use the provided key for signing.
Here, <selector> is the name of the current selector. After having
generated keys and providing a new selector, this name has to be
/var/qmail/ssl/domainkeys/ to the master one. qmail-dksign will now
pick up those and use the provided key for signing.
However, in general this reqires to deploy DKIM records for those
domains sharing the same public key but require different domain names
as distinguished DNS TXT records.
Rather, you may want to publish just one DKIM DNS TXT record which is
commonly shared for all concerning domains. Since the sending domain is
used as default for the SDID, you need now to provide the same SDID
explicitely for each domain of concern in control/dkimdomains.
The '<selector>' - and not the SDID - together with the literal
._domainkey. and the domain name defines the binding of the private
key with the DKIM TXT record: <selector>._domainkey.<domain>.
GNERATING CRYPTO MATERIAL
Public/private keys can be generated by OpenSSL or LibreSSL or
compatible TLS implementations and shall be provided in canonical
format. The directory /var/qmail/ssl/domainkeys/ and the resulting key
needs to be readable by qmailq, the user qmail-dksign and qmail-dkim
runs under. The private key shall NEVER exposed to the public.
The script mkdkimkey is enabled to generate RSA or Ed25519 private and
public keys in the required format together with a BIND compliant DKIM
DNS TXT record.
RESPONSES
qmail-dksign may provide the following responses indicating an error:
Z Unable to switch to target directory.
Z Unable to create DKIM stage file: <file>
Z Unable to unlink DKIM stage file.
Z Unable to read control files.
Z Unable to read message.
D SMTP cannot transfer messages with partial final lines.
K can't read private file: <file> continue without signing.
Z unable to run qmail-remote. (=> configuration/permission error)
SYSTEM IMPACT
qmail-dksign makes heavy use of system file descriptors. Given a high
concurrencyremote you may run out of file descriptors which thus need
to be enhanced either system-wide or for the specific users qmailr and
qmails.
Man(1) output converted with
man2html
and me.