Guides: storage & data

How to encrypt data at rest

This guide shows you how to enable at-rest encryption on a storage backend. Encryption is backend-scoped: every bucket routed to the backend inherits it. For the threat model behind each mode, see encryption at rest.

1. Pick a mode#

  • If the backend is a filesystem, or an S3 provider you don't fully trust with plaintext, use aes256-gcm-proxy — the proxy encrypts before the backend sees the bytes.
  • If the backend is AWS S3 and you want per-decrypt audit logs and KMS key management, use sse-kms; if AWS-managed AES256 is enough, use sse-s3.
  • If the bucket's contents are public anyway, keep none — encryption is pure overhead there.

The full mode matrix, field list, and wire format are in the encryption reference.

2. Generate and place the key (proxy-AES only)#

Generate a 32-byte hex key and put it in the proxy's environment — never in the config file. The env-var name is derived from the backend name (uppercase, -/. → _):

# for backend hetzner-fsn1
export DGP_BACKEND_HETZNER_FSN1_ENCRYPTION_KEY=$(openssl rand -hex 32)
# singleton-backend deployments use:
export DGP_ENCRYPTION_KEY=$(openssl rand -hex 32)

Before going further, store the key off-box — a secrets manager, an operator vault, a sealed envelope. If you lose a proxy-AES key, the encrypted objects on that backend are unrecoverable. The proxy does not escrow keys; there is no recovery path.

From the admin UI: Settings → Storage → Backends — each backend card has an encryption subsection with a mode dropdown and a key-generation widget. Keys are generated in-browser (crypto.getRandomValues) and never round-trip through the server before Apply; the panel shows a red key-loss banner and gates Apply behind an "I have stored this key safely" checkbox.

Enable encryption on a backend

3. Configure the backend#

One worked example per mode.

Proxy-AES on a named S3 backend — key comes from the env var in step 2, so no key field appears in YAML:

# validate
storage:
  default_backend: hetzner-fsn1
  backends:
    - name: hetzner-fsn1
      type: s3
      endpoint: https://fsn1.your-objectstorage.com
      region: fsn1
      force_path_style: true
      encryption:
        mode: aes256-gcm-proxy
        key_id: hetzner-2026-06    # optional but recommended — stamps objects with a stable key generation
  buckets:
    db-archive:
      backend: hetzner-fsn1

Proxy-AES on a singleton filesystem backend (no # validate here — the ${env:…} reference only expands when DGP_ENCRYPTION_KEY is set):

storage:
  backend:
    type: filesystem
    path: /var/lib/deltaglider_proxy/data
  backend_encryption:
    mode: aes256-gcm-proxy
    key: "${env:DGP_ENCRYPTION_KEY}"
    key_id: local-2026-06

SSE-KMS on an AWS backend — the proxy never touches key material; AWS does the crypto:

# validate
storage:
  default_backend: aws-dr
  backends:
    - name: aws-dr
      type: s3
      region: eu-west-1
      encryption:
        mode: sse-kms
        kms_key_id: arn:aws:kms:eu-west-1:123456789012:key/abcd-ef01
        bucket_key_enabled: true   # reduces per-request KMS cost

SSE-S3 on an AWS backend:

      encryption:
        mode: sse-s3

Note the native SSE modes are S3-only; the proxy rejects them on filesystem backends at config check.

4. Restart and verify#

Restart the proxy (or apply from the UI) so the env var and config load together, then prove the round trip:

  1. Write and read back through the proxy — clients must notice nothing:

    aws --endpoint-url https://s3.acme.example s3 cp dump.sql s3://db-archive/nightly/dump.sql
aws --endpoint-url https://s3.acme.example s3 cp s3://db-archive/nightly/dump.sql - | sha256sum

    The hash must match the original.

  2. Check the stored object is actually ciphertext — look at it on the raw backend, bypassing the proxy. In proxy-AES mode the body starts with the DGE1 magic (chunked) or is opaque GCM ciphertext, and the backend-side user metadata carries the dg-encrypted marker (an aes-256-gcm-* value) plus dg-encryption-key-id. On a filesystem backend the markers live in the user.dg.metadata xattr:

    xattr -p user.dg.metadata /var/lib/deltaglider_proxy/data/db-archive/nightly/dump.sql

    Native modes stamp dg-encrypted-native: sse-kms (or sse-s3) instead — that marker is harmless to expose.

  3. Old plaintext objects still read fine: the decrypt path dispatches on the marker, and absent marker means "serve as-is."

5. Encrypt the historical objects#

Enabling encryption is not retroactive — only new writes are encrypted; existing objects stay in their stored form. When you change a backend's encryption in the admin UI, the Backends page proposes a Re-encrypt job that rewrites every object not matching the new config.

Re-encrypt proposal

Accept it (or start one later from Settings → Jobs → + New job → Re-encrypt buckets…). The job write-gates each bucket while it runs and survives restarts — the mechanics, including what the write gate means for clients, are covered in How to rotate or change encryption keys.

Verify#

  • A fresh PUT through the proxy reads back byte-identical (step 4.1).
  • The raw backend stores ciphertext and the dg-encrypted / dg-encrypted-native marker (step 4.2).
  • The key is stored somewhere safe outside the proxy host.
  • If you ran a re-encrypt job, its row at Settings → Jobs shows succeeded and a raw-backend spot-check of an old object now shows the marker too.