Bichon encrypts stored credentials. It does not encrypt the mail archive. This page states what that means in practice and where the protection has to come from instead.
What the encryption password does
BICHON_ENCRYPT_PASSWORD (or BICHON_ENCRYPT_PASSWORD_FILE) keys the values Bichon has to read back in plaintext later: IMAP passwords, OAuth tokens, and other stored secrets.
It protects those values at rest — when someone obtains a copy of the database or a backup without the password. It does not protect against someone who controls the running instance: they can read the password from the process environment, the key file, or memory, and decrypt anything the application can decrypt.
If neither setting is supplied, the binary falls back to a built-in placeholder (change-this-default-password-now). Treat that as no protection. Set one of the two options, do not set both, and keep a backup of the value — changing the encryption password later is not supported: there is no re-encryption step, and values encrypted under the old password cannot be read under a new one.
If the password is lost, stored credentials must be re-entered and re-authorized. Archived mail is not affected, but account sync will not work until the credentials are restored.
What is encrypted
- IMAP account passwords.
- OAuth2 client secrets, access tokens, and refresh tokens.
- The S3 access key and secret key of the backup target. The endpoint, region, and bucket are stored in plaintext.
- Values in the
system_configoverride collection (whole values encrypted). - Pro: the SIEM bearer token and HMAC signing secret.
Mechanism: AES-256-GCM via ring. Each value gets a random 32-byte salt and a random 12-byte nonce, and the key is derived with PBKDF2-HMAC-SHA256 at 100,000 iterations. The salt, nonce, and ciphertext are stored together as URL-safe base64.
User login passwords are a different mechanism: they are stored as Argon2id hashes, which cannot be reversed. Two exceptions: accounts created before the hash format existed still hold the old reversibly encrypted value until their next successful login, and a password set by bichon-admin reset is written in that old format until the admin logs in once.
What is not encrypted
- Message blobs — compressed with Zstd/Lz4, not encrypted.
- Tantivy indexes — envelope metadata and body text are plaintext.
memdb— the main metadata database. Account records, users, roles, and configuration live here; credential fields inside account records are the encrypted exception. Session and API tokens are stored as-is, and API tokens can be created without an expiry, so a copy ofmemdballows replaying live tokens until they expire.audit.db,integrity.db,anchor.db— plaintext SQLite files (Pro/Enterprise features).- Exports — MBOX and EML files are plaintext.
- Backup payloads — manifests and index packages are gzip-compressed, message blobs keep their compression, and nothing is encrypted by Bichon. Bichon sends no encryption headers; server-side encryption applies only if the bucket has a default (SSE-S3/SSE-KMS). A local backup directory is plaintext.
- TLS private key —
key.pemin the data root when built-in HTTPS is enabled.
Anyone with read access to the data root can read the archive without the encryption password.
Threat model
Two situations are easy to conflate:
- An offline copy leaks — a database file, a volume snapshot, a backup. Credential encryption helps here only if the copy does not also contain the password or key file; the archive is readable either way.
- The running host is compromised — root on the host, admin in the container, or equivalent. No application-level scheme helps: the process must be able to decrypt what it uses, so an attacker with the same access can do the same. This applies to any unattended, self-encrypting application, not just Bichon.
An unattended deployment that boots without human input cannot use an unlock that requires a human. Storing the key in a compose file, .env, or a file on the same disk does not change case 2; it only moves the plaintext.
Where to put the protection instead
- Encrypt the data root and any backup target at the storage layer (LUKS2, BitLocker, or the NAS equivalent). TPM2/Clevis auto-unlock stops disk removal and offline copies, but not someone who already controls the running machine.
- For S3 backups, enable SSE-S3 or SSE-KMS as the bucket default; Bichon does not add encryption headers itself. For local backups, use an encrypted volume.
- Run the container as a non-root user (see Quick Start), grant it only the mounts it needs, and keep host access restricted.
- Serve the REST API over HTTPS — built-in (
BICHON_ENABLE_REST_HTTPS=true) or behind a TLS-terminating reverse proxy. - Restrict
BICHON_CORS_ORIGINS; when it is unset, all origins are allowed. - Change the default admin password (
admin@bichon); the WebUI keeps a reminder while it still works. - Prefer expiring API tokens and revoke tokens that are no longer used.
- Prefer provider-side app-specific passwords or short-lived OAuth grants for IMAP accounts, so a leaked credential has a smaller blast radius.
- Apply least privilege with global and account-scoped roles — see Users & Access Control.
About encrypting the archive itself
We have considered encrypting message blobs with the same password and have not made it the default. Two reasons:
- The archive is irreplaceable, while credentials are not: a forgotten password can be fixed by re-entering an IMAP password, but a forgotten archive key means the mail is gone.
- In an unattended deployment the archive key would live on the same machine as the data, so it would add little against the case it is supposed to defend against. It would be roughly equivalent to full-disk encryption, with a much larger recovery and reindexing burden.
If this changes, it needs to be opt-in, with an explicit "losing the key loses the archive" acknowledgment and a recovery-key or envelope-encryption design. We are open to concrete proposals.
Related
- Storage & Backup — data directory layout, backup behavior, and target-side encryption.
- Configuration Reference —
BICHON_ENCRYPT_PASSWORD, HTTPS, CORS, and token lifetime.