Configuring the document encryption-at-rest key

MobilityManager can encrypt uploaded documents at rest when they are stored on local storage. This is controlled by the DocumentStorage configuration section. This article explains the encryption key requirement and how to configure it safely.

The DocumentStorage section

Two keys govern encryption at rest, both under the root DocumentStorage section:

• DocumentStorage:EnableEncryptionAtRest — turns encryption on or off. It defaults to on.
• DocumentStorage:LocalEncryptionKey — the key used to encrypt and decrypt local documents.

Note: If you previously configured these under DamageManagement:DocumentStorage:*, migrate to the root DocumentStorage keys. The old location is no longer used.

Startup enforcement

Outside the Development environment, the application fails to start if encryption at rest is enabled but no key is configured. The startup check applies when DocumentStorage:EnableEncryptionAtRest is on (or left at its default) and DocumentStorage:LocalEncryptionKey is empty. The error instructs you to supply a base64-encoded 32-byte key or to disable encryption at rest.

Warning: The key is intentionally not committed to appsettings.json. A deployed instance with encryption enabled must supply the key through an environment variable or secret store.

Generate a key

The key must be a base64-encoded 32-byte value:

openssl rand -base64 32

Use the entire output as the value of DocumentStorage__LocalEncryptionKey.

Provide the key by environment

• Docker / Compose / published: set the environment variable

  DocumentStorage__LocalEncryptionKey=base64-32-byte-key
  DocumentStorage__EnableEncryptionAtRest=true

• Kubernetes: keep DocumentStorage__EnableEncryptionAtRest in the ConfigMap and place DocumentStorage__LocalEncryptionKey in the Secret.

If you do not need encryption

To run without encryption at rest — for example on evaluation systems — explicitly disable it:

DocumentStorage__EnableEncryptionAtRest=false

With the feature disabled, no key is required and the startup check is skipped.

Warning: Treat the encryption key like any other secret and back it up securely. If you lose it, previously encrypted documents cannot be decrypted. Rotating the key requires re-encrypting existing content.

Related

• Setting the JWT signing key for production
• Configuring environment variables and the .env file
• Production hardening checklist
• Troubleshooting a failed startup