Manage Dovecot Mail Crypt Keys with doveadm

You will finish with a cautious workflow for listing, generating, exporting and password-protecting the keys used by 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. The 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. Its four subcommands are 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 installation. Do not substitute a setting name from a different Dovecot release without checking its own documentation.

2. Choose one user and inspect its keys

Start with a single account. Replace the placeholder with an exact userdb username; the command does not create a user for you:

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

The output is installation-specific. The useful result is a list of user or mailbox keys, not a particular line format. The list operation does not require the private-key password according to the local manpage. To inspect only the user's keypair, add -U:

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

Without -u, -A or -F, doveadm uses the environment of the currently logged-in user. That default is easy to miss when an administrator runs a command interactively. Keep -u explicit in operational 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. This changes 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 happens only when no key is found. The local -f option forces creation. Treat it as destructive: a forced replacement can make old encrypted data inaccessible if the old key is not retained by the deployment. Do not add -f merely to make a failed command try harder.

If your intention is 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 all folder keys with the current active user key. Schedule that operation for a suitable maintenance window and verify the result with list. Recovery depends on the old key material and your mail-crypt design; there is no generic undo command in this utility.

4. Generate a folder key deliberately

Omit -U and supply a mailbox mask when the target is a folder rather than 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 as Dovecot and the IMAP client see it. Namespaces and mailbox separators can make a guessed name wrong. Confirm the exact spelling with your normal mailbox inventory before generating a folder key. A mask can match more than one mailbox, so avoid broad patterns until you have tested them on one account.

5. Add a password to a user key

The password subcommand changes the password on the user's private key. Use interactive prompts so the new secret is not written into shell history:

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

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

To provide passwords non-interactively, the local manual documents -n for the new password and -o for the old password. It also documents -C to clear the password. Both are security-sensitive: command arguments can be visible to other processes and may enter logs. Prefer the prompts. Clearing a password removes protection from the key, so use -C only as an intentional 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. First use a private temporary directory with restrictive permissions, then save the command's output only if you have confirmed the command's output format in your deployment:

$ 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

Do not paste the PEM contents into a ticket or terminal transcript. If the keys are password-protected, provide the configured password with the global -o plugin/mail_crypt_private_password=... option as documented. Avoid putting a real password in a shared shell history or process list. Remove an export only after confirming that 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 all users discovered through the user database. -F FILE reads one username per line from a file. Prefer a reviewed file when the intended 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 installations also need working iteration settings, such as SQL iterate_query or LDAP iterate_attrs and iterate_filter. A successful command is not proof that every intended account was found.