diff options
Diffstat (limited to 'man/qmail-dkim.8')
| -rw-r--r-- | man/qmail-dkim.8 | 217 |
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). + |