s/qmail:
Section: Misc. Reference Manual Pages (qmail-dksign)
Updated: 8
Index
Return to Main Contents
NAME
qmail-dksign - DKIM sign outgoing messages
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
SQMAIL/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.
- 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
SQMAIL/ssl/domainkeys
to store public and private keys.
Each
domain
may have its own key material resulting in a structure
SQMAIL/ssl/domainkeys/<domain>/,
where the following keyfiles are expected:
- <selector> (default: '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.
Here,
<selector>
is the name of the current
selector.
After having generated keys and providing a new
selector,
this name has to be included as
selector
for the given domain in
SQMAIL/control/dkimdomains
in order to become active for signing.
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
SQMAIL/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
SQMAIL/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.
SEE ALSO
qmail-queue(8),
qmail-remote(8),
qmail-dkim(8),
qmail-dkverify(8),
qmail-log(5).
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- CONTROL FILE
-
- SELECTING DOMAINS FOR SIGNING
-
- CRYPTO MATERIAL
-
- SHARING KEYS FOR DIFFERENT DOMAINS
-
- GNERATING CRYPTO MATERIAL
-
- RESPONSES
-
- SYSTEM IMPACT
-
- SEE ALSO
-
This document was created by
man2html,
using the manual pages.
Time: 16:40:05 GMT, September 13, 2025