feat(encryption): Add previous keys fallback feature

app/Config/Encryption.php

@@ -23,6 +23,24 @@
      */
     public string $key = '';
 
+    /**
+     * --------------------------------------------------------------------------
+     * Previous Encryption Keys fallback enabled
+     * --------------------------------------------------------------------------
+     * If you want to enable decryption using previous keys, set this to true.
+     * See the user guide for more info.
+     */
+    public bool $previousKeysFallbackEnabled = false;
+
+    /**
+     * --------------------------------------------------------------------------
+     * Previous Encryption Keys
+     * --------------------------------------------------------------------------
+     * If you want to enable decryption using previous keys, set them here.
+     * See the user guide for more info.
+     */
+    public array $previousKeys = [];
+
     /**
      * --------------------------------------------------------------------------
      * Encryption Driver to Use

env

@@ -55,6 +55,11 @@
 
 # encryption.key =
 
+# Previous keys fallback is disabled by default.
+# If you want to enable it, uncomment the line below.
+# encryption.previousKeysFallbackEnabled = true
+# encryption.previousKeys =
+
 #--------------------------------------------------------------------
 # SESSION
 #--------------------------------------------------------------------

system/Config/BaseConfig.php

@@ -130,18 +130,34 @@
         foreach ($properties as $property) {
             $this->initEnvValue($this->{$property}, $property, $prefix, $shortPrefix);
 
-            if ($this instanceof Encryption && $property === 'key') {
-                if (str_starts_with($this->{$property}, 'hex2bin:')) {
-                    // Handle hex2bin prefix
-                    $this->{$property} = hex2bin(substr($this->{$property}, 8));
-                } elseif (str_starts_with($this->{$property}, 'base64:')) {
-                    // Handle base64 prefix
-                    $this->{$property} = base64_decode(substr($this->{$property}, 7), true);
+            if ($this instanceof Encryption) {
+                if ($property === 'key') {
+                    $this->{$property} = $this->parseEncryptionKey($this->{$property});
+                } elseif ($property === 'previousKeysFallbackEnabled') {
+                    // previousKeysFallbackEnabled must be boolean
+                    $this->{$property} = (bool) $this->{$property};
+                } elseif ($property === 'previousKeys') {
+                    // previousKeys must be an array
+                    if (is_string($this->{$property})) {
+                        $this->{$property} = array_map(fn ($item) => $this->parseEncryptionKey($item), explode(',', $this->{$property}));
+                    }
                 }
             }
         }
     }
 
+    protected function parseEncryptionKey(string $key): string
+    {
+        if (str_starts_with($key, 'hex2bin:')) {
+            return hex2bin(substr($key, 8));
+        }
+        if (str_starts_with($key, 'base64:')) {
+            return base64_decode(substr($key, 7), true);
+        }
+
+        return $key;
+    }
+
     /**
      * Initialization an environment-specific configuration setting
      *

system/Encryption/Encryption.php

@@ -53,6 +53,18 @@ class Encryption
      */
     protected $key;
 
+    /**
+     * Whether to fall back to previous keys when decryption fails.
+     */
+    protected bool $previousKeysFallbackEnabled = false;
+
+    /**
+     * List of previous keys for fallback decryption.
+     *
+     * @var list<string>
+     */
+    protected array $previousKeys = [];
+
     /**
      * The derived HMAC key
      *
@@ -91,9 +103,11 @@ public function __construct(?EncryptionConfig $config = null)
     {
         $config ??= new EncryptionConfig();
 
-        $this->key    = $config->key;
-        $this->driver = $config->driver;
-        $this->digest = $config->digest ?? 'SHA512';
+        $this->key                         = $config->key;
+        $this->previousKeysFallbackEnabled = $config->previousKeysFallbackEnabled;
+        $this->previousKeys                = $config->previousKeys;
+        $this->driver                      = $config->driver;
+        $this->digest                      = $config->digest ?? 'SHA512';
 
         $this->handlers = [
             'OpenSSL' => extension_loaded('openssl'),
@@ -116,9 +130,11 @@ public function __construct(?EncryptionConfig $config = null)
     public function initialize(?EncryptionConfig $config = null)
     {
         if ($config instanceof EncryptionConfig) {
-            $this->key    = $config->key;
-            $this->driver = $config->driver;
-            $this->digest = $config->digest ?? 'SHA512';
+            $this->key                         = $config->key;
+            $this->previousKeysFallbackEnabled = $config->previousKeysFallbackEnabled ?? false;
+            $this->previousKeys                = $config->previousKeys ?? [];
+            $this->driver                      = $config->driver;
+            $this->digest                      = $config->digest ?? 'SHA512';
         }
 
         if (empty($this->driver)) {

system/Encryption/Handlers/OpenSSLHandler.php

@@ -14,7 +14,6 @@
 namespace CodeIgniter\Encryption\Handlers;
 
 use CodeIgniter\Encryption\Exceptions\EncryptionException;
-use SensitiveParameter;
 
 /**
  * Encryption handling for OpenSSL library
@@ -56,6 +55,18 @@
      */
     protected $key = '';
 
+    /**
+     * Whether to fall back to previous keys when decryption fails.
+     */
+    protected bool $previousKeysFallbackEnabled = false;
+
+    /**
+     * List of previous keys for fallback decryption.
+     *
+     * @var list<string>
+     */
+    protected array $previousKeys = [];
+
     /**
      * Whether the cipher-text should be raw. If set to false, then it will be base64 encoded.
      */
@@ -80,14 +91,14 @@
     /**
      * {@inheritDoc}
      */
     public function encrypt(#[SensitiveParameter] $data, #[SensitiveParameter] $params = null)
     {
         // Allow key override
         if ($params !== null) {
             $this->key = is_array($params) && isset($params['key']) ? $params['key'] : $params;
         }
 
         if (empty($this->key)) {
             throw EncryptionException::forNeedsStarterKey();
         }
 
@@ -116,7 +127,7 @@
     /**
      * {@inheritDoc}
      */
     public function decrypt($data, #[SensitiveParameter] $params = null)
     {
         // Allow key override
         if ($params !== null) {
@@ -127,8 +138,47 @@
             throw EncryptionException::forNeedsStarterKey();
         }
 
+        try {
+            $result = $this->decryptWithKey($data, $this->key);
+        } catch (EncryptionException $e) {
+            $result    = false;
+            $exception = $e;
+        }
+
+        if ($result === false && $this->previousKeysFallbackEnabled && ! empty($this->previousKeys)) {
+            foreach ($this->previousKeys as $previousKey) {
+                try {
+                    $result = $this->decryptWithKey($data, $previousKey);
+                    if ($result !== false) {
+                        return $result;
+                    }
+                } catch (EncryptionException) {
+                    // Try next key
+                }
+            }
+        }
+
+        if (isset($exception)) {
+            throw $exception;
+        }
+
+        return $result;
+    }
+
+    /**
+     * Decrypt the data with the provided key
+     *
+     * @param string $data
+     * @param string $key
+     *
+     * @return false|string
+     *
+     * @throws EncryptionException
+     */
+    protected function decryptWithKey($data, #[SensitiveParameter] $key)
+    {
         // derive a secret key
-        $authKey = \hash_hkdf($this->digest, $this->key, 0, $this->authKeyInfo);
+        $authKey = \hash_hkdf($this->digest, $key, 0, $this->authKeyInfo);
 
         $hmacLength = $this->rawData
             ? $this->digestSize[$this->digest]
@@ -152,7 +202,7 @@
         }
 
         // derive a secret key
-        $encryptKey = \hash_hkdf($this->digest, $this->key, 0, $this->encryptKeyInfo);
+        $encryptKey = \hash_hkdf($this->digest, $key, 0, $this->encryptKeyInfo);
 
         return \openssl_decrypt($data, $this->cipher, $encryptKey, OPENSSL_RAW_DATA, $iv);
     }

system/Encryption/Handlers/SodiumHandler.php

@@ -14,7 +14,6 @@
 namespace CodeIgniter\Encryption\Handlers;
 
 use CodeIgniter\Encryption\Exceptions\EncryptionException;
-use SensitiveParameter;
 
 /**
  * SodiumHandler uses libsodium in encryption.
@@ -31,6 +30,18 @@
      */
     protected $key = '';
 
+    /**
+     * Whether to fall back to previous keys when decryption fails.
+     */
+    protected bool $previousKeysFallbackEnabled = false;
+
+    /**
+     * List of previous keys for fallback decryption.
+     *
+     * @var list<string>
+     */
+    protected array $previousKeys = [];
+
     /**
      * Block size for padding message.
      *
@@ -41,7 +52,7 @@
     /**
      * {@inheritDoc}
      */
     public function encrypt(#[SensitiveParameter] $data, #[SensitiveParameter] $params = null)
     {
         $this->parseParams($params);
 
@@ -72,7 +83,7 @@
     /**
      * {@inheritDoc}
      */
     public function decrypt($data, #[SensitiveParameter] $params = null)
     {
         $this->parseParams($params);
 
@@ -80,6 +91,47 @@
             throw EncryptionException::forNeedsStarterKey();
         }
 
+        try {
+            $result = $this->decryptWithKey($data, $this->key);
+            sodium_memzero($this->key);
+        } catch (EncryptionException $e) {
+            $result    = false;
+            $exception = $e;
+            sodium_memzero($this->key);
+        }
+
+        if ($result === false && $this->previousKeysFallbackEnabled && ! empty($this->previousKeys)) {
+            foreach ($this->previousKeys as $previousKey) {
+                try {
+                    $result = $this->decryptWithKey($data, $previousKey);
+                    if (isset($result)) {
+                        return $result;
+                    }
+                } catch (EncryptionException) {
+                    // Try next key
+                }
+            }
+        }
+
+        if (isset($exception)) {
+            throw $exception;
+        }
+
+        return $result;
+    }
+
+    /**
+     * Decrypt the data with the provided key
+     *
+     * @param string $data
+     * @param string $key
+     *
+     * @return string
+     *
+     * @throws EncryptionException
+     */
+    protected function decryptWithKey($data, #[SensitiveParameter] $key)
+    {
         if (mb_strlen($data, '8bit') < (SODIUM_CRYPTO_SECRETBOX_NONCEBYTES + SODIUM_CRYPTO_SECRETBOX_MACBYTES)) {
             // message was truncated
             throw EncryptionException::forAuthenticationFailed();
@@ -90,7 +142,7 @@
         $ciphertext = self::substr($data, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
 
         // decrypt data
-        $data = sodium_crypto_secretbox_open($ciphertext, $nonce, $this->key);
+        $data = sodium_crypto_secretbox_open($ciphertext, $nonce, $key);
 
         if ($data === false) {
             // message was tampered in transit
@@ -106,7 +158,6 @@
 
         // cleanup buffers
         sodium_memzero($ciphertext);
-        sodium_memzero($this->key);
 
         return $data;
     }