removed top level directory

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).
+