Manage Dovecot Mail Crypt Keys with doveadm

Force a new mail crypt key without a backup plan and old encrypted mail can become unreadable for good. This guide covers a cautious workflow for listing, generating, exporting and password-protecting the keys behind Dovecot's mail crypt plugin. The examples target the installed dovecot-core package, version 2.3.21+dfsg1-2ubuntu6.5, whose local manpage describes the Dovecot 2.3 command interface.

Allow about 20 minutes for an existing mail crypt deployment. You need shell access, a configured Dovecot user database and mail storage, and the mail crypt plugin enabled for the relevant service. Commands that operate on keys normally need Dovecot's administrative access. This guide does not enable the plugin or edit Dovecot configuration.

1. Confirm the local contract

Read the installed manual before copying a command. This is an ordinary, read-only check:

$ zcat /usr/share/man/man1/doveadm-mailbox-cryptokey.1.gz | less
$ dpkg-query -W -f='${Package} ${Version}\n' dovecot-core
dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5

The command family is doveadm mailbox cryptokey, with four subcommands: list, generate, export and password. The local manual calls the protected-key setting plugin/mail_crypt_private_password, so use that spelling on this Dovecot 2.3 install. Don't borrow a setting name from a different release without checking its own documentation.

2. Choose one user and inspect its keys

Start with a single account. Swap in an exact userdb username: the command won't create one for you:

$ USER='[email protected]'
$ sudo doveadm mailbox cryptokey list -u "$USER"
 

The output is installation-specific. What matters is the list of user or mailbox keys, not a particular line format. list doesn't require the private-key password per the local manpage. To inspect only the user's own keypair, add -U:

$ sudo doveadm mailbox cryptokey list -u "$USER" -U

Without -u, -A or -F, doveadm uses the currently logged-in user's own environment, easy to miss when an administrator runs a command interactively. Keep -u explicit in your notes and scripts.

3. Generate a user key without touching folder keys

Generate a keypair for the chosen user with -U. A newly generated pair becomes active, changing persistent key state, so record the current key listing first:

$ sudo doveadm mailbox cryptokey generate -u "$USER" -U
$ sudo doveadm mailbox cryptokey list -u "$USER" -U

Normally, keypair creation only happens when no key is found. The local -f option forces creation; treat it as destructive, since a forced replacement can make old encrypted data unreadable if the old key isn't retained. Don't add -f just to make a failing command try harder.

To create a new active user key and re-encrypt existing folder keys with it, the documented combination is:

$ sudo doveadm mailbox cryptokey generate -u "$USER" -U -R

-R re-encrypts every folder key with the current active user key. Schedule that for a proper maintenance window and verify the result with list. Recovery depends on the old key material and your mail-crypt design; there's no generic undo command here.

4. Generate a folder key deliberately

Omit -U and supply a mailbox mask when the target is a folder, not the user keypair:

$ MAILBOX='INBOX'
$ sudo doveadm mailbox cryptokey generate -u "$USER" "$MAILBOX"
$ sudo doveadm mailbox cryptokey list -u "$USER" "$MAILBOX"

Use the mailbox name exactly as Dovecot and the IMAP client see it: namespaces and separators can make a guessed name wrong. Confirm the spelling against your normal mailbox inventory before generating a folder key, and avoid broad masks until you've tested them on one account, since a mask can match more than one mailbox.

5. Add a password to a user key

password changes the password on the user's private key. Use the interactive prompts so the new secret never lands in shell history:

$ sudo doveadm mailbox cryptokey password -u "$USER" -N -O
 

The command prompts for both passwords: -N for the new one, -O for the old. If the key has no old password, follow that deployment's own prompt behaviour. Test the protected key with a harmless list first, then with the Dovecot operation that actually needs private-key access.

For non-interactive use, the local manual documents -n for the new password and -o for the old, plus -C to clear the password entirely. Both are security-sensitive: command arguments can be visible to other processes and may end up in logs, so prefer the prompts. Clearing a password removes protection from the key, so use -C only as a deliberate recovery or maintenance action.

6. Export only when you have a protected destination

Export writes user or folder key material in PEM format. Treat the destination and terminal as sensitive. Use a private, restrictively permissioned directory, and only keep the output once you've confirmed the format your deployment expects:

$ sudo install -d -m 700 /var/lib/dovecot/key-export-review
$ sudo doveadm mailbox cryptokey export -u "$USER" -U | sudo tee /var/lib/dovecot/key-export-review/alice-user-key.pem > /dev/null
$ sudo chmod 600 /var/lib/dovecot/key-export-review/alice-user-key.pem
$ sudo doveadm mailbox cryptokey list -u "$USER" -U

Don't paste PEM contents into a ticket or terminal transcript. If the keys are password-protected, supply the configured password with the global -o plugin/mail_crypt_private_password=... option as documented, and keep a real password out of shared shell history or process lists. Only remove an export once you've confirmed the required backup or transfer is complete: deleting it is irreversible unless another copy exists.

7. Operate on many users only after a single-user test

-A applies a command to every user the user database discovers. -F FILE reads one username per line. Prefer a reviewed file when the population is known:

$ sudo doveadm mailbox cryptokey list -F /root/cryptokey-users.txt -U

Check the file before use:

$ sudo awk 'NF == 1 && $1 !~ /^#/ { print }' /root/cryptokey-users.txt

The manpage warns that -A with a passwd userdb can include system users below first_valid_uid. SQL and LDAP installs also need working iteration settings, SQL's iterate_query or LDAP's iterate_attrs and iterate_filter. A successful run is not proof every intended account was found.