Dovecot CE
Search K

Appearance

Mail Crypt Plugin (mail-crypt) ​

The mail crypt plugin is used to secure email messages stored in a Dovecot system. Messages are encrypted before written to storage and decrypted after reading. Both operations are transparent to the user.

In case of unauthorized access to the storage backend, the messages will, without access to the decryption keys, be unreadable to the offending party.

There can be a single encryption key for the whole system or each user can have a key of their own. The used cryptographical methods are widely used standards and keys are stored in portable formats, when possible.

Functional Overview ​

The use of mail crypt plugin depends on a user having a keypair, a private and a public key, for asymmetric cryptography. These keys are provisioned in a variable via the user database or directly from Dovecot configuration files.

The public half of the provisioned keypairs are used to generate and encrypt keys for symmetric encryption. The symmetric keys are used to encrypt and decrypt individual files. Symmetric encryption is faster and more suitable for block mode storage encryption. The symmetric key used to encrypt a file is stored, after being encrypted with the public asymmetric key, together with the file.

Encryption Technologies ​

The mail crypt plugin provides encryption at rest for emails.

Encryption of the messages is performed using the symmetric Advanced Encryption Standard (AES) algorithm in Galois/Counter Mode (GCM) with 256 bit keys. Integrity of the data is ensured using Authenticated Encryption with Associated Data (AEAD) with SHA256 hashing.

The encryption keys for the symmetric encryption are randomly generated. These keys in turn are encrypted using a key derived with from the provisioned private key.

Provisioned private keys can be Elliptic Curve (EC) keys or RSA Encryption is done using the Integrated Encryption Scheme (IES). This algorithm is usable both with EC and RSA keys.

Technical Requirements ​

Using per-folder keys is not considered production quality, but global keys are fine.

WARNING

Improper configuration or use can make your emails unrecoverable! Treat encryption with care and backup encryption keys!

This page assumes you are using configuring mail encryption from scratch with a recent version of Dovecot.

Settings ​

crypt_acl_require_secure_key_sharing

Defaultno
Valueboolean

If enabled, you cannot share a key to groups or someone without a public key.

crypt_global_public_key_file

Default[None]
ValueFile

Public key to encrypt files. Key must be in PEM pkey format. The PEM key may additionally be base64-encoded into a single line, which can make it easier to store into userdb extra fields.

crypt_user_key_curve

Default[None]
Valuestring

Defines the elliptic curve to use for key generation.

Any valid curve supported by the underlying cryptographic library is allowed.

Example:

crypt_user_key_curve = secp521r1

This must be set if you wish to use folder keys rather than global keys.

With global keys (either RSA or EC keys), all keying material is taken from the setting and no key generation is performed.

In folder-keys mode, a key pair is generated for the user, and a folder-specific key pair is generated. The latter is encrypted by means of the user's key pair.

For EdDSA, you need to use X448 or X25519, case sensitive.

crypt_user_key_password

Default[None]
Valuestring

Password to decrypt user's master private key.

crypt_write_algorithm

Defaultaes-256-gcm-sha256
Valuestring

Set the encryption algorithm. If empty new mails are not encrypted, but existing mails can still be decrypted.

Supported symmetric algorithms ​

While mail crypt plugin does not support setting encryption algorithm, it is possible to specify one with FS crypt.

Dovecot supports all algorithms in OpenSSL that have an OID assigned, and additionally few more (with official OIDs).

In particular, XTS, CCM and CTR modes are not supported, due to the way they would need to be handled. Some operating systems limit the available algorithms with policies.

It is recommended to use AES-GCM or ChaCha20-Poly1305 algorithm, with SHA256 or greater.

Algorithm setting format is <algorithm name>‐<mode>‐<hash algorithm;>. E.g. aes-256-gcm-sha256 or chacha20-poly1305-sha256.

Note that hash algorithm is used for various hashing purposes, not just data integrity, so it is always required.

Files encrypted with one algorithm can be decrypted even if the configuration specifies different algorithm, as the parameters are stored in the file.

List of known algorithms that Dovecot supports as of writing.

Encryption algorithmSupported sizeSupported modes
chacha20-poly13051,3
aes128, 192, 256gcm1, cbc2
camellia128, 192, 256cbc2
aria128, 192, 256cbc2
seed-cbc2
sm4-cbc2
des-ede3-cbc2

