Encryption at rest and the encryption key
This article explains how MobilityManager encrypts stored documents, where the encryption key comes from, and the one rule you must never break when rotating it.
Encryption at rest, on every provider
When encryption at rest is enabled, each file is encrypted before it is written to storage. This applies no matter which provider is active — Local, Azure Blob, or S3 all receive already-encrypted content. As a result, the folder, container, or bucket never holds a readable copy of your documents. Files are decrypted only when a user with permission downloads them. Encryption at rest is enabled by default.
How the encryption works
The platform uses AES-GCM, an authenticated encryption scheme, and wraps each file in a self-describing envelope. Because the envelope is authenticated, tampering with a stored file is detected at download time and the file will not decrypt. Every file gets a fresh random nonce, so identical files do not produce identical ciphertext.
The encryption key
Encryption uses a single 256-bit key, supplied as a base64-encoded 32-byte value. There are two ways to provide it:
| Source | How it is set |
|---|---|
| Database key | An operator sets a base64 key directly in the storage settings. This is preferred when present. |
| Configuration secret reference | A reference to a configuration key (for example an environment variable or secret store entry) that holds the key. |
If a database key is set, it takes priority; otherwise the platform resolves the key from the configured secret reference. For security, the raw key is never returned by the settings screen — the interface only indicates whether a key is present so it can offer rotation.
Rotating the key safely
The platform uses one active key with no key-ring and does not re-encrypt existing files when the key changes. This has a critical consequence:
Warning: If you change the encryption key, documents encrypted under the previous key can no longer be decrypted. There is no automatic re-encryption. Treat key changes as a one-way event and confirm you have no important documents under the old key before rotating.
To protect you from accidental loss, saving storage settings without providing a new key preserves the existing key rather than clearing it. The key only changes when you deliberately enter a new one. A new key must be a valid base64-encoded 32-byte value, or the save is rejected.
Backward compatibility
Files uploaded before encryption was enabled remain readable. On download, the platform detects whether a stored file is encrypted by checking the envelope, and returns plaintext files unchanged. This means enabling encryption does not break access to older documents — but only files written after it is enabled are actually encrypted.
Note: Managing the encryption key requires the settings:manage permission, typically held by SystemAdmin. Store a secure backup of the key outside the platform, because losing it means losing access to every document encrypted under it.
Related
- Where documents are stored: Local, Azure Blob, and S3 providers
- Configuring the document storage provider
- Tenant scoping and document isolation
- Document retention and permanent deletion
