>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3594042. --> Reported by: [mably](https://www.drupal.org/user/3375160) Related to !26 >>> <h3>Problem/Motivation</h3> <p>The roadmap's OpenBao item planned a Key provider that fetches the Master KEK from the store into Drupal. A stronger design is to never bring the Master KEK into Drupal at all, using the Transit secrets engine (encryption as a service): the Master KEK is a Transit key created in the store and never exported. Drupal sends a freshly generated Subject KEK to <code>transit/encrypt</code> and stores the returned ciphertext; it sends that ciphertext to <code>transit/decrypt</code> to get the Subject KEK back. A full Drupal compromise then cannot exfiltrate the root key for offline or permanent decryption. The Transit API is identical on OpenBao and HashiCorp Vault, so this works against either.</p> <h3>Proposed resolution</h3> <p>Implemented as a pluggable Master KEK wrap mechanism in pdv core, plus a submodule that implements it against Transit.</p> <p><strong>pdv core</strong> gains a <code>MasterKeyWrap</code> plugin type (attribute, interface, base, manager). The default <code>local</code> plugin keeps today's local-AEAD wrapping. <code>SubjectKeyManager</code> selects the plugin by the Master KEK Key's <em>type</em> (not by a cipher suite), so existing local keys are unchanged and new mechanisms slot in:</p> <ul> <li>create: the chosen plugin wraps the new Subject KEK; the returned blob is stored as <code>wrapped_key</code>.</li> <li>unwrap: the plugin recorded on the row unwraps it.</li> <li>rotate: when source and target share a mechanism the plugin's native rewrap is used (for Transit, <code>transit/rewrap</code>, so the Subject KEK plaintext never leaves the store); across mechanisms it unwraps with the source and re-wraps with the target.</li> </ul> <p>The Master KEK selectors (site-wide and per-tenant) offer keys whose type a wrap plugin claims.</p> <p><strong>pdv_vault submodule</strong> adds a <code>vault_transit</code> wrap plugin and a <code>pdv_vault_transit</code> Key type whose value is the Transit key name. It calls the store directly over HTTP, so it needs no extra dependencies. The Transit key is created with <code>derived=true</code> and every call passes the owner identity as the per-call context, giving the same owner-binding as the local AEAD.</p> <p><strong>Auth.</strong> The token only needs <code>encrypt</code>/<code>decrypt</code>/<code>rewrap</code> on the one Transit key (never key export, never reading arbitrary secrets), supplied from settings.php or an environment variable, never DB config.</p> <h3>Trade-offs</h3> <ul> <li>The Subject KEK plaintext still transits to and from the store on create and unwrap (Drupal needs it to wrap document DEKs); only the Master KEK never leaves, and during rotation the Subject KEK does not either.</li> <li>Every owner-key resolve becomes a store round-trip (latency and an availability dependency), versus fetch-the-master-once-then-local-crypto. The standard KMS/HSM trade-off.</li> </ul> <h3>Remaining tasks</h3> <ul> <li>Review and merge the merge request.</li> </ul> <h3>API changes</h3> <p>New <code>MasterKeyWrap</code> plugin type in pdv core. <code>SubjectKeyManager</code> (which is <code>@internal</code>) gains the wrap-plugin manager as a constructor argument. No behaviour change for existing local Master KEKs.</p> <h3>User interface changes</h3> <p>The Master KEK select on the settings and tenant forms now also lists keys whose type a wrap plugin handles. Setup is documented in a new "Master KEK in OpenBao or Vault" handbook page.</p>