1 Uses AEAD integrity.

2 Uses HMAC integrity.

3 Requires recent enough OpenSSL.

Dynamic Settings ​

Per-user settings may be returned by userdb: Extra Fields. To provide crypt_global_private_key or crypt_global_public_key_file as a single line userdb attribute you can base64 encode the original PEM key contents. For example:

sh
cat ecprivkey.pem | base64 -w0

All configured keys must be in PEM format.

Modes Of Operation ​

Mail crypt plugin can operate using either global keys or folder keys. Using both is not supported.

Folder Keys Mode ​

In this mode, for the user a key pair is generated. Then for each folder a key pair is generated. This folder is encrypted using the user's key pair. A user can have more than one key pair but only one can be active.

Unencrypted User Keys ​

In this version of the folder keys mode, each user's private key is stored unencrypted on the server.

Example config for folder keys with Maildir:

mail_plugins {
  mail_crypt = yes
}
mail_attribute {
  dict file {
    path = %{home}/Maildir/dovecot-attributes
  }
}

crypt_user_key_curve = secp521r1

Encrypted User Keys ​

In this version of the folder keys mode, the users private key is stored encrypted on the server.

Example config for mandatory encrypted folder keys with Maildir:

mail_plugins {
  mail_crypt = yes
}
mail_attribute {
  dict file {
    path = %{home}/Maildir/dovecot-attributes
  }
}

crypt_user_key_curve = secp521r1
crypt_user_key_require_encrypted = yes

The password that is used to decrypt the users master/private key, must be provided via password query:

passdb sql {
  query = SELECT email as user, password, '%{password | sha256}' AS userdb_crypt_user_key_password \
    FROM virtual_users \
    WHERE email='%{user}'
}

Choosing Encryption Password ​

DO NOT use passwords directly. It can contain % which is interpreted as variable expansion and can cause errors. Also, it might be visible in debug logging. Suggested approaches are base64 encoding, hex encoding or hashing the password. With hashing, you get the extra benefit that password won't be directly visible in logs.

Another issue that you must consider when using user's password is that when the password changes, you must re-encrypt the user private key.

Global keys ​

In this mode, all keying material is taken from plugin environment. You can use either Elliptic Curve (EC) keys (recommended) or RSA keys. No key generation is automatically performed.

A good solution for environments where no user folder sharing is needed is to generate per-user EC key pair and encrypt that with something derived from user's password. The benefit is that it can be easier to do key management when you can do the EC re-encryption steps in case of password change in your user database instead of dovecot's database.

You should not configure crypt_user_key_curve when using global keys.

Elliptic Curve (EC) Key ​

In order to generate an EC key, you must first choose a curve from the output of this command:

sh
openssl ecparam -list_curves

If you choose the curve prime256v1, generate an EC key with the command:

sh
openssl ecparam -name prime256v1 -genkey | openssl pkey -out ecprivkey.pem

Then generate a public key out of your private EC key

sh
openssl pkey -in ecprivkey.pem -pubout -out ecpubkey.pem

These keys can now be used with this configuration:

mail_plugins {
  mail_crypt = yes
}

crypt_global_public_key_file = rsapubkey.pem
crypt_global_private_key main {
  crypt_private_key_file = rsaprivkey.pem
  crypt_private_password = secret
}
Converting EC key to PKEY ​

If you have an EC private key which begins with something like:

-----BEGIN EC PRIVATE KEY-----

With possibly parameters like this before that:

-----BEGIN EC PARAMETERS-----
BgUrgQQACg==
-----END EC PARAMETERS-----

You must convert it to pkey format with:

sh
openssl pkey -in oldkey.pem -out newkey.pem

Then newkey.pem can be used with mail-crypt plugin.

Using Edwards curve DSA (EdDSA) ​

Added: 2.4.0

You can use EdSDA keys by using algorithm X25519 or X448 (case sensitive).

To generate a suitable keypair, use

sh
openssl genpkey -algorithm X448 -out edprivkey.pem
openssl pkey -in private.pem -pubout -out edpubkey.pem

Note that ED25519 keys are not suitable for X25519.

RSA key ​

WARNING

Use of RSA keys is discouraged, please use crypt_user_key_curve instead.

You can generate an unencrypted RSA private key in the pkey format with the command:

sh
openssl genpkey -algorithm RSA -out rsaprivkey.pem

Alternatively, you can generate a password encrypted private key with:

sh
openssl genpkey -algorithm RSA -out rsaprivkey.pem -aes-128-cbc -pass pass:secret

This does make the password show up in the process listing, so it can be visible for everyone on the system.

Regardless of whether you generated an unencrypted or password encrypted private key, you can generate a public key out of it with:

sh
openssl pkey -in rsaprivkey.pem -pubout -out rsapubkey.pem

These keys can then be used with this configuration:

mail_plugins {
  mail_crypt = yes
}

crypt_global_public_key_file = rsapubkey.pem
crypt_global_private_key main {
  crypt_private_key_file = rsaprivkey.pem
  crypt_private_password = secret
}

Base64-encoded Keys ​

Mail-crypt plugin can read keys that are base64 encoded. This is intended mostly for providing PEM keys via userdb, because it may be difficult to get userdb to return multi-line values.

Hence, this is possible:

sh
openssl ecparam -name secp256k1 -genkey | openssl pkey | base64 -w0 > ecprivkey.pem
base64 -d ecprivkey.pem | openssl ec -pubout | base64 -w0 > ecpubkey.pem
mail_plugins {
  mail_crypt = yes
}
crypt_global_private_key main {
  # create the filter, but leave its settings empty
}

passdb static {
  password = pass
  fields {
    crypt_global_public_key_file = ecpubkey.pem
    crypt_global_private_key/main/private_key_file = inline:<base64-encoded content of ecprivkey.pem>
  }
}

Read-only Mode ​

If you have encrypted mailboxes that you need to read, but no longer want to encrypt new mail, use empty crypt_write_algorithm setting:

crypt_write_algorithm =
crypt_global_private_key main {
  crypt_private_key_file = server.key
}

mail-crypt-plugin and ACLs ​

If you are using global keys, mails can be shared within the key scope. The global key can be provided with several different scopes:

  • Global scope: key is configured in dovecot.conf file
  • Per-user(group) scope: key is configured in userdb file

With folder keys, key sharing can be done to single user, or to multiple users. When a key is shared to a single user, and the user has a public key available, the folder key is encrypted using recipient's public key. This requires the mail_crypt_acl plugin, which will enable accessing the encrypted shared folders.

If you have crypt_acl_require_secure_key_sharing enabled, you can't share the key to groups or someone with no public key.

Decrypting Files Encrypted with mail-crypt Plugin ​

You can use decrypt.rb to decrypt encrypted files.

fs-crypt ​

fs-crypt is a lib-fs wrapper that can encrypt and decrypt files. It works similarly to the fs-compress wrapper. It can be used to encrypt e.g.:

Note that fs-crypt and the fs-compress plugin wrapper can be also combined. Please make sure that compression is always applied before encryption. See fs-compress plugin for an example and more details about compression.

fs-crypt settings ​

See Mail Crypt Plugin: Settings for generic mail-crypt settings.

WARNING

Changed: 2.4.0 fs-crypt requires encryption keys by default.

fs_crypt_read_plain_fallback

Defaultno
Valueboolean

If enabled files that are not encrypted are returned as-is. By default it results in a read error.

Doveadm Commands ​

TIP

For doveadm commands that are working with password protected keys, the global -o option should be used to provide the password. Example:

sh
doveadm -o crypt_private_password=some_password <...doveadm command...>

To encrypt/decrypt files manually, you can use:

sh
doveadm \
  -o fs=crypt,posix \
  -o fs/crypt/fs_driver=crypt \
  -o fs/posix/fs_driver=posix \
  -o crypt_private_key_file=pubkey.pem \
  -o crypt_global_private_key=main \
  -o crypt_global_private_key/main/crypt_private_key_file=privkey.pem \
  fs get/put '' path/to/input-file [/path/to/output-file]

mailbox cryptokey generate

Man Pagedoveadm-mailbox-cryptokey(1)

Generate new keypair for user or folder.

To generate new active user key and re-encrypt all your keys with it can be done with

sh
doveadm mailbox cryptokey generate -u username -UR

This can be used to generate new user keypair and re-encrypt and create folder keys.

INFO

You must provide a password if you want to generate password-protected keypair right away. You can also use doveadm mailbox cryptokey password to secure it.

CLI
HTTP API

Copyright © Open-Xchange GmbH