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_keyrow (amaster_key_versionfield; 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 thevault:vN:prefix; local returns none), andcurrentVersion($master_key_id)(Transit returns the key latest_version; local returns 0). - Treat a subject as current only when its
master_key_idequals 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 nativetransit/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
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
Comment #3
mably commentedComment #5
mably commented