Edit File: Plugins.MailCrypt.txt
mail-crypt-plugin ================= Contents 1. mail-crypt-plugin 1. Introduction 1. Functional Overview 2. Encryption Technologies 2. Technical Requirements 3. Settings for mail crypt plugin 4. Modes of operation 5. Folder keys 1. Unencrypted user keys 2. Encrypted user keys 6. Global keys 1. RSA key 2. EC key 3. Converting EC key to PKEY 4. Base64 encoded keys 7. New dcrypt format (mail_crypt_save_version = 2) 8. Old dcrypt format (mail_crypt_save_version = 1) 9. Read-only mode (mail_crypt_save_version = 0) 10. mail-crypt-plugin and ACLs 11. decrypting files encrypted with mail-crypt plugin 12. fs-crypt and fs-mail-crypt 2. doveadm plugin 1. doveadm mailbox cryptokey generate 2. doveadm mailbox cryptokey list 3. doveadm mailbox cryptokey export 4. doveadm mailbox cryptokey password Introduction ------------ 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 usedstandards 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 ---------------------- This feature is available in v2.2.27+. Using per-folder keys is not considered production quality, but global keys are fine. *NB! Improper configuration or use can make your emails unrecoverable. Treat encryption with care and backups.* mail-crypt-plugin encrypts and decrypts mail. The plugin has an older version, and the extent of this version's backward compatibility is controlled by the setting *mail_crypt_save_version*. The setting has three valid values, of which one must be set for the plugin to do anything. The values are 0 and 2. With *mail_crypt_save_version = 2*, mails are saved in dcrypt version 2 format, and this is the value that should be used. With *mail_crypt_save_version = 0*, the plugin does not write encrypted mails, but can still read them. To provide *mail_crypt_global_private_key* and *mail_crypt_global_public_key* as userdb attributes, you can base64 encode the original contents, such as PEM file. For example, ---%<------------------------------------------------------------------------- cat ecprivkey.pem | base64 -w0 ---%<------------------------------------------------------------------------- Settings for mail crypt plugin ------------------------------ These all go into userdb environment or under plugin { } * *mail_crypt_save_version* - Save format, 0 = read only, 2 = current version * *mail_crypt_curve* - EC curve to use for key generation * *mail_crypt_global_private_key(_n)* - Private key to decrypt files, you can specify many * *mail_crypt_global_public_key* - Public key to use to encrypt files, you can specify one * *mail_crypt_private_key* - Private key to decrypt user's master key, can be base64 encoded * *mail_crypt_private_password* - Password to decrypt user's master key or environment private key * *mail_crypt_acl_require_secure_key_sharing* - Require secure key sharing * *mail_crypt_require_encrypted_user_key* - Require user key encryption with password All external keys must be in PEM format, using pkey format. Modes of operation ------------------ Mail crypt plugin can operate using *either* global keys *or* folder keys. Using both is not supported. To perform any encryption,*mail_crypt_save_version* must be specified and non-zero. Folder keys ----------- In this mode, the user is generated a key pair, and each folder is generated a key pair, which is encrypted using the user's key pair. A user can have more than one key pair but only one can be active. You must use save version 2. You must also specify *mail_crypt_curve*. Any valid curve supported by underlying cryptographic library is supported.*mail_attribute_dict* has to be set since it is used to store the keys. Unencrypted user keys --------------------- In this version of the folder keys mode, the users private key is stored unencrypted on the server. Example config for folder keys with Maildir: ---%<------------------------------------------------------------------------- mail_attribute_dict = file:%h/Maildir/dovecot-attributes mail_plugins = $mail_plugins mail_crypt plugin { mail_crypt_curve = secp521r1 mail_crypt_save_version = 2 } ---%<------------------------------------------------------------------------- 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_attribute_dict = file:%h/Maildir/dovecot-attributes mail_plugins = $mail_plugins mail_crypt plugin { mail_crypt_curve = secp521r1 mail_crypt_save_version = 2 mail_crypt_require_encrypted_user_key = yes } ---%<------------------------------------------------------------------------- The password that is used to decrypt the users master/private key, must be provided via password query: ---%<------------------------------------------------------------------------- # File: /etc/dovecot/dovecot-sql.conf.ext password_query = SELECT \ email as user, password, \ '%w' AS userdb_mail_crypt_private_password \ FROM virtual_users WHERE email='%u'; ---%<------------------------------------------------------------------------- Global keys ----------- In this mode, all keying material is taken from plugin environment. You can use either EC keys (recommended) or RSA keys. No key generation is performed. RSA key ------- Use of RSA keys is discouraged, please use Elliptic Curve keys instead. You can generate an unencrypted RSA private key in the pkey format with the command: ---%<------------------------------------------------------------------------- openssl genpkey -algorithm RSA -out rsaprivkey.pem ---%<------------------------------------------------------------------------- Alterantively, you can generate a password encrypted private key with: ---%<------------------------------------------------------------------------- openssl genpkey -algorithm RSA -out rsaprivkey.pem -aes-128-cbc -pass pass:qwerty ---%<------------------------------------------------------------------------- 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: ---%<------------------------------------------------------------------------- openssl pkey -in rsaprivkey.pem -pubout -out rsapubkey.pem ---%<------------------------------------------------------------------------- These keys can then be used by mail-crypt-plugin with the configuration: ---%<------------------------------------------------------------------------- mail_plugins = $mail_plugins mail_crypt plugin { mail_crypt_global_private_key = <rsaprivkey.pem mail_crypt_global_private_password = qwerty mail_crypt_global_public_key = <rsapubkey.pem mail_crypt_save_version = 2 } ---%<------------------------------------------------------------------------- EC key ------ In order to generate an EC key, you must first choose a curve from the outputof this command: ---%<------------------------------------------------------------------------- openssl ecparam -list_curves ---%<------------------------------------------------------------------------- If you choose the curve prime256v1, generate and EC key with the command: ---%<------------------------------------------------------------------------- openssl ecparam -name prime256v1 -genkey | openssl pkey -out ecprivkey.pem ---%<------------------------------------------------------------------------- Then generate a public key out of your private EC key ---%<------------------------------------------------------------------------- openssl pkey -in ecprivkey.pem -pubout -out ecpubkey.pem ---%<------------------------------------------------------------------------- These keys can now be used with mail-crypt-plugin with the configuration: ---%<------------------------------------------------------------------------- mail_plugins = $mail_plugins mail_crypt plugin { mail_crypt_global_private_key = <ecprivkey.pem mail_crypt_global_public_key = <ecpubkey.pem mail_crypt_save_version = 2 } ---%<------------------------------------------------------------------------- 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: ---%<------------------------------------------------------------------------- openssl pkey -in oldkey.pem -out newkey.pem ---%<------------------------------------------------------------------------- Then newkey.pem can be used with mail-crypt-plugin. Base64 encoded keys ------------------- Mail-crypt plugin can read keys that are base64 encoded. This is intended mostly for providing PEM keys via userdb. Hence, this is possible: ---%<------------------------------------------------------------------------- openssl ecparam -name secp256k1 -genkey | openssl pkey | base64 -w0 > ecprivkey.pem base64 -d ecprivkey.pem | openssl ec -pubout | base64 -w0 > ecpubkey.pem ---%<------------------------------------------------------------------------- ---%<------------------------------------------------------------------------- passdb { driver = static args = password=pass mail_crypt_global_public_key=<content of ecpubkey.pem> mail_crypt_global_private_key=<content of ecprivkey.pem> } mail_plugins = $mail_plugins mail_crypt plugin { mail_crypt_save_version = 2 } ---%<------------------------------------------------------------------------- New dcrypt format (mail_crypt_save_version = 2) ----------------------------------------------- The recommended setting of *mail_crypt_save_version* for new installations of mail-crypt-plugin is 2. Old dcrypt format (mail_crypt_save_version = 1) ----------------------------------------------- Do not use this. It is supported for legacy reasons only and should not be used to create new files. It will not work without a global key. Read-only mode (mail_crypt_save_version = 0) -------------------------------------------- If you have encrypted mailboxes that you need to read, but no longer want to encrypt new mail, use *mail_crypt_save_version = 0*: ---%<------------------------------------------------------------------------- plugin { mail_crypt_save_version = 0 mail_crypt_global_private_key = <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 multiple users. When key is shared to single user, and the user has public key available, the folder key is encrypted to recipient's public key. If you have *mail_crypt_acl_require_secure_key_sharing* plugin setting, 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 [https://gist.github.com/cmouse/882f2e2a60c1e49b7d343f5a6a2721de] to decrypt encrypted files. fs-crypt and fs-mail-crypt -------------------------- The 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.: * FTS index objects (fts_dovecot_fs) * External mail attachments (mail_attachment_fs) fs-crypt comes in two flavors, mail-crypt and crypt. mail-crypt is intended to be used with user context, while crypt can be used elsewhere. Currently the fs-crypt plugin requires that all the files it reads are encrypted. If it sees an unencrypted file it'll fail to read it. The plan is to fix this later. FS driver syntax: *crypt:[algo=<s>:][set_prefix=<n>:][private_key_path=/path:][public_key_path=/path:][password=password:]<parent fs>* where: * *algo*: Encryption algorithm. Default is aes-256-gcm-sha256. * *set_prefix*: Read _public_key and _private_key under this prefix. Default is "mail_crypt_global". * *private_key_path*: Path to private key * *public_key_path*: Path to public key * *password*: Password for decrypting public key Example: ---%<------------------------------------------------------------------------- plugin { fts_index_fs = crypt:set_prefix=fscrypt_index:posix:prefix=/tmp/fts fscrypt_index_public_key = <server.pub fscrypt_index_private_key = <server.key } ---%<------------------------------------------------------------------------- To encrypt/decrypt files manually, you can use ---%<------------------------------------------------------------------------- doveadm fs get/put crypt private_key_path=foo:public_key_path=foo2:posix:prefix=/path/to/files/root path/to/file ---%<------------------------------------------------------------------------- doveadm plugin ============== Following commands are made available via doveadm. doveadm mailbox cryptokey generate ---------------------------------- ---%<------------------------------------------------------------------------- doveadm [-o plugin/mail_crypt_private_password=some_password] mailbox cryptokey generate [-u username | -A] [-Rf] [-U] mailbox-mask [mailbox-mask ...] ---%<------------------------------------------------------------------------- Generate new keypair for user or folder. * -o - Dovecot option, needed if you use password protected keys * -u - Username or mask to operate on * -A - All users * -R - Re-encrypt all folder keys with current active user key * -f - Force keypair creation, normally keypair is only created if none found * -U - Operate on user keypair only To generate new active user key and re-encrypt all your keys with it can be done with ---%<------------------------------------------------------------------------- doveadm mailbox cryptokey generate -u username -UR This can be used to generate new user keypair and re-encrypt and create folder keys. ---%<------------------------------------------------------------------------- Note that you must provide password if you want to generate password-protected keypair right away. You can also use doveadm mailbox cryptokey password to secure it. doveadm mailbox cryptokey list ------------------------------ ---%<------------------------------------------------------------------------- doveadm mailbox cryptokey list [-u username | -A] [-U] mailbox-mask [mailbox-mask ...] ---%<------------------------------------------------------------------------- * -u - Username or mask to operate on * -A - All users * -U - Operate on user keypair only Will list all keys for user or mailbox. doveadm mailbox cryptokey export -------------------------------- ---%<------------------------------------------------------------------------- doveadm [-o plugin/mail_crypt_private_password=some_password] mailbox cryptokey export [-u username | -A] [-U] mailbox-mask [mailbox-mask ...] ---%<------------------------------------------------------------------------- * -u - Username or mask to operate on * -A - All users * -U - Operate on user keypair only Exports user or folder private keys. doveadm mailbox cryptokey password ---------------------------------- ---%<------------------------------------------------------------------------- doveadm mailbox cryptokey password [-u username | -A] [-N | -n password] [-O | -o password] [-C] ---%<------------------------------------------------------------------------- * -u - Username or mask to operate on * -A - All users * -N - Ask new password * -n - New password * -O - Ask old password * -o - Old password * -C - Clear password Sets, changes or clears password for user's private key. (This file was created from the wiki on 2019-02-05 04:42)
Back to File Manager