dkimdo

The dkimdo utility is a command-line tool that performs common DKIM operations: key generation and key handling, and signing and verifying email messages. DKIM, DomainKeys Identified Mail, is specified in RFC 6376.

The goal of this project is to provide a general-purpose utility that can cater to all you will ever need for working with DKIM on the command-line. All dkimdo subcommands support a multitude of options and are thus highly customisable.

Internally, dkimdo is based on the viadkim library. This library aims for excellent standards conformance, including support for internationalised email. Since dkimdo mostly delegates to the library, its API documentation can be helpful for learning about details of dkimdo behaviour.

Installation

The dkimdo command-line tool is a Rust program; install it with Cargo as usual.

For example, use the following command to install the latest version published on crates.io:

cargo install --locked dkimdo

The minimum supported Rust version is 1.74.0.

Usage

Once installed, the dkimdo program can be invoked on the command-line as dkimdo, followed by a command name.

For key handling the following commands are available:

• dkimdo genkey generates a new signing key and the corresponding DKIM public key record
• dkimdo keyinfo displays information about an existing local signing key
• dkimdo query displays information about a DKIM public key record in DNS

For signing and verifying the following commands are available:

• dkimdo sign signs an email message with a DKIM signature
• dkimdo verify verifies the DKIM signatures in an email message

Additionally, low-level commands dkimdo canon and dkimdo crypt execute canonicalisation algorithms and perform basic cryptographic operations.

All dkimdo commands come with extensive configuration options. See dkimdo help <command> for usage information.

For details, refer to the included manual page dkimdo(1). (You can view the manual page without installing by passing the file path to man: man ./dkimdo.1)

Examples

Generate Ed25519 signing key and DKIM public key record, and print to stdout and stderr:

dkimdo genkey ed25519

Generate 2048-bit RSA signing key:

dkimdo genkey rsa

Generate 1024-bit RSA signing key:

dkimdo genkey --bits 1024 rsa

Generate RSA signing key and store in file key.pem, and also store DKIM public key record in file record.txt:

dkimdo genkey rsa >key.pem 2>record.txt

Generate RSA signing key in file key.pem with permissions 0600:

dkimdo genkey --out-file key.pem rsa

Query DNS for DKIM public key record at default._domainkey.example.com:

dkimdo query example.com default

Query for DKIM public key and check if it corresponds to signing key key.pem:

dkimdo query example.com default key.pem

Sign message msg.eml for domain example.com with selector default, using key key.pem for the signature:

dkimdo sign example.com default key.pem < msg.eml

Verify signatures in message msg.eml:

dkimdo verify < msg.eml

Sign message msg.eml and immediately verify the resulting message:

dkimdo sign example.com default key.pem < msg.eml | dkimdo verify

Each command has a number of customisation options. Sign message msg.eml again, but this time including a user identifier, using relaxed canonicalisation, expiry after one week, a record of the original headers in the diagnostic z= tag, the body length in the l= tag, and formatted to a narrower width:

dkimdo sign \
  --id user@example.com \
  --canon-algo relaxed/relaxed \
  --expiration +1w \
  --copy-headers \
  --body-length '%' \
  --line-width 64 \
  example.com default key.pem < msg.eml

Licence

Copyright © 2024 David Bürgin

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.