feat: encryption key rotation support

[michalsn]

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

[paulbalandan]

Initial thoughts:

1. Can we have the bug fixed in a separate PR, if possible targeting develop although it can be BC?
2. The decrypt logic going to a callback looks unintuitive to me. Though I understand why it's made like that. I'm thinking if we can have a decorator class that takes in either OpenSSLHandler or SodiumHandler (so basically any handler implementing EncrypterInterface) then when it's the decrypt function we just delegate that to the inner handler. Something like:

class RotatingDecryptionHandler extends BaseHandler
{
        public function __construct(
                private readonly EncrypterInterface $innerHandler,
        } ()

        public function encrypt()
        {
               return $this->innerHandler->encrypt();
        }

        public function decrypt($data, $params)
        {
                try {
                        return $this->innerHandler->decrypt($data, $params);
                } catch (EncryptionException $e) {
                        foreach ($previousKeys as $previousKey) {
                                try {
                                       $params['key'] = $previousKey;
                                        return $this->innerHandler->decrypt($data, $params);
                                 } catch (EncryptionException) {
                                        continue;
                                  }
                        }

                         throw $e;
                }
        }
}

The name of the decorator class is negotiable. Then, when the user requests the openssl handler from the encryption manager, we just wrap it with the decorator class.

What do you think?

[michalsn]

1. Sure, but we can't target develop branch - this is still a BC break.
2. Yes, this is probably a much better idea than using a callback.

[michalsn]

Resolved via #9870 and #9868