Skip to content

Conversation

@michalsn
Copy link
Member

@michalsn michalsn commented Jan 1, 2026

Description
This PR adds support for encryption key rotation through the new previousKeys config option. When decryption with the current key fails, the system automatically falls back to trying previous keys, allowing seamless key rotation without losing access to data encrypted with old keys.

While implementing this feature, I discovered critical state management issues in both OpenSSLHandler and SodiumHandler. The handlers were modifying their internal $key property when keys were passed via the $params argument to encrypt() and decrypt() methods. This was actually a bug, as the user guide clearly states that the key passed via $params:

will be used as the starting key for this operation https://codeigniter.com/user_guide/libraries/encryption.html#CodeIgniter\Encryption\CodeIgniter\Encryption\EncrypterInterface::decrypt

And not that it will permanently modify the handler's state (this is aligned with how CI3 worked).

Additionally, SodiumHandler::encrypt() was calling sodium_memzero($this->key), which destroyed the encryption key after the first use and prevented handler reuse. While this memory-clearing behavior was documented, it created an inconsistency where SodiumHandler could not be reused after encryption, but OpenSSLHandler could, making it impossible to use both handlers reliably in the same way.

These issues became particularly problematic with the previousKeys fallback mechanism, where the handlers needed to try multiple keys without corrupting their state. To fix this, I refactored both handlers to use local variables for keys passed via $params, ensuring the handler's state remains unchanged and aligning the implementation with the documented behavior.

This is a BC break because some code may have relied on the buggy behavior where $params modified the stored key. However, this affects only a small subset of users who passed a key via $params once and expected it to persist for subsequent operations. Most users who either always pass the key via $params for each operation or always configure keys via Config\Encryption are not affected.

The proper way to configure encryption keys has always been through Config\Encryption, and this change enforces that pattern while fixing the underlying state management bugs.

Closes #9853

Checklist:

  • Securely signed commits
  • Component(s) with PHPDoc blocks, only if necessary or adds value (without duplication)
  • Unit testing, with >80% coverage
  • User guide updated
  • Conforms to style guide

Co-authored-by: patel-vansh <developer.patelvansh@gmail.com>
@michalsn michalsn added enhancement PRs that improve existing functionalities breaking change Pull requests that may break existing functionalities 4.7 labels Jan 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

4.7 breaking change Pull requests that may break existing functionalities enhancement PRs that improve existing functionalities

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant