>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3590540. --> Reported by: [mably](https://www.drupal.org/user/3375160) Related to !7 >>> <h3>Problem/Motivation</h3> <p>The Fuzzy Config Key Provider derives its encryption key deterministically from <code>$settings['hash_salt']</code>. Any change to <code>hash_salt</code> &mdash; a routine compliance action &mdash; silently turns every stored key into unrecoverable bytes. There is no warning, no fallback, no way to read old values to re-encrypt them after the rotation.</p> <p>This blocks operators who would otherwise rotate <code>hash_salt</code> on schedule (annual key rotation, post-incident rotation, key-management policy alignment). The provider's encryption-at-rest value proposition is undermined by the impossibility of safe rotation.</p> <h3>Steps to reproduce</h3> <ol> <li>Install module 2.1.0 (or later), with the v1 format from issue #3590533.</li> <li>Create a Fuzzy-stored key and verify it decrypts.</li> <li>Change <code>$settings['hash_salt']</code> in <code>settings.php</code>.</li> <li>Read the key value &mdash; empty string returned, original plaintext gone. No log entry indicates why.</li> </ol> <h3>Proposed resolution</h3> <p><strong>Depends on issue #3590533</strong> &mdash; the v1 (AES-256-GCM) format must be in place. The GCM authentication tag is what makes the design below safe: trial-decrypting with a wrong key fails loudly (tag mismatch &rarr; openssl_decrypt returns FALSE), which is unsafe with AES-CBC where the wrong key silently returns garbage that may look like valid plaintext.</p> <p><strong>1. Add an opt-in previous-salt fallback.</strong> A new <code>settings.php</code> entry holds the prior <code>hash_salt</code> value to try during decryption:</p> <pre><pre>// settings.php<br>$settings['hash_salt'] = 'new-salt';<br>$settings['fuzzy_key_provider_previous_hash_salt'] = 'old-salt';</pre></pre><p>Single scalar, not a list. Drupal's recommended rotation procedure (below) keeps the previous-salt slot occupied for exactly one rotation cycle, so a list of previous salts would be speculative complexity. If a site needs to chain rotations, they script A &rarr; re-encrypt &rarr; B &rarr; re-encrypt &rarr; C explicitly; each step uses one previous salt. The scalar also enforces "migrate fully before rotating again" discipline &mdash; valuable for an audit-trail-grade provider.</p> <p><code>decryptV1()</code> attempts the current <code>hash_salt</code> first. On GCM tag-verification failure (openssl_decrypt returns FALSE) it falls back to <code>fuzzy_key_provider_previous_hash_salt</code> if set, and returns the plaintext if that tag verifies. Encryption always uses the current salt &mdash; new writes are immediately tied to the post-rotation key.</p> <p>Reads pay at most one extra GCM operation on a miss. After running the re-encrypt command (below), the steady state is one successful tag verification per read.</p> <p><strong>2. Add the Drush command deferred from #3590533.</strong></p> <pre>drush fuzzy_key_provider:re-encrypt</pre><p>Walks every <code>key.key.*</code> config entity whose provider is <code>fuzzy_config</code>, reads the value (succeeding via the current salt or the previous-salt fallback), and re-encrypts it with the current salt. Reuses the static <code>KeyMigrator::reEncryptAll()</code> helper already introduced in #3590533. Re-runnable &mdash; every read decrypts cleanly, so the command is safe to invoke any number of times.</p> <p><strong>Note on idempotency.</strong> The walker in #3590533 detects "already v1" by prefix match. To detect "already encrypted under the current salt" we cannot inspect the ciphertext directly. The walker therefore re-saves every v1 key on each run &mdash; a couple of openssl operations per key, no functional change to the stored semantic value, just a fresh random IV. Operators running the command twice in a row see no observable difference.</p> <p><strong>3. End-to-end rotation procedure</strong> (documented in README):</p> <ol> <li>Edit <code>settings.php</code>: set the new <code>hash_salt</code>; set <code>fuzzy_key_provider_previous_hash_salt</code> to the old one.</li> <li>Deploy.</li> <li>Run <code>drush fuzzy_key_provider:re-encrypt</code>.</li> <li>Remove the <code>fuzzy_key_provider_previous_hash_salt</code> entry from <code>settings.php</code>.</li> </ol> <h3>Out of scope</h3> <ul> <li><strong>Legacy (pre-2.1) values do not get rotation support.</strong> The legacy CBC path returns garbage on a wrong key with no way to detect the failure, so trying a previous salt there would silently corrupt readable plaintext into arbitrary bytes. Sites that have not yet run the post-update from #3590533 must do so first, then rotate.</li> <li><strong>Chained rotations without intervening migration.</strong> If a site rotates A &rarr; B, skips the re-encrypt, then rotates B &rarr; C, the keys encrypted under A become unrecoverable &mdash; by design. Documented as a hard prerequisite of the procedure.</li> <li>No automatic salt-discovery from environment-managed secrets backends (Vault, AWS Secrets Manager). Operators wire those into <code>settings.php</code> themselves using existing patterns.</li> <li>No UI-driven rotation. <code>hash_salt</code> rotation is operator-managed; surfacing it in the admin UI conflates secrets-management with config-management.</li> </ul> <h3>Remaining tasks</h3> <ul> <li>Extend <code>FuzzyConfigKeyProvider::decryptV1()</code> to fall back to <code>fuzzy_key_provider_previous_hash_salt</code> on tag-verification failure.</li> <li>Add the <code>drush fuzzy_key_provider:re-encrypt</code> command class plus <code>drush/drush</code> in <code>require-dev</code>.</li> <li>Add kernel test coverage: fallback succeeds on a previous-salt v1 ciphertext; fallback returns empty when no salt matches; re-encrypt walker re-keys ciphertexts to the current salt.</li> <li>Update README with the operational procedure under the existing <em>Caveats</em> section (which currently links forward to this issue).</li> </ul> <h3>API changes</h3> <p>None at the public-method level. One new <code>settings.php</code> entry (<code>fuzzy_key_provider_previous_hash_salt</code>) &mdash; opt-in, scalar string, no default. One new Drush command.</p> <h3>Data model changes</h3> <p>None. Stored format remains v1.</p> <h3>Related</h3> <p>Depends on #3590533 (v1 format + KeyMigrator helper).</p>