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, 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 the export command from cli. Instead see the best option for your deployment solution. For example when running as a SystemD service, you could add Environment="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.

1. Stop EmailEngine
2. Run EmailEngine encryption migration tool to encrypt existing secrets
3. 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.