Skip to content

Installation

This page installs the vault site, which every deployment needs. In the primary remote topology you then set up one or more separate consumer sites that reach the vault over HTTP - follow Client-server configuration for that (it is the main path). For a single-site deployment, install the vault here and add a same-site consumer such as PDV Webform.

Requirements

  • Drupal 11, PHP 8.2 or newer, with the PHP sodium extension.
  • Key and Consumers.

Install the module

composer require drupal/pdv
drush en pdv

This enables pdv and its dependencies and installs a starter set of item kinds.

Configure the Master KEK

The vault cannot encrypt anything until a 256-bit Master KEK is configured through the Key module.

  1. Create a key at Configuration -> System -> Keys (/admin/config/system/keys):
    • Key type: Encryption, 256 bits.
    • Key provider: your choice. For local development the configuration provider is fine; for production keep the root key out of Drupal by holding the Master KEK in OpenBao or HashiCorp Vault instead (see Master KEK in OpenBao or Vault).
  2. Point the vault at it at Configuration -> Personal Data Vault (/admin/config/pdv/settings):
    • Master KEK: select the key you just created.
    • Consent request lifetime: how long a pending store request stays valid, in seconds (default 900).
    • Inline body storage threshold (bytes): bodies at or below this size are stored encrypted inline in the item row; larger bodies are stored as an encrypted file. Default 0 (always use a file).

The Master KEK must resolve to exactly 32 bytes. It cannot be deleted while it still protects vault data: the key's delete form is blocked when the key is the current Master KEK or still wraps any user key. Pointing this setting at a different key keeps existing data readable under the previous key (each user key records the Master KEK it was wrapped under), so the old key must be kept until a full re-wrap. After changing the Master KEK, drain the re-wrap backlog from Vault subjects -> Rotate to current Master KEK (under /admin/config/pdv/subjects): it re-wraps every user key in bounded batches and reports progress. Cron advances the same backlog automatically, and drush pdv:rotate-keys drains it from the command line. On a multi-tenant site this is per tenant - the action and the drush command (drush pdv:rotate-keys <tenant>) act on one tenant at a time. Once no subject is left on the old key, the old key can be retired. Losing the key material itself (for example wiped from an external secrets store) is unrecoverable, so treat it like any other root secret.

Permissions

Permission Grants
manage own pdv vault Use one's own vault: upload, review requests, grant/revoke, manage trusted consumers.
administer pdv item kinds Manage the controlled vocabulary of kinds.
administer pdv tenants Create and configure vault tenants and their per-tenant Master KEK.
administer pdv Configure module settings, including the Master KEK.
use pdv test console Use the developer consumer simulator (dev only).

administer pdv, administer pdv item kinds, administer pdv tenants, and use pdv test console are marked as restricted; grant them only to trusted roles.

Operator tools

With administer pdv, a Vault subjects report (Configuration -> Personal Data Vault -> Vault subjects) lists every vault subject with item count, total size, Master KEK (flagged when not the current one), creation date and last access. From there an operator can, without ever seeing item content:

  • Manage access for a subject - view their grants, trusted consumers and pending requests plus a structural item list (kinds and sizes only, never labels, filenames or bodies) - and revoke grants/trust or decline requests. Operators cannot grant new access, approve requests, or upload.
  • Purge a subject's vault (crypto-erase of everything) while keeping the user account. Purging the account itself also purges the vault.

Cron

pdv relies on cron for routine vault hygiene, so the site must run cron on a schedule. On each run, in bounded chunks, pdv:

  • expires pending store requests past the configured lifetime;
  • advances the Master KEK re-wrap backlog (see above);
  • reaps stale rows - expired grants and trusts, abandoned consent requests, and rows orphaned by an interrupted purge - so these tables stay bounded on a large site.

Everything here is bounded per run, so it is safe on busy sites. A site that never runs cron will accumulate expired and orphaned rows indefinitely.

Optional submodules

  • PDV Webform (pdv_webform) - a Webform element to upload a file or reuse a vault document in a form.
  • PDV Test Console (pdv_test_console) - a consumer simulator for testing the sharing flows.

See Submodules.

Cross-site (consumer) setup

The steps above set up a single-site vault, where any consumer (such as a Webform) lives on the same Drupal site. To let a separate site read and write the vault over HTTP - the client-server topology, using OAuth and the pdv_client / pdv_server_api modules - follow Client-server configuration. As with the Master KEK, the consumer's OAuth client secret is held in a Key, never in configuration.