From c4e4aab7499ea32b39333720d213c9b6e6250448 Mon Sep 17 00:00:00 2001 From: Aki Tuomi Date: Wed, 4 Sep 2024 11:38:20 +0300 Subject: [PATCH] mail_crypt: Document supported ciphers --- .github/actions/spelling/allow.txt | 1 + docs/core/plugins/mail_crypt.md | 44 ++++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+) diff --git a/.github/actions/spelling/allow.txt b/.github/actions/spelling/allow.txt index 994732129..41a940f44 100644 --- a/.github/actions/spelling/allow.txt +++ b/.github/actions/spelling/allow.txt @@ -2,6 +2,7 @@ bitmask bitmasks configurations DOkv +ede github https iostream diff --git a/docs/core/plugins/mail_crypt.md b/docs/core/plugins/mail_crypt.md index b4e84b9b2..91cec04b3 100644 --- a/docs/core/plugins/mail_crypt.md +++ b/docs/core/plugins/mail_crypt.md @@ -5,6 +5,9 @@ dovecotlinks: fs_crypt: hash: fs-crypt-and-fs-mail-crypt text: fs-crypt + supported_sym_algorithms: + hash: supported-symmetric-algorithms + text: Supported symmetric algorithms --- # Mail Crypt (mail-crypt) Plugin @@ -69,6 +72,47 @@ compatibility issues. +### 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 algorithm | Supported size | Supported modes | +| -------------------- | -------------- | --------------- | +| [chacha20](https://en.wikipedia.org/wiki/ChaCha20) | - | [poly1305](https://en.wikipedia.org/wiki/ChaCha20-Poly1305)1,3 | +| [aes](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) | 128, 192, 256 | [gcm](https://en.wikipedia.org/wiki/Galois/Counter_Mode)1, [cbc](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#CBC)2 | +| [camellia](https://en.wikipedia.org/wiki/Camellia_(cipher)) | 128, 192, 256 | [cbc](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#CBC)2 | +| [aria](https://en.wikipedia.org/wiki/ARIA_(cipher)) | 128, 192, 256 | [cbc](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#CBC)2 | +| [seed](https://en.wikipedia.org/wiki/SEED) | - | [cbc](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#CBC)2 | +| [sm4](https://en.wikipedia.org/wiki/SM4_(cipher)) | - | [cbc](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#CBC)2 | +| [des-ede3](https://en.wikipedia.org/wiki/Triple_DES) | - | [cbc](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#CBC)2 | + +1 Uses [AEAD](https://en.wikipedia.org/wiki/AEAD) integrity. + +2 Uses [HMAC](https://en.wikipedia.org/wiki/HMAC) integrity. + +3 Requires recent enough OpenSSL. + ### Dynamic Settings Plugin settings may be dynamically set via [[link,userdb_extra_fields]].