Problem/Motivation

The pdv_vault submodule can hold the Master KEK in OpenBao or HashiCorp Vault Transit. The Transit key can be rotated in place (for example bao write -f transit/keys/pdv-master/rotate), which adds a new key version. New Subject KEKs then wrap under the new version automatically, and existing ones keep decrypting under the old version (Transit's min_decryption_version), but pdv never migrates the existing subjects onto the new version.

This is because Master KEK rotation converges subjects by the Master KEK Key-entity id (master_key_id), not by the Transit key version: SubjectKeyManager::rewrap() short-circuits when the id is unchanged, so an in-place version bump yields zero pending and re-wraps nothing.

The consequence is that an operator cannot safely retire an old Transit key version (raise min_decryption_version) without risking undecryptable subject data, since older subjects are never moved forward.

Proposed resolution

Make the existing rotation version-aware, rather than add a parallel feature, so "Rotate to current Master KEK" also picks up a Transit version bump:

  • Store the Master KEK key version on each pdv_subject_key row (a master_key_version field; 0 for non-versioned local keys), so which subjects are behind is a cheap, indexed query.
  • Have the wrap plugin report versions: supportsRekey(), versionOf($wrapped) (the Transit plugin reads the vault:vN: prefix; local returns none), and currentVersion($master_key_id) (Transit returns the key latest_version; local returns 0).
  • Treat a subject as current only when its master_key_id equals the target AND its stored version equals the target current version, so one rotation handles both a Key-entity swap and an in-place Transit version bump, re-wrapping via native transit/rewrap (the Subject KEK plaintext never leaves the store).
  • Re-wrap a whole chunk of subjects in a single request using Transit batch_input, keeping rotation feasible at 100k+ subjects when the Master KEK is network-backed (this also speeds up a Key-swap rotation).

Data model changes

A new master_key_version base field on the pdv_subject_key entity. pdv is pre-release, so this is a field-definition add plus fresh install, with no update path.

API changes

New methods on the internal MasterKeyWrapInterface, and version-aware convergence in SubjectKeyManager and MasterKeyRotator. These services are @internal and pre-release, so there is no backward-compatibility concern.

Remaining tasks

  • Implement, with kernel-test coverage (the existing dispatch test has a fake versioned wrap plugin to extend).
  • Document it in the rotation section of the "Master KEK in OpenBao or Vault" handbook page.
  • Review and merge.

Issue fork pdv-3594067

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

Comments

mably created an issue. See original summary.

mably’s picture

Status: Active » Needs review

  • mably committed 0c12e256 on 1.x
    feat: #3594067 Make Master KEK rotation pick up a new Vault/OpenBao...
mably’s picture

Status: Needs review » Fixed

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.