Enabling secrets encryption
By default EmailEngine stores all data in cleartext which is fine for testing but maybe not so much for production. This is why EmailEngine offers a field level encryption option that encrypts all sensitive fields like account passwords, access and refresh tokens.
By default EmailEngine stores all data in cleartext which is fine for testing but maybe not so much for production. This is why EmailEngine offers a field-level encryption option that encrypts all sensitive fields like account passwords, access and refresh tokens, settings value for Google OAuth client secret, etc. using aes-256-gcm cipher.
Encryption settings can not be changed during runtime. To start using encryption (or disabling it) you have to stop EmailEngine, perform encryption migration and then start EmailEngine with new encryption options.
Enabling encryption on a new instance
If you do not have any email accounts set up then this is the easiest solution. Set up an encryption secret and start EmailEngine, that's it. You can provide encryption secret using the EENGINE_SECRET
environment variable.
$ export EENGINE_SECRET="secret-password"
$ emailengine
In general you probably do not want to provide environment variables by using theexport
command from cli. Instead see the best option for your deployment solution. For example when running as a SystemD service, you could addEnvironment="EENGINE_SECRET=secret-password"
to the[Service]
section in the unit file. EmailEngine is also able to pick up the dotenv (/.env
) file from current working directory.
Enabling encryption on an existing instance
Even though you could use the same approach as with a new instance you probably should not. This would mean that while new email accounts would have encrypted secrets, all existing email accounts would still be in cleartext. So the setup path requires an additional step.
- Stop EmailEngine
- Run EmailEngine encryption migration tool to encrypt existing secrets
- Start EmailEngine with encryption options
The encryption tool is actually the same command you would normally use to start EmailEngine except it takes an additional argument encrypt
.
$ export EENGINE_SECRET="secret password"
$ emailengine encrypt --any.command.line.options
Running emailengine encrypt
instead of just emailengine
encrypts all existing secrets and then exits the application.
Changing encryption secret
If you have any reason to believe that your encryption secret has been leaked or you want to do regular secrets rollover you can use the emailengine encrypt
command. In this case, you would have to provide the previous secret for the command as well. EmailEngine would then decrypt the secret value, encrypt it with the new secret and then store it.
$ export EENGINE_SECRET="secret password"
$ emailengine encrypt --decrypt="old-secret" --any.command.line.options
If you have messed up your installation and have accounts encrypted with different secrets then you can provide these secrets separately.
$ export EENGINE_SECRET="secret password"
$ emailengine encrypt --decrypt="old-secret-1" --decrypt="old-secret-2" ...
Disabling encryption
This is similar to changing the secret except that you'd provide the old secrets but not a new one.
$ emailengine encrypt --decrypt="old-secret" --any.command.line.options
Using Vault
For improved security, you might not want to keep the encryption secret stored in the same server EmailEngine is running on. In this case, you could store it in Vault as a key-value secret.
EmailEngine would read the actual secret during application startup from Vault and never store it on the server. If anything happens you can revoke this specific application authentication credentials and it would not be able to fetch the secret anymore.
For all use cases using Vault is similar to the previously described actions except that you would not be using EENGINE_SECRET anymore.
EmailEngine is able to use AppRole authentication. You should provide Vault Role ID and Secret so that EmailEngine would be able to authenticate itself. In general, you would have to set the following environment variables:
VAULT_ADDR
is the URL of the Vault server, for example"http://127.0.0.1:8200"
VAULT_ROLE_ID
is the application's AppRole role ID, eg"887e1fdf-0d40-28e9-8d80-fd39b76dfe05"
VAULT_SECRET_ID
is the application's AppRole secret, eg"fe75beb8-c9cd-33b9-2d03-fcbd982b1f26"
VAULT_PATH
is the kv path to read from, eg."secret/data/emailengine"
VAULT_KEY
is an optional key to fetch from the Vault path, defaults to"secret"
Here's an example of VAULT_PATH=secret/data/emailengine
and VAULT_KEY=secret
(encryption secret resolves into "saladus2"):

In any case, once you have decided on encryption settings you have to keep using these, otherwise strange things will start to happen.