add sqmail-4.2.29asqmail-4.2

1 files changed, 217 insertions, 0 deletions

diff --git a/man/qmail-dkim.8 b/man/qmail-dkim.8
new file mode 100644
index 0000000..53463e9
--- /dev/null
+++ b/man/qmail-dkim.8
@@ -0,0 +1,217 @@
+.TH s/qmail: qmail-dkim 8
+.SH "NAME"
+qmail-dkim \- libdkim implementation for s/qmail
+.SH "SYNOPSIS"
+.B qmail-dkim
+[
+.I -h
+.I -v
+.I -V
+.I -s[ecckey]
+.I -b[1|2|3]
+.I -c[s|t|u]
+.I -d domain
+.I -i identity
+.I -l 
+.I -q
+.I -t
+.I -x expire_time
+.I -y selector
+.I -Y selector2
+.I -z[1|2|3|4|5]
+]
+.I in_message
+.I RSA_private_key
+.I out_message
+.I Ed25519_private_key
+.SH "DESCRIPTION"
+.B qmail-dkim
+is the implementation of
+.B libdkim
+for s/qmail providing API compatibility 
+and supporting RSA and Ed25519 DKIM signatures
+in single or hybrid mode.
+In hybrid mode, two 
+.I private keys
+and two
+.I selectors 
+need to be provided.
+.B qmail-dkim
+supports distinct operations:
+.TP 5
+.B qmail-dkim \fI-s in_message RSA_private_key out_message\fR
+DKIM signes 
+.I in_message
+with the given
+.I private_key 
+and returns
+.IR out_message .
+.TP 5 
+.B qmail-dkim \fI-s in_message RSA_private_key out_message Ed255_private_key\fR
+signs 
+.I in_message 
+with both a RSA 
+.I RSA_private_key 
+and a
+.IR Ed25519_private_key.
+Here, the RSA default selector is \fIdefault\fR and the 
+Ed25519 default selector is \fIeddy\fR; both subject of change.
+.TP 5
+.B qmail-dkim  \fI-v in_message\fR
+verifies the 
+.IR in_message .
+.SH "DKIM FORMATS"
+DKIM needs a common understanding of the attributes
+subject for signing and verification. 
+The following attributes can be set:
+.TP 5
+-c
+is the 'canonicalization', thus how a validiation client
+should deal with signature verification of the 
+message headers and/or body. Here, the choices are given 
+via an appended character:
+.I r
+relax on header,
+.I s
+simple (strict) on message body,
+.I t
+relax/simple, or eventually
+.I u
+simple relaxed.
+Finally, the hash function to be used in the signature
+can be given as
+.TP 5
+-z
+following either with
+.I 1
+using sha1, or 
+.I 2
+using sha256, or finally as default
+.I 3
+providing both signature values in the mail header.
+.I 4
+telling 
+.B qmail-dkim
+to use the Ed25519 signature scheme.
+.I 5
+allows
+.B qmail-dkim 
+to attach both a 
+.I RSA-SHA256
+as well as a
+.I Ed25519
+signature to the message, which considered to be a
+.I hybrid
+mode.
+
+.SH "DKIM SIGNING"
+.B qmail-dkim
+will include (several) message headers detailing the
+.B DKIM signature
+with at least the following fields:
+.TP 3
+a
+=<signature type>
+.TP 3
+c
+=<used canoncicalization>
+.TP 3
+s
+=<selector>
+.TP 3
+d
+=<identity>
+.TP 3
+i
+=<identifier>
+.TP 3
+h
+=<included header1:header2:...>
+.TP 3
+bh
+=<hash of the canonicalized body until its upper limit length; if given>
+.TP 3
+b
+=<base64 encoded signature>
+.P
+Additional settings can be achieved using the following options:
+.TP 5
+.I -d domain
+is the signer's domain name and together with the prepended
+.TP 5
+.I -y selector
+it is used for the DNS TXT lookup of the public key; supporting
+mainly key roll-over. The first selector is used for RSA signatures.
+.TP 5
+.I -Y selector2
+Same as \fI-y\fR but now for Ed25519 signatures.
+.TP 5
+.I -I identifier
+giving an additional hint about the agent or identifier
+responsible for the signing like 'postmaster@domain'; defaults to 
+.IR domain .
+.TP 5
+.I -t expire_time
+given in seconds, tells how log the signature is valid. 
+It defaults to 
+.I 604800
+secconds (seven days).
+.P
+Further, some more option fields can be displayed in the header:
+.TP 5
+.I -l
+include a body length tag.
+.TP 5
+.I -q
+include the query method tag.
+
+.SH "DKIM VERIFICATION"
+.B qmail-dkim
+as invoked by
+.B qmail-dkverify
+extracting the received DKIM header fields,
+and following the signature verification procedure
+as given here, while fetching the signer's
+.I public key
+using a DNS TXT lookup.
+Now, the respective header lines, and/or
+the message body will be hashed and compared
+against the values taken from the signatures.
+
+The results will be indicated by either return code
+.I 0 
+in case of success, 
+.I 1
+in case of mismatch, or
+.I -1
+if other failures were encountered.
+
+Given the call argument
+.TP 3
+-v 
+.B qmail-dkim
+will provide the DKIM results
+.I pass
+or
+.I fail
+including verbose reasons on the commmand line. 
+This is the legacy mode.
+
+.RE
+Rather, invoking
+.B qmail-dkim
+with argument
+.TP 3
+-V
+it communicates the results over a file interface
+to be picked up by 
+.IR qmail-dkverify .
+
+.SH "SEE ALSO"
+qmail-queue(8),
+qmail-remote(8),
+qmail-dksign(8),
+qmail-dkverify(8),
+qmail-send(8),
+qmail-log(8).
+