Skip to content

Personal Data Vault

Personal Data Vault (pdv) is a Drupal module for storing a user's files and structured data encrypted at rest, and for sharing them with workflows or external API consumers on a case-by-case basis.

It is built around one rule: a database dump, a stolen disk, or a backup tape must reveal nothing. Every item body is encrypted, and so is its metadata (label, filename, MIME type). On disk the ciphertext files carry opaque random names with no extension, so even the file listing leaks nothing about content.

What it does

  • Encrypts everything at rest with libsodium AEAD, under a three-tier key hierarchy (see Concepts).
  • Categorizes documents and records with a controlled vocabulary of kinds (see Item kinds and records).
  • Stores two payload types: documents (uploaded files) and records (structured fields such as a civil-status record), handled the same way for sharing.
  • Mediates access: a consumer is identified before it can be granted anything, and consent is captured on the vault site.
  • Shares per item or per kind: one-off grants, owner-approved requests, and standing read/write pre-authorizations ("trust").
  • Erases cryptographically: deleting a document destroys its key material so the ciphertext becomes permanently unrecoverable.

Deployment topologies

PDV is built primarily for a central vault with remote consumers: the vault runs on one Drupal site, and separate consumer sites read and write a user's data over an authenticated HTTP API (OAuth client-credentials), gated by the owner's consent. This is the main, intended deployment - see Client-server configuration and the API reference.

The same code also runs same-site, where a consumer (such as a Webform) lives on the vault site itself and talks to it in-process. The consumer code is identical either way - one VaultClientInterface, answered by a local or a remote client depending on which the site installed - so same-site is handy for a single-site deployment or local development.

Modules

A site picks its role by the modules it enables. The vault site enables pdv_engine, and pdv_server if other sites use it. A consumer site enables pdv_client instead. Every module that reads or writes a vault, such as pdv_webform, works the same on both.

  • Personal Data Vault (pdv) is the contract: VaultClientInterface, the one service every consumer drives. It holds no data. It is never enabled by hand: it arrives with the modules that need it, and the Extend page does not list it.
  • PDV Engine (pdv_engine) keeps the vaults on this site: the encrypted items, the keys, the grants and the consent ceremony.
  • PDV Server (pdv_server) lets consumers on other sites reach the vaults on this one, over an OAuth-protected HTTP API.
  • PDV Client (pdv_client) reaches a vault on another site, for a consumer site that keeps no vault of its own.

The other modules are described in Submodules.

Requirements

  • Drupal 11.3 or Drupal 12, PHP 8.2+, the PHP sodium extension.
  • Key - holds the Master KEK on the vault, and the OAuth client secret on a remote consumer.
  • Consumers - identifies the parties that request access.
  • For the remote topology: Simple OAuth on the vault (provider) and the pdv_client module on each consumer.

See Installation to get started, or jump straight to Client-server configuration for the remote setup.

Project