diff options
Diffstat (limited to 'man/qmail-dksign.9')
| -rw-r--r-- | man/qmail-dksign.9 | 336 |
1 files changed, 336 insertions, 0 deletions
diff --git a/man/qmail-dksign.9 b/man/qmail-dksign.9 new file mode 100644 index 0000000..08d310e --- /dev/null +++ b/man/qmail-dksign.9 @@ -0,0 +1,336 @@ +.TH s/qmail: qmail-dksign 8 +.SH "NAME" +qmail-dksign \- DKIM sign outgoing messages +.SH "SYNOPSIS" +.B qmail-dksign +.I host +.I sender +.I recip +[ +.I recip ... +] +.SH "DESCRIPTION" +.B qmail-dksign +is a stub routine to be invoked by +.B qmail-spawn +in place of +.B qmail-remote +and is required to customize the signing policy +for outgoing emails according to RFC 6893/8463 by means of +.B qmail-dkim +and finally to invoke +.B qmail-remote +for subsequent message delivery. + +.B qmail-dksign +is also an extension to +.B qmail-queue +(with comparable permissions) using +.I queue/dkim/<n>/<m> +to provide a temporary but persistent staging +area for outgoing messages to be DKIM signed. +.SH "CONTROL FILE" +.B qmail-dksign +will be only called by +.B qmail-rspawn +if +.I SQMAIL/control/dkimdomains +is present. + +.IR dkimdomains : +\'domain:selector[,selector2]|sdid|[auid|~]|expire|c:z:l\' +allows multitenant and hybrid DKIM signing settings per sending +.IR domain . + +.I 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: +.TP 5 +.I selector +is used as prepending name label for +.IR domain : +.IR selector._domainkey.domain . +If not explicitely given, it defaults to +.I default +and is mostly used to support the key roll-over. +.TP 5 +.I 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. +.TP 5 +.I 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 +.IR domain . +.TP 5 +.I auid +is the 'Agent/User Identifier' of the signer, +in case it is not the sending +.IR domain . +In most cases it can be neglected and is obsolete. +Rather, you can specifiy that the +.I auid +is always included as +.I originator +of the mail while providing the tilde symbol +.I ~ +here as generic substitude. +.TP 5 +.I expire +determins the validity period of the signature in DKIM signed +message. Due to the assumed key-rollover, it is limited +and defaults to +.I 604800 +secs since the email was signed. +.TP 5 +.I 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 +.I r +relax (allow mangling of whitespaces and cases; default) +.I s +simple (=strict) +.I t +relax on header, simple on body, +.I u +simple on header, relax on body. +.TP 5 +.I z +The signature algorithm can be specified as +.I 1 +RSA with sha1, +.I 2 +RSA with sha256 (as default), or +.I 3 +providing both signature values in the mail header; +.I 4 +Ed25519 ECC signatures. +.I 5 +tells +.B qmail-dksign +to include both +.I RSA-SHA256 +and +.I Ed25519 +signatures in the mail header. +Here, you need two different +.I selectors +and +.IR private\ keys. +Finally, setting +.TP 5 +.I l +(literal) advices +.I 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. + +.RE +RSA and Ed25519 signatures can now be used simultaneously +while providing different keys available as distinct selectors. +Those settings are handed-over to +.B qmail-dkim +to provide the signing of emails. +.B qmail-dksign +calls +.B qmail-dkim +to automatically include the query method +.I q=dns/txt +in the DKIM header. +.SH "SELECTING DOMAINS FOR SIGNING" +.B qmail-dksign +can be instructed to sign all outgoing mails with the +MTA's private key. This is achieved by simply using +.I *: +in +.IR control/dkimdomains . +Rather, the signing operation can be restricted for domains +.B s/qmail +has responsibility for, as given in +.IR rcpthosts . +This is commanded via +.IR =: . +Alternatively, in multitenant mode +.B 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: +.IR !nodkim.org . + +.EE + *: + =: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: +.EX + +Note: The owner of the crypto material (public and private keys) is +.IR qmailq . +.SH "CRYPTO MATERIAL" +.B qmail-dksign +follows the conventions from +.B qmail-remote +to use the directory +.I SQMAIL/ssl/domainkeys +to store public and private keys. + +Each +.I domain +may have its own key material resulting in a structure +.IR SQMAIL/ssl/domainkeys/<domain>/ , +where the following keyfiles are expected: +.TP 5 +.IR <selector>\ (default:\ 'default') +is a mandatory symbolic link to +.I [rsa|ed25519].private_<selector> +used for signing. +.TP 5 +.I rsa.public_<selector> +is the DER-header enriched and base64 encoded RSA public key. +.TP 5 +.I ed25519.public_<selector> +is the 'naked' base64 encoded Ed25519 public key. + +.RE +Here, +.I <selector> +is the name of the current +.IR selector . +After having generated keys and providing a new +.IR selector , +this name has to be included as +.I selector +for the given domain in +.I SQMAIL/control/dkimdomains +in order to become active for signing. + +In case of +.I 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 +.IR dkimdomains . +White spaces are not allowed. If the RSA selector is +.IR default , +it can be omitted while followed by the colon and the +Ed25519 selector name. + +.SH "SHARING KEYS FOR DIFFERENT DOMAINS" +Different +.I 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 +.I SQMAIL/ssl/domainkeys/ +to the master one. +.B 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 +.I sending\ domain +is used as default for the +.IR SDID , +you need now to provide the same +.I SDID +explicitely for each domain of concern in +.IR control/dkimdomains . + +The '<selector>' - and not the SDID - +together with the literal +.I ._domainkey. +and the domain name defines the binding of the +private key with the DKIM TXT record: +.IR <selector>._domainkey.<domain> . + +.SH "GNERATING CRYPTO MATERIAL" +Public/private keys can be generated by +.I OpenSSL +or +.I LibreSSL +or compatible TLS implementations and +shall be provided in canonical format. +The directory +.I SQMAIL/ssl/domainkeys/ +and the resulting key needs to be readable by +.IR qmailq , +the user +.B qmail-dksign +and +.B qmail-dkim +runs under. The private key shall +.B NEVER +exposed to the public. + +The script +.B mkdkimkey +is enabled to generate +.I RSA +or +.I Ed25519 +private and public keys in the required format +together with a +.I BIND +compliant DKIM DNS TXT record. +.SH "RESPONSES" +.B qmail-dksign +may provide the following responses indicating an error: +.TP 5 +Z +Unable to switch to target directory. +.TP 5 +Z +Unable to create DKIM stage file: <file> +.TP 5 +Z +Unable to unlink DKIM stage file. +.TP 5 +Z +Unable to read control files. +.TP 5 +Z +Unable to read message. +.TP 5 +D +SMTP cannot transfer messages with partial final lines. +.TP 5 +K +can't read private file: <file> continue without signing. +.TP 5 +Z +unable to run qmail-remote. (=> configuration/permission error) +.SH "SYSTEM IMPACT" +.B qmail-dksign +makes heavy use of system file descriptors. +Given a high +.I concurrencyremote +you may run out of file descriptors which thus need to be enhanced +either system-wide or for the specific users +.I qmailr +and +.IR qmails . +.SH "SEE ALSO" +qmail-queue(8), +qmail-remote(8), +qmail-dkim(8), +qmail-dkverify(8), +qmail-log(8). + |