Management

Stalwart exposes encryption-at-rest settings through the self-service portal, which allows end users to register their own keys and toggle encryption for their accounts without involving a system administrator. The same settings are reachable over the JMAP API (through the AccountSettings and PublicKey objects) and through the CLI.

Each account may register one or more PublicKey objects holding an OpenPGP public key or an S/MIME certificate. Encryption at rest is then activated by referencing one of these keys from the encryptionAtRest field on the AccountSettings singleton.

Enabling encryption

End users enable encryption from the self-service portal by performing two steps:

1. Register at least one public key as a PublicKey object. Upload the OpenPGP public key or S/MIME certificate and fill in description; optional fields include expiresAt and emailAddresses. The key material goes into key.
2. Update the AccountSettings singleton and set the encryptionAtRest field to the chosen algorithm variant, referencing the registered key by id.

The encryptionAtRest field accepts three variants: Disabled, Aes128, and Aes256. The Aes128 and Aes256 variants carry a publicKey identifier, an encryptOnAppend boolean controlling whether messages appended over JMAP or IMAP are also encrypted, and an allowSpamTraining boolean controlling whether the spam classifier is trained on the plaintext before encryption.

For example, enabling AES-256 encryption with a registered key:

{
  "encryptionAtRest": {
    "@type": "Aes256",
    "publicKey": "id1",
    "encryptOnAppend": false,
    "allowSpamTraining": false
  }
}

After registering a key and selecting an algorithm, send a test message to the account. The message should arrive encrypted, and the mail client must hold the corresponding private key to decrypt it. If decryption fails, verify that the client is configured with the matching private key for the OpenPGP public key, or the S/MIME certificate private key, that was uploaded to the server.

Disabling encryption

To disable encryption at rest for an account, update the AccountSettings singleton and set encryptionAtRest to the Disabled variant:

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

New messages are then stored in plain text. Messages encrypted while the feature was enabled remain encrypted on disk; disabling the setting does not decrypt existing content. Re-enabling encryption at a later point applies only to messages received afterwards and does not retroactively encrypt previously delivered messages.