Managing encryption

Encryption at rest is enabled per account, either by the account’s user or by an administrator. Two things are needed. The first is a registered public key, which is an OpenPGP key or an S/MIME certificate: the server encrypts with it, and only the matching private key can decrypt. The second is the account’s encryption setting, which selects that key and the cipher. Users manage both in the account manager of the WebUI, at /account.

The same data is available to administrators and scripts. In the API and the CLI, the keys are PublicKey objects, and the encryption setting is the encryptionAtRest field of the AccountSettings object. The account settings are found in the WebUI under Account › Settings. None of this takes effect unless encryption is also allowed server-wide, as described in Server-wide settings.

Enable encryption

Enabling encryption takes four steps: export the public key from the mail client, register it with the server, select it in the encryption settings, and confirm with a test message that the client can read what the server encrypts.

1. Export the public key or certificate from the mail client, as described in OpenPGP or S/MIME. The client must hold the private key, because it alone can decrypt the stored messages.

2. Register the key with the server. In the account manager, open the public keys under Account › Public Keys. Add a public key, paste the ASCII-armored OpenPGP key or the PEM certificate into it, and give it a description. This creates a PublicKey object whose key field holds the pasted text.

3. Select the key and a cipher in the encryption settings, and save. The setting is the encryptionAtRest field, and its variant selects the cipher:

   • Aes128 or Aes256: AES in CBC mode, for OpenPGP keys and S/MIME certificates.
   • Aes256Gcm or ChaCha20Poly1305: authenticated ciphers, for S/MIME certificates only. Selecting one with an OpenPGP key is refused with <algorithm> is only supported for S/MIME encryption, but the selected public key is an OpenPGP key.
   • Disabled: no encryption.

   Each variant other than Disabled carries the id of the key in publicKey and two switches. With encryptOnAppend, messages that the user’s clients store over JMAP or IMAP are also encrypted, provided the server allows it. With allowSpamTraining, the spam classifier learns from the plain text of the account’s messages before they are encrypted, which it otherwise cannot do.

4. Send a test message to the account and open it in the mail client, which should show it as encrypted and readable. When the client cannot decrypt it, the client does not hold the private key that matches the registered public key.

The following setting encrypts the account’s messages with AES-256 for a registered key:

{
  "encryptionAtRest": {
    "@type": "Aes256",
    "publicKey": "<public key id>",
    "encryptOnAppend": false,
    "allowSpamTraining": false
  }
}

The setting refers to a single PublicKey, but a PublicKey can hold more than one key. To encrypt for several keys, for example during a change of key, put all of them into the same PublicKey, as several armored keys or several certificates one after another.

Disable encryption

To stop encrypting new messages, set encryptionAtRest to Disabled:

{
  "encryptionAtRest": {"@type": "Disabled"}
}

New messages are then stored in plain text, but the change does not affect messages already stored. Messages stored while encryption was enabled stay encrypted and can only be read with the private key, because disabling the setting does not decrypt them. In the other direction, enabling it again does not encrypt the messages stored in the meantime.

The private key is the only way to read the encrypted messages, and the server cannot help recover them. Deleting a PublicKey that the setting refers to does not make old messages readable either, so the private key must be kept for as long as the messages are kept.