.TH DKIMDO 1 2024-06-14 "dkimdo 0.1.1"
.SH NAME
dkimdo \- DKIM command-line tool
.SH SYNOPSIS
.SY "dkimdo canon"
.OP \-D index
.OP \-I path
.OP \-l num
.OP \-O path
.OP \-r
.OP \-s names
.I target
.I algo
.YS
.SY "dkimdo crypt"
.I tool
\&...
.YS
.SY "dkimdo genkey"
.OP \-b num
.OP \-E path
.OP \-\-include-pubkey
.OP \-O path
.OP \-\-pubkey-format name
.RI "[\fB\-\-wrap-zonefile\fR" "\~domain\fB:\fPselector" ]
.I key-type
.YS
.SY "dkimdo keyinfo"
.OP \-E path
.OP \-\-pubkey-format name
.RI "[\fB\-\-wrap-zonefile\fR" "\~domain\fB:\fPselector" ]
.I key-file
.YS
.SY "dkimdo query"
.OP \-p
.OP \-s
.OP \-T num
.I domain
.I selector
.RI [ key-file ]
.YS
.SY "dkimdo sign"
.OP \-a algo
.OP \-\-ascii-signature
.OP \-c algo
.OP \-i id
.OP \-I path
.OP \-l len
.OP \-N wsp
.OP \-\-normalize-output
.OP \-o
.OP \-O path
.OP \-\-order-tags names
.OP \-s names
.OP \-t time
.OP \-w num
.OP \-x interval
.OP \-X tag
.OP \-z
.I domain
.I selector
.I key-file
.YS
.SY "dkimdo verify"
.OP \-1
.OP \-b num
.OP \-I path
.OP \-p
.OP \-q
.OP \-s
.OP \-t time
.OP \-T num
.OP \-x
.OP \-z
.YS
.SY "dkimdo help"
.RI [ command ]
.SY "dkimdo version"
.YS
.SH DESCRIPTION
.B dkimdo
performs various DKIM operations.
It provides a set of commands for generating and handling DKIM keys, and for
signing and verifying email messages using DKIM signatures.
DKIM,
.I DomainKeys Identified
.IR Mail ,
is specified in RFC\~6376.
.PP
The
.B dkimdo
program takes as its first argument a command name (for example,
.BR "dkimdo sign" ).
Each such command covers a specific area of DKIM functionality, and accepts
specific options and arguments.
The commands are detailed in the next section.
.PP
The commands make use of the standard I/O streams
.I standard input
(stdin),
.I standard output
(stdout), and
.I standard error
(stderr).
On standard input, commands usually expect an RFC\~5322 email message.
On standard output, commands produce the main data output; some commands produce
“reports”, that is, output for human consumers.
On standard error, most commands produce diagnostic output such as error
messages; commands
.B genkey
and
.B keyinfo
use standard error for secondary data output.
Refer to each command for how it utilizes the I/O streams.
.SH COMMANDS
This section lists all available commands and their options in alphabetical
order.
By convention, options must be passed to a command before any mandatory
positional arguments.
.SS The “canon” command
The
.B canon
command executes one of the four canonicalization algorithms.
The mandatory arguments
.I target
and
.I algo
select, respectively, the message section
.B header
or
.B body
(abbreviated
.B h
and
.BR b )
and the algorithm
.B simple
or
.B relaxed
(abbreviated
.B s
and
.BR r ).
By default, an email message is read from standard input and the resulting bytes
from header or body canonicalization are written to standard output.
The input is automatically normalized to conventional SMTP form with CRLF line
endings.
This command may be abbreviated as
.BR c .
.PP
The command accepts the following options.
.TP
.BR \-l " \fInum\fR, " \-\-body-length " \fInum\fR"
Number of bytes of the body canonicalization result to include in the output.
This option can be used to truncate the canonicalized body as is done through
the
.I l=
tag in signatures.
.TP
.BR \-I " \fIpath\fR, " \-\-in-file " \fIpath\fR"
Path to the message input file.
When this option is used, the email message is not read from standard input, but
from this file instead.
.TP
.BR \-O " \fIpath\fR, " \-\-out-file " \fIpath\fR"
Path to the canonicalization output file.
When this option is used, the canonicalized bytes are not written to standard
output, but to this file instead.
.TP
.BR \-r ", " \-\-raw-input
Treat input as raw header or body.
When doing header canonicalization, this option causes the input to be treated
as a well-formed header section only, using CRLF line endings (without the empty
line separating header and body).
When doing body canonicalization, the input is treated as being only and exactly
the message body, without any normalization or sanitizing to be done.
.IP
When this option is not used, the expected input is an RFC\~5322 email message,
which will be normalized (convert LF to CRLF line endings, add final CRLF to
body if not present) to the conventional SMTP form before being presented to the
canonicalization algorithm.
.TP
.BR \-s " \fInames\fR, " \-\-select-headers " \fInames\fR"
Colon-separated list of header names to select for canonicalization.
Headers are canonicalized as described in “hash step\~2” of RFC\~6376,
section\~3.7 (the
.I h=
tag in signatures).
When neither this option nor
.B \-\-signature-header
are used, the entire header section is canonicalized without filtering.
.TP
.BR \-D " \fIindex\fR, " \-\-signature-header " \fIindex\fR"
Canonicalize a
.I DKIM-Signature
header field occurring in the input.
Value “1” selects the first
.I DKIM-Signature
header, “2” selects the second, and so on.
The header is canonicalized as described in “hash step\~2” of RFC\~6376,
section\~3.7, that is, with the value of the
.I b=
tag stripped and without the final CRLF.
When this option is used together with
.BR \-\-select-headers ,
the canonicalized
.I DKIM-Signature
header is appended to the canonicalized header selection (as in “hash step\~2”
mentioned above).
When neither this option nor
.B \-\-select-headers
are used, the entire header section is canonicalized without filtering.
.SS The “crypt” command
The
.B crypt
command executes one of four cryptography tools.
These tools are called as subcommands of the
.B crypt
command (for example,
.BR "dkimdo crypt hash" ).
These are low-level tools that do not have any notion of RFC\~5322 email
messages or DKIM signatures; they operate on raw byte inputs read from standard
input, and write the result to standard output.
This command may be abbreviated as
.BR y .
.PP
The
.B crypt
command provides all cryptographic operations that are used in DKIM signatures.
Together with the
.B canon
command, these tools make it possible to produce or validate the
.IR body-hash ,
.IR data-hash ,
and
.I signature
values from RFC\~6376, section\~3.7 manually, without going through the
high-level commands
.B dkimdo sign
and
.BR "dkimdo verify" ,
and without requiring the use of third-party tools.
.PP
The following tools and options are available.
.TP
.BR base64 " [" \-d ]
The
.B base64
tool (abbreviated
.BR b )
encodes bytes as a Base64 string, or, if option
.B \-d
is used, decodes bytes from a Base64 string.
.TP
.BR hash " [" \-1 ]
The
.B hash
tool (abbreviated
.BR h )
hashes input bytes to produce the SHA-256 digest or, if option
.B \-1
is used, the SHA-1 digest.
The output is the digest in binary, not textual form.
.TP
.BR sign " [" \-1 "] \fIkey-file\fR"
The
.B sign
tool (abbreviated
.BR s )
produces an RSA with SHA-256 signature (SHA-1 if option
.B \-1
is used) or an Ed25519 signature, depending on the signing key used.
The mandatory argument
.I key-file
is the path to a signing key in PKCS#8 PEM format.
The message to sign is read from standard input.
.TP
.BR verify " [" \-1 "] [" \-e "] \fIpubkey-der-file\fR \fIsig-file\fR"
The
.B verify
tool (abbreviated
.BR v )
verifies an RSA with SHA-256 signature (SHA-1 if option
.B \-1
is used) or, if option
.B \-e
is used, an Ed25519 signature.
The first mandatory argument
.I pubkey-der-file
is the path to a file containing public key bytes (for example, as found encoded
in a DKIM public key record’s
.I p=
tag), the second mandatory argument
.I sig-file
is the path to a file containing a cryptographic signature (for example, as
found encoded in a
.I DKIM-Signature
header’s
.I b=
tag).
The message to verify is read from standard input.
A zero exit code signals successful verification.
.IP
The public key bytes may be supplied in several formats.
For both RSA and Ed25519 verification, the public key may be encoded in ASN.1
DER
.I SubjectPublicKeyInfo
(RFC\~5280) format.
For RSA, the public key may also be encoded in ASN.1 DER
.I RSAPublicKey
(RFC\~8017) format.
For Ed25519, passing the raw 32 bytes of the public key is also supported.
.SS The “genkey” command
The
.B genkey
command generates a new signing key and the corresponding DKIM public key
record.
The mandatory argument
.I key-type
selects the type of key to generate:
.B rsa
(abbreviated
.BR r )
generates an RSA signing key,
.B ed25519
(abbreviated
.BR e )
generates an Ed25519 signing key.
By default, the signing key is printed in PKCS#8 PEM format to standard output,
and the DKIM public key record is printed to standard error.
This command may be abbreviated as
.BR g .
.PP
The command accepts the following options.
.TP
.BR \-b " \fInum\fR, " \-\-bits " \fInum\fR"
The number of bits in an RSA key.
The default is 2048.
.TP
.BR \-E " \fIpath\fR, " \-\-err-file " \fIpath\fR"
Path to DKIM public key record output file.
When this option is used, the public key record is not written to standard
error, but to this file instead.
.TP
.B \-\-include-pubkey
Include the public key bytes in the generated Ed25519 signing key.
When this option is not used, only the private key bytes are included in the
signing key output.
.TP
.BR \-O " \fIpath\fR, " \-\-out-file " \fIpath\fR"
Path to signing key output file.
When this option is used, the signing key is not written to standard output,
but, with restricted access permissions, to this file instead.
.TP
.BR \-\-pubkey-format " \fIname\fR"
Encoding format to use for RSA public key.
The format name
.B spki
outputs the RSA public key in
.I SubjectPublicKeyInfo
(RFC\~5280) format; format name
.B pkcs1
outputs the RSA public key in
.I RSAPublicKey
(RFC\~8017, PKCS#1) format.
The default is
.BR spki .
.IP
Format
.I RSAPublicKey
is the standard format according to RFC\~6376, section\~3.6.1, but it is not
widely used or supported;
instead, format
.I SubjectPublicKeyInfo
has become the de-facto standard format in wide use.
Therefore, use of format
.B pkcs1
is not recommended.
Refer to the errata of RFC\~6376 for more information.
.TP
.BR \-\-wrap-zonefile " \fIdomain\fR" : "\fIselector\fR"
Wrap public key record in a zonefile snippet.
The option argument is the domain of the record and the selector, separated by a
colon.
When this option is used, the contents of the public key record are printed
embedded in a zonefile entry that could be included in a zonefile.
.SS The “help” command
The
.B help
command shows usage information for the
.B dkimdo
program.
If optional argument
.I command
is given, it shows a brief overview of the usage and available options of the
command.
This command may be abbreviated as
.B h
(the option-like forms
.B \-h
and
.B \-\-help
are also recognized).
.PP
For all commands, the usage information is also available as option
.B \-h
and
.BR \-\-help .
That is,
.B dkimdo help sign
and
.B dkimdo sign \-\-help
are equivalent.
.SS The “keyinfo” command
The
.B keyinfo
command inspects a locally accessible signing key.
It reads a key file in PKCS#8 PEM format and shows a report for the key found,
and also prints the corresponding DKIM public key record to standard error.
The mandatory argument
.I key-file
is the signing key to inspect.
This command may be abbreviated as
.BR k .
.PP
The command accepts the following options.
.TP
.BR \-E " \fIpath\fR, " \-\-err-file " \fIpath\fR"
Same as for the
.B genkey
command.
.TP
.BR \-\-pubkey-format " \fIname\fR"
Same as for the
.B genkey
command.
.TP
.BR \-\-wrap-zonefile " \fIdomain\fR" : "\fIselector\fR"
Same as for the
.B genkey
command.
.SS The “query” command
The
.B query
command queries the DNS for a DKIM public key record, and shows a report listing
some of its properties.
The mandatory arguments
.I domain
and
.I selector
are used to construct the target domain name
.RI (“ selector ._domainkey. domain .”).
Optional argument
.I key-file
is the path to a signing key in PKCS#8 PEM format, which, if given, is checked
for correspondence to the public key in the public key record (that is, whether
or not the two keys form a public/private key pair).
This command may be abbreviated as
.BR q .
.PP
The command accepts the following options.
.TP
.BR \-p ", " \-\-show-record
Print the actual DKIM public key record retrieved from DNS alongside the report.
.TP
.BR \-s ", " \-\-system-resolver
Use the resolver configured on the system.
When this option is used,
.B dkimdo
will read the resolver configuration present on the system (for example, at
.I /etc/resolv.conf
on UNIX-like systems) to configure the integrated resolver library.
.IP
When this option is not used, the program disregards the local resolver
configuration and performs name resolution on its own by directly querying a
well-known public DNS service such as Google Public DNS.
.TP
.BR \-T " \fInum\fR, " \-\-timeout-secs " \fInum\fR"
Number of seconds until a query times out.
The default is 10.
.SS The “sign” command
The
.B sign
command signs a message with a DKIM signature.
The mandatory arguments are
.IR domain ,
the signing domain in the
.I d=
tag;
.IR selector ,
the selector in the
.I s=
tag; and
.IR key-file ,
the path to a signing key in PKCS#8 PEM format.
By default, it reads an email message from standard input, and writes the
message to standard output with a new
.I DKIM-Signature
header prepended.
The input is automatically normalized to conventional SMTP form with CRLF line
endings.
This command may be abbreviated as
.BR s .
.PP
The command accepts the following options.
.TP
.BR \-X " \fItag\fR, " \-\-add-tag " \fItag\fR"
Additional tag-value pair to include in the signature (for example,
.BR ex=123 ).
This option may be used repeatedly.
.TP
.B \-\-ascii-signature
Use only ASCII in the generated signature.
When this option is used, any non-ASCII items such as internationalized domain
names in Unicode form are converted to their ASCII equivalent.
.TP
.BR \-l " \fIlen\fR, " \-\-body-length " \fIlen\fR"
Number of bytes of the canonicalized message body to include in the signature
.RI ( l=
tag).
The value
.B %
sets
.I l=
to the actual message body length.
The default is no
.I l=
tag.
.TP
.BR \-c " \fIalgo\fR, " \-\-canon-algo " \fIalgo\fR"
The canonicalization algorithm
.RI ( c=
tag).
The default is
.BR relaxed/simple .
.TP
.BR \-z ", " \-\-copy-headers
Record original headers in
.I z=
tag.
When this option is used, the generated signature includes the
.I z=
tag with a copy of all header fields used to create the signature.
.TP
.BR \-x " \fIinterval\fR, " \-\-expiration " \fIinterval\fR"
The expiration timestamp to include in the
.I x=
tag.
This value can be given as a timestamp, which must be greater than the timestamp
in
.I t=
(for example,
.BR 1708634568 );
or as a duration expression consisting of pairs of integer and time unit, where
acceptable units are
.BR w ,
.BR d ,
.BR h ,
.BR m ,
and
.BR s ,
meaning weeks, days, hours, minutes, and seconds, respectively, and the whole
expression optionally preceded by
.B +
(for example,
.BR +3d10m ,
“valid for three days and ten minutes”).
An empty value suppresses inclusion of the
.I x=
tag.
The default is expiry after five days.
.TP
.BR \-i " \fIid\fR, " \-\-id " \fIid\fR"
The signing identity to record in the
.I i=
tag.
.TP
.BR \-I " \fIpath\fR, " \-\-in-file " \fIpath\fR"
Path to the message input file.
When this option is used, the email message is not read from standard input, but
from this file instead.
.TP
.BR \-N " \fIwsp\fR, " \-\-indent " \fIwsp\fR"
Indentation whitespace of continuation lines in the generated signature.
Indentation whitespace must consist of only space and tab characters.
The default is a single tab character.
.TP
.BR \-w " \fInum\fR, " \-\-line-width " \fInum\fR"
The maximum line width in characters of the generated signature.
The default is 78.
.TP
.B \-\-normalize-output
Output message in the normalized SMTP form using CRLF line endings.
Regardless of whether this option is used or not, the input message is presented
to the DKIM algorithm in the required RFC\~5322 (hence “normalized”) form.
When this option is not used, the email message is printed (to stdout) in the
unmodified, original form.
.TP
.BR \-\-order-tags " \fInames\fR"
Order tags according to the given colon-separated tag names.
The tag names included in the generated DKIM signature are ordered according to
this list of names; tag names not listed here are appended.
For example, the value
.B c:a:b
causes the
.IR c= ,
.IR a= ,
and
.I b=
tags to be included at the beginning of the signature in this order, the
remaining tags are included after in an unspecified order.
.TP
.BR \-O " \fIpath\fR, " \-\-out-file " \fIpath\fR"
Path to the signed message output file.
When this option is used, the signed email message is not written to standard
output, but to this file instead.
.TP
.BR \-a " \fIalgo\fR, " \-\-sign-algo " \fIalgo\fR"
The signing algorithm to use
.RI ( a=
tag).
The default is the key type of the signing key in argument
.I key-file
with hash algorithm SHA-256.
.TP
.BR \-s " \fInames\fR, " \-\-sign-headers " \fInames\fR"
Colon-separated list of header names to include in the signature
.RI ( h=
tag).
The header names are included in
.I h=
exactly as given.
.IP
When this option is not used, the headers in the default set
.BR From ,
.BR Sender ,
.BR Reply-To ,
.BR Subject ,
.BR Date ,
.BR Message-ID ,
.BR To ,
.BR Cc ,
.BR MIME-Version ,
.BR Content-Type ,
.BR Content-Transfer-Encoding ,
.BR Content-Disposition ,
.BR In-Reply-To ,
and
.B References
are included in the signature.
These headers will then be “oversigned”, that is, included in
.I h=
once more than actually present in the message, preventing later addition of
such headers.
.TP
.BR \-o ", " \-\-signature-only
Output only the generated
.I DKIM-Signature
header, not the email message.
.TP
.BR \-t " \fItime\fR, " \-\-timestamp " \fItime\fR"
The timestamp to record in the
.I t=
tag.
A timestamp is the number of seconds since the UNIX epoch (for example,
.BR 1708634567 ).
An empty value suppresses inclusion of the
.I t=
tag.
The default is the current timestamp.
.SS The “verify” command
The
.B verify
command verifies the DKIM signatures in an email message.
By default, an email message is read from standard input and a report with the
verification results is shown.
The input is automatically normalized to conventional SMTP form with CRLF line
endings.
This command may be abbreviated as
.BR v .
.PP
The command accepts the following options.
.TP
.BR \-1 ", " \-\-allow-sha1
Allow signatures using the SHA-1 hash algorithm.
When this option is not used, signatures using the SHA-1 hash algorithm evaluate
to failure result
.IR policy .
.TP
.BR \-t " \fItime\fR, " \-\-as-of " \fItime\fR"
Assume the given timestamp being the current time.
A timestamp is the number of seconds since the UNIX epoch (for example,
.BR 1708634567 ).
The current time is relevant when evaluating the validity of a signature’s
.I t=
and
.I x=
tags.
.TP
.BR \-z ", " \-\-eval-z
Re-evaluate failing signatures by substituting the header fields found in the
signature’s
.I z=
tag, if present, for the actual message header.
This option can be used to diagnose in-transit header rewriting problems:
The
.I z=
tag is intended to record header fields as they appeared at the time the message
was signed; any alterations done later are not present, and the re-evaluation
might therefore produce a successful result.
.IP
When using this option, the second verification result does not replace the
first result, but is displayed alongside it.
The contents of the
.I z=
tag are analyzed for differences from the headers actually present, and
highlighted in a diff-like format showing the modified header fields.
In this diff, headers with names occurring multiple times in the original and
actual header field set are matched from the bottom up, that is, in evaluation
order.
Note that valid signatures are not re-evaluated, any
.I z=
tag present is ignored.
.TP
.BR \-x ", " \-\-ignore-time
Allow expired signatures and signatures with a timestamp in the future.
When this option is not used, such signatures evaluate to failure result
.IR policy .
.TP
.BR \-I " \fIpath\fR, " \-\-in-file " \fIpath\fR"
Path to the message input file.
When this option is used, the email message is not read from standard input, but
from this file instead.
.TP
.BR \-b " \fInum\fR, " \-\-min-key-bits " \fInum\fR"
Minimum acceptable number of bits in RSA key.
Signatures using an RSA key of a size below this threshold evaluate to failure
result
.IR policy .
The default is 1024.
.TP
.BR \-q ", " \-\-quiet
Signal verification result through exit code.
When this option is used, the signatures are evaluated, but no report is shown;
instead a zero exit code signals success, and a non-zero exit code signals
failure.
“Success” is at least one acceptable signature.
.TP
.BR \-p ", " \-\-show-header
Print the actual
.I DKIM-Signature
header alongside each evaluation result in the report.
.TP
.BR \-s ", " \-\-system-resolver
Same as for the
.B query
command.
.TP
.BR \-T " \fInum\fR, " \-\-timeout-secs " \fInum\fR"
Same as for the
.B query
command.
.SS The “version” command
The
.B version
command shows version information for the
.B dkimdo
program.
(For this command, the synonymous option-like forms
.B \-V
and
.B \-\-version
are also recognized.)
.SH SEE ALSO
RFC\~6376