.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// 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// , where the following keyfiles are expected: .TP 5 .IR \ (default:\ 'default') is a mandatory symbolic link to .I [rsa|ed25519].private_ used for signing. .TP 5 .I rsa.public_ is the DER-header enriched and base64 encoded RSA public key. .TP 5 .I ed25519.public_ is the 'naked' base64 encoded Ed25519 public key. .RE Here, .I 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 '' - 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 ._domainkey. . .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: .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: 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).