Encryption & compliance

Vaks PM · Encryption, key management & DORA · June 2026

Overview & shared responsibility

Vaks PM is a project-management web application designed to run entirely on infrastructure the organization controls (on-premise: on its own servers rather than on a third-party online service). Encryption is applied at four independent layers, each protecting a different surface:

• Application fields. A narrow set of sensitive columns (for example email-relay passwords, multi-factor seeds and single-sign-on credentials) are encrypted inside the database by the application itself, using envelope encryption with per-tenant keys.
• Data-store volumes. The disks that hold the database and the object store are encrypted as a whole, so the entire dataset (not just the few secret fields) is protected at rest.
• In transit. Traffic is encrypted at the public edge (HTTPS) and on the internal hops between the application and its dependencies.
• Backups. Backup artifacts are encrypted before they leave the host.

Glossary

Acronyms and terms used throughout this guide, defined once here for reference.

DORA control mapping

DORA (the Digital Operational Resilience Act, EU Regulation 2022/2554) and its supporting technical standards are risk-based rather than prescriptive of any specific product. They require encryption of data at rest and in transit commensurate with data classification, plus a key-management policy covering the key lifecycle, rotation and separation of duties. A third-party HSM or KMS is not mandatory for compliance.

“Built-in” = active in every deployment. “Operator-enabled” = a control the operator turns on/provides from the infrastructure. “KMS/HSM” = external KEK custody, opt-in.

Data classification & encryption layers

Not all data is protected the same way. The application encrypts a small set of secrets at the field level; the bulk of the data (business data and personal data) relies on volume and transit encryption, because it must stay queryable. The table below shows which data sits at which classification and which layer protects it.

Envelope encryption (KEK → DEK → data)

The application encrypts its sensitive fields with envelope encryption, a two-layer key scheme:

• A DEK (Data Encryption Key), AES-256-GCM, 32 bytes, encrypts the actual fields. There is one DEK per tenant; all of that tenant's secrets are encrypted under its single DEK. The DEK is stored in the tenant database only in wrapped (encrypted) form, never in clear.
• A KEK (Key Encryption Key), AES-256-GCM, 32 bytes, encrypts ("wraps") the DEK. The KEK never touches the data itself; its only job is to lock and unlock DEKs. It lives outside the database, as a mounted key file or in an external KMS/HSM.

To read a secret, the application unwraps the tenant's DEK with the KEK, then decrypts the field with the DEK. To write one, it does the reverse. The diagram shows the relationship.

Step-by-step operational detail of the local key ring (generating and activating a KEK, the mounted key material and rotation) lives in the deployment guides: Docker Swarm and Kubernetes.

Key custody providers

The KEK is supplied by a key provider, selected by the CRYPTO_KEY_PROVIDER setting. Three providers exist; each stored key records which provider wrapped it, so providers can coexist during a migration. The default, the local key ring, is fully DORA-compliant on its own; the external providers add hard separation of duties, where no application administrator can export the key.

The provider configuration variables (CRYPTO_KMS_*, CRYPTO_HSM_*), the HSM key-broker sidecar, and the per-orchestrator placement of these settings are configured in the deployment guides: Kubernetes and Docker Swarm.

Migrating custody

Because each stored key records the provider that wrapped it, a migration between providers is online and reversible: no downtime, no data re-encryption. The outline:

1. Configure the new provider and set CRYPTO_KEY_PROVIDER to kms or hsm, then roll the services. New DEKs are now wrapped by the new provider; existing ones still unwrap via their current provider, so a mix is expected and correct.
2. In Admin → Security & Compliance → Encryption keys, click Rotate KEK. Every DEK is unwrapped with its current provider and re-wrapped under the new one. Repeat per tenant.
3. Watch the data-key distribution until every key shows the new provider's scheme, then run a decrypt check (sign in, or open a settings page that reads an encrypted value).
4. Reversible: keep the previous provider's key material available until verified. Rollback is setting CRYPTO_KEY_PROVIDER back and re-running Rotate KEK.

Key rotation

Two distinct rotations exist, with very different costs. Both are driven from Admin → Security & Compliance → Encryption keys and require the crypto:manage permission; both are written to the audit log.

Rotation & incident runbook

The response to a suspected key compromise depends on which key is involved. Record every incident; the audit log evidences each key operation with actor, time and outcome.

Volume encryption at rest

Field-level encryption protects only the secrets. To protect the entire dataset on disk (the database files and the object-store files) the data volumes themselves are encrypted. This is the layer that the operator provides; the approach differs by orchestrator.

Docker Swarm: LUKS2 with network-bound unlock (Clevis + Tang)

On the self-managed Swarm topology, the bootstrap provisions LUKS2 file-backed volumes for the data stores. Two volumes are created:

• the database data volume, mounted where PostgreSQL keeps its data (so it is encrypted before the database initializes into it);
• the object-store volume, mounted where the S3 server keeps its objects.

Each volume is formatted with cipher aes-xts-plain64 and a 512-bit key. Only the data volumes are encrypted, not the host OS disk and not other workloads.

The challenge with at-rest encryption is unlocking the volume at boot without a human typing a passphrase. Vaks PM solves this with network-bound disk encryption using Clevis and Tang:

• A Tang server is a tiny, stateless network key server (it holds no per-client secret). On each host it listens on an internal-network port; a host's volumes are bound to the Tang servers running on its peer hosts (never itself).
• Clevis binds the LUKS volume to a policy. The policy uses Shamir's Secret Sharing (SSS) with a threshold of 1 across the peer Tang servers: the volume unlocks automatically as long as at least one peer Tang server is reachable.
• At boot, a small unlock-and-mount helper runs before the database (and before Docker for the object store), waits for a peer Tang server, unlocks the volume via Clevis and mounts it. The application services then start on top of an already-mounted, decrypted volume.

The exact bootstrap commands (installing Tang, building the Clevis SSS policy, formatting and binding each volume, and the ordering relative to the database start-up) are in Docker Swarm deployment. This section describes what those steps do and the policy behind them.

Kubernetes: encrypted StorageClass

On Kubernetes the equivalent is an encrypted StorageClass, delegated to the platform: the database, cache and object-store persistent volumes are provisioned from a class backed by the cloud provider's key-managed block storage, a Container Storage Interface (CSI) driver with encryption, or nodes with encrypted disks. When the dependencies are external/managed (for example a managed database service), use that provider's own at-rest encryption instead. This is an install-time choice: changing it on a running cluster means migrating volume data. See Kubernetes deployment and the encryption-layer detail it links.

Internal TLS & custom CA

Encryption covers the public edge (HTTPS at the reverse proxy) and the product's internal traffic as well. Three internal flows are encrypted:

A fresh install runs internal TLS out of the box with self-signed certificates: traffic is encrypted, but the peer's identity is not verified. Replacing those with certificates issued by the organization's own CA (Certificate Authority) adds identity verification, which protects against an active man-in-the-middle.

Certificate specification (the key points)

• One shared certificate can cover the internal components, with its SAN (Subject Alternative Name) listing all host IP addresses (Swarm) or the database service name (Kubernetes), plus 127.0.0.1 / localhost. The legacy Common Name field is no longer honored, so populating the SAN is mandatory.
• Extended Key Usage must be both serverAuth and clientAuth. The coordination store uses mTLS (each node is both a server, since it listens, and a client, since it calls its peers), so a server-only certificate is rejected. This is the single most common mistake: corporate CAs often issue server-only certificates.
• Key type RSA ≥ 2048 bits or ECDSA P-256; SHA-256 minimum signature; validity per the CA's policy (plan for rotation before expiry).

From CSR to deployment

Produce a CSR (Certificate Signing Request) carrying the SAN and the dual EKU, have the internal CA sign it (requiring that it preserves the SAN and EKU and returns the chain), and deploy three PEM files: the leaf certificate, its private key (unencrypted, 600 permissions, owned by the service user), and the CA certificate used as the trust anchor. On Swarm the files go on each host under /etc/vaks/ and the trust anchors are re-pointed at the CA one node at a time, to preserve availability. On Kubernetes the certificate is supplied as a Secret (or issued by cert-manager) and the application verifies the database with PG_TLS / PG_TLS_CA / PG_TLS_MODE.

The per-orchestrator file placement, the supply of a custom Certificate Authority and the verification commands are covered in the deployment guides: Docker Swarm and Kubernetes.

GDPR: erasure & portability

Encryption protects data confidentiality; GDPR (the EU General Data Protection Regulation) governs how personal data is handled. Vaks PM implements two relevant data-subject rights as product features:

• Right to erasure (Art. 17) by pseudonymization. Deleting a person's records would break the time, finance and audit aggregates that reference them, so instead the product overwrites the personal data (name, email and other identifiers are replaced with a non-identifying pseudonym) while keeping the foreign keys intact. The PII is gone; the historical aggregates survive and the audit log's integrity is unaffected. The operation is idempotent and audited.
• Right to data portability (Art. 20) by self-export. A user can export their own data (profile, time entries, allocations, comments, skills and attachment metadata) as a structured file; secrets are excluded. An administrator can perform the export on a user's behalf.

These features and their administration are described in the product guide: see Product: GDPR (anonymization & portability).

Encrypted backups

Backup artifacts are encrypted at creation with age, an asymmetric (public-key) scheme: a public recipient key sits on the host and seals each artifact, while the matching private key is held in escrow off-cluster. The host can therefore create encrypted backups but cannot, on its own, decrypt them.

Because the KEK lives outside the database, a database backup contains only the wrapped per-tenant DEKs plus ciphertext. Restoring it works only if the key ring still holds the KEK that wrapped those DEKs. Two coordination rules follow:

• Back up the key material separately from the database (the KEK material and the backup age private key), with retention at least as long as the database backups that reference them. A database backup alone cannot be decrypted without its keys.
• Snapshot a key inventory alongside each backup set. Record which KEK the DEKs were wrapped under and which age recipient the artifacts were sealed to, so a future operator knows exactly which keys a given backup needs.

Lock-out recovery & escrow

The escrow inventory every operator must maintain off-cluster:

Verification checklist

Confirm each layer is active before relying on it:

• Field-level encryption. GET /admin/crypto/status (or the admin panel) returns the active KEK provider, the active KEK and the distribution of DEKs by KEK. After a rotation, confirm every DEK references the intended KEK. The application start-up log also lists the loaded key ring and the active key.
• Decrypt check. Sign in, or open an admin settings page that reads an encrypted value (for example the notification / SMTP settings), to confirm secrets decrypt end to end.
• Volume encryption (Swarm). The data volumes appear as LUKS-mapped devices and unlock automatically at boot via Clevis/Tang; confirm the unlock-and-mount unit ran before the database started.
• Volume encryption (Kubernetes). The persistent volumes are bound to an encrypted StorageClass; confirm the class in use.
• External edge TLS. The organization's host name loads over HTTPS with a valid certificate.
• Internal TLS. The database reports ssl on and shows encrypted connections; the coordination store reports healthy; with a custom CA, openssl verify against the database returns code 0.
• Backups. Backup artifacts are encrypted to the configured age recipient and shipped off the cluster; a restore drill succeeds against the escrowed keys.
• Audit integrity. The daily integrity anchor verifies; the verification endpoint reports no tampering.

Related: The application · Technical architecture · Docker Swarm deployment · Kubernetes deployment · Operations · Demo