# 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.

[RFC 6376]: https://www.rfc-editor.org/rfc/rfc6376
[viadkim]: https://crates.io/crates/viadkim

## 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.

[Rust]: https://www.rust-lang.org
[crates.io]: https://crates.io/crates/dkimdo

## 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`)

[*dkimdo*(1)]: https://codeberg.org/glts/dkimdo/src/tag/0.1.1/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/>.