feat(encryption): Add previous keys fallback feature

app/Config/Encryption.php

@@ -23,6 +23,15 @@ class Encryption extends BaseConfig
      */
     public string $key = '';
 
+    /**
+     * --------------------------------------------------------------------------
+     * Previous Encryption Keys
+     * --------------------------------------------------------------------------
+     * If you want to enable decryption using previous keys, set them here.
+     * See the user guide for more info.
+     */
+    public string $previousKeys = '';
+
     /**
      * --------------------------------------------------------------------------
      * Encryption Driver to Use

env

@@ -55,6 +55,9 @@
 
 # encryption.key =
 
+# Previous keys fallback; comma-separated list
+# encryption.previousKeys =
+
 #--------------------------------------------------------------------
 # SESSION
 #--------------------------------------------------------------------

system/Config/BaseConfig.php

@@ -130,18 +130,34 @@ public function __construct()
         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 === 'previousKeys') {
+                    $keysArray  = array_map(trim(...), explode(',', $this->{$property}));
+                    $parsedKeys = [];
+
+                    foreach ($keysArray as $key) {
+                        $parsedKeys[] = $this->parseEncryptionKey($key);
+                    }
+                    $this->{$property} = implode(',', $parsedKeys);
                 }
             }
         }
     }
 
+    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,11 @@ class Encryption
      */
     protected $key;
 
+    /**
+     * Comma-separated list of previous keys for fallback decryption.
+     */
+    protected string $previousKeys = '';
+
     /**
      * The derived HMAC key
      *
@@ -91,9 +96,10 @@ 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->previousKeys = $config->previousKeys;
+        $this->driver       = $config->driver;
+        $this->digest       = $config->digest ?? 'SHA512';
 
         $this->handlers = [
             'OpenSSL' => extension_loaded('openssl'),
@@ -116,9 +122,10 @@ 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->previousKeys = $config->previousKeys ?? '';
+            $this->driver       = $config->driver;
+            $this->digest       = $config->digest ?? 'SHA512';
         }
 
         if (empty($this->driver)) {

system/Encryption/Handlers/OpenSSLHandler.php

@@ -56,6 +56,11 @@ class OpenSSLHandler extends BaseHandler
      */
     protected $key = '';
 
+    /**
+     * List of previous keys for fallback decryption.
+     */
+    protected string $previousKeys = '';
+
     /**
      * Whether the cipher-text should be raw. If set to false, then it will be base64 encoded.
      */
@@ -127,8 +132,48 @@ public function decrypt($data, #[SensitiveParameter] $params = null)
             throw EncryptionException::forNeedsStarterKey();
         }
 
+        $result = false;
+
+        try {
+            $result = $this->decryptWithKey($data, $this->key);
+        } catch (EncryptionException $e) {
+            $exception = $e;
+        }
+
+        if ($result === false && $this->previousKeys !== '') {
+            foreach (explode(',', $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 +197,7 @@ public function decrypt($data, #[SensitiveParameter] $params = null)
         }
 
         // 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

@@ -31,6 +31,11 @@
      */
     protected $key = '';
 
+    /**
+     * List of previous keys for fallback decryption.
+     */
+    protected string $previousKeys = '';
+
     /**
      * Block size for padding message.
      *
@@ -80,6 +85,48 @@
             throw EncryptionException::forNeedsStarterKey();
         }
 
+        $result = false;
+
+        try {
+            $result = $this->decryptWithKey($data, $this->key);
+            sodium_memzero($this->key);
+        } catch (EncryptionException $e) {
+            $exception = $e;
+            sodium_memzero($this->key);
+        }
+
+        if ($result === false && $this->previousKeys !== '') {
+            foreach (explode(',', $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 +137,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 +153,6 @@
 
         // cleanup buffers
         sodium_memzero($ciphertext);
-        sodium_memzero($this->key);
 
         return $data;
     }
@@ -120,7 +166,7 @@
      *
      * @throws EncryptionException If key is empty
      */
-    protected function parseParams($params)
+    protected function parseParams(#[SensitiveParameter] $params)
     {
         if ($params === null) {
             return;