>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3594067. --> Reported by: [mably](https://www.drupal.org/user/3375160) Related to !27 >>> <h3>Problem/Motivation</h3> <p>The <code>pdv_vault</code> submodule can hold the Master KEK in OpenBao or HashiCorp Vault Transit. The Transit key can be rotated in place (for example <code>bao write -f transit/keys/pdv-master/rotate</code>), 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 <code>min_decryption_version</code>), but pdv never migrates the existing subjects onto the new version.</p> <p>This is because Master KEK rotation converges subjects by the Master KEK <em>Key-entity id</em> (<code>master_key_id</code>), not by the Transit key <em>version</em>: <code>SubjectKeyManager::rewrap()</code> short-circuits when the id is unchanged, so an in-place version bump yields zero pending and re-wraps nothing.</p> <p>The consequence is that an operator cannot safely retire an old Transit key version (raise <code>min_decryption_version</code>) without risking undecryptable subject data, since older subjects are never moved forward.</p> <h3>Proposed resolution</h3> <p>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:</p> <ul> <li>Store the Master KEK key version on each <code>pdv_subject_key</code> row (a <code>master_key_version</code> field; 0 for non-versioned local keys), so which subjects are behind is a cheap, indexed query.</li> <li>Have the wrap plugin report versions: <code>supportsRekey()</code>, <code>versionOf($wrapped)</code> (the Transit plugin reads the <code>vault:vN:</code> prefix; local returns none), and <code>currentVersion($master_key_id)</code> (Transit returns the key latest_version; local returns 0).</li> <li>Treat a subject as current only when its <code>master_key_id</code> 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 <code>transit/rewrap</code> (the Subject KEK plaintext never leaves the store).</li> <li>Re-wrap a whole chunk of subjects in a single request using Transit <code>batch_input</code>, keeping rotation feasible at 100k+ subjects when the Master KEK is network-backed (this also speeds up a Key-swap rotation).</li> </ul> <h3>Data model changes</h3> <p>A new <code>master_key_version</code> base field on the <code>pdv_subject_key</code> entity. pdv is pre-release, so this is a field-definition add plus fresh install, with no update path.</p> <h3>API changes</h3> <p>New methods on the internal <code>MasterKeyWrapInterface</code>, and version-aware convergence in <code>SubjectKeyManager</code> and <code>MasterKeyRotator</code>. These services are <code>@internal</code> and pre-release, so there is no backward-compatibility concern.</p> <h3>Remaining tasks</h3> <ul> <li>Implement, with kernel-test coverage (the existing dispatch test has a fake versioned wrap plugin to extend).</li> <li>Document it in the rotation section of the "Master KEK in OpenBao or Vault" handbook page.</li> <li>Review and merge.</li> </ul>