Update the docs to reflect the blowfish_secret changes

Signed-off-by: Maurício Meneghini Fauth <mauricio@fauth.dev>

7 files changed, 42 insertions, 20 deletions

diff --git a/ChangeLog b/ChangeLog
index 46def253e4..d4bc5e966e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -34,6 +34,7 @@ phpMyAdmin - ChangeLog
 - issue        Fix PHP warning on GIS visualization when there is only one GIS column
 - issue #17728 Some select HTML tags will now have the correct UI style
 - issue #17734 PHP deprecations will only be shown when in a development environment
+- issue #17369 Fix server error when blowfish_secret is not exactly 32 bytes long
 
 5.2.0 (2022-05-10)
 - issue #16521 Upgrade Bootstrap to version 5
diff --git a/config.sample.inc.php b/config.sample.inc.php
index 34b6a9dabf..5ba637c759 100644
--- a/config.sample.inc.php
+++ b/config.sample.inc.php
@@ -10,8 +10,8 @@
 declare(strict_types=1);
 
 /**
- * This is needed for cookie based authentication to encrypt password in
- * cookie. Needs to be 32 chars long.
+ * This is needed for cookie based authentication to encrypt the cookie.
+ * Needs to be a 32-bytes long string of random bytes.
  */
 $cfg['blowfish_secret'] = ''; /* YOU MUST FILL IN THIS FOR COOKIE AUTH! */
 
diff --git a/doc/config.rst b/doc/config.rst
index 5594823827..95cd0aa841 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -1896,13 +1896,23 @@ Cookie authentication options
     :type: string
     :default: ``''``
 
-    The "cookie" auth\_type uses AES algorithm to encrypt the password. If you
-    are using the "cookie" auth\_type, enter here a random passphrase of your
-    choice. It will be used internally by the AES algorithm: you won’t be
-    prompted for this passphrase.
+    The "cookie" auth\_type uses the :term:`Sodium` extension to encrypt the cookies (see :term:`Cookie`). If you are
+    using the "cookie" auth\_type, enter here a generated string of random bytes to be used as an encryption key. It
+    will be used internally by the :term:`Sodium` extension: you won't be prompted for this encryption key.
 
-    The secret should be 32 characters long. Using shorter will lead to weaker security
-    of encrypted cookies, using longer will cause no harm.
+    Since a binary string is usually not printable, it can be converted into a hexadecimal representation (using a
+    function like `sodium_bin2hex <https://www.php.net/sodium_bin2hex>`_) and then used in the configuration file. For
+    example:
+
+    .. code-block:: php
+
+        // The string is a hexadecimal representation of a 32-bytes long string of random bytes.
+        $cfg['blowfish_secret'] = sodium_hex2bin('f16ce59f45714194371b48fe362072dc3b019da7861558cd4ad29e4d6fb13851');
+
+    .. warning::
+
+        The encryption key must be 32 bytes long. If it has a different length of bytes, a new key will be automatically
+        generated for you. However it will only last for the duration of the session.
 
     .. note::
 
@@ -1910,11 +1920,19 @@ Cookie authentication options
         Blowfish algorithm was originally used to do the encryption.
 
     .. versionchanged:: 3.1.0
+
         Since version 3.1.0 phpMyAdmin can generate this on the fly, but it
         makes a bit weaker security as this generated secret is stored in
         session and furthermore it makes impossible to recall user name from
         cookie.
 
+    .. versionchanged:: 5.2.0
+
+        Since version 5.2.0, phpMyAdmin uses the
+        `sodium\_crypto\_secretbox <https://www.php.net/sodium_crypto_secretbox>`_ and
+        `sodium\_crypto\_secretbox\_open <https://www.php.net/sodium_crypto_secretbox_open>`_ PHP functions to encrypt
+        and decrypt cookies, respectively.
+
 .. config:option:: $cfg['CookieSameSite']
 
     :type: string
@@ -3809,8 +3827,8 @@ following example shows two of them:
 .. code-block:: php
 
     <?php
-    $cfg['blowfish_secret'] = 'multiServerExample70518';
-    // any string of your choice
+    // The string is a hexadecimal representation of a 32-bytes long string of random bytes.
+    $cfg['blowfish_secret'] = sodium_hex2bin('f16ce59f45714194371b48fe362072dc3b019da7861558cd4ad29e4d6fb13851');
     $i = 0;
 
     $i++; // server 1 :
diff --git a/doc/glossary.rst b/doc/glossary.rst
index 87eb074a27..8e328ae25d 100644
--- a/doc/glossary.rst
+++ b/doc/glossary.rst
@@ -335,6 +335,11 @@ From Wikipedia, the free encyclopedia
 
       .. seealso:: <https://en.wikipedia.org/wiki/Server_(computing)>
 
+    Sodium
+      The Sodium PHP extension.
+
+      .. seealso:: `PHP manual for Sodium extension <https://www.php.net/manual/en/book.sodium.php>`_
+
     Storage Engines
       MySQL can use several different formats for storing data on disk, these
       are called storage engines or table types. phpMyAdmin allows a user to
diff --git a/doc/setup.rst b/doc/setup.rst
index c2b7b78928..1f2563edfc 100644
--- a/doc/setup.rst
+++ b/doc/setup.rst
@@ -587,8 +587,8 @@ simple configuration may look like this:
 .. code-block:: xml+php
 
     <?php
-    // use here a value of your choice at least 32 chars long
-    $cfg['blowfish_secret'] = '1{dd0`<Q),5XP_:R9UK%%8\"EEcyH#{o';
+    // The string is a hexadecimal representation of a 32-bytes long string of random bytes.
+    $cfg['blowfish_secret'] = sodium_hex2bin('f16ce59f45714194371b48fe362072dc3b019da7861558cd4ad29e4d6fb13851');
 
     $i=0;
     $i++;
diff --git a/libraries/classes/Config/Settings.php b/libraries/classes/Config/Settings.php
index c5ee9ede3d..62d344c516 100644
--- a/libraries/classes/Config/Settings.php
+++ b/libraries/classes/Config/Settings.php
@@ -118,10 +118,9 @@ final class Settings
     public $AllowThirdPartyFraming;
 
     /**
-     * The 'cookie' auth_type uses AES algorithm to encrypt the password. If
-     * at least one server configuration uses 'cookie' auth_type, enter here a
-     * pass phrase that will be used by AES. The maximum length seems to be 46
-     * characters.
+     * The 'cookie' auth_type uses the Sodium extension to encrypt the cookies. If at least one server configuration
+     * uses 'cookie' auth_type, enter here a generated string of random bytes to be used as an encryption key. The
+     * encryption key must be 32 bytes long.
      *
      * @var string
      */
diff --git a/libraries/config.default.php b/libraries/config.default.php
index 3ecb83faa2..2c3acd51c1 100644
--- a/libraries/config.default.php
+++ b/libraries/config.default.php
@@ -100,10 +100,9 @@ $cfg['TranslationWarningThreshold'] = 80;
 $cfg['AllowThirdPartyFraming'] = false;
 
 /**
- * The 'cookie' auth_type uses AES algorithm to encrypt the password. If
- * at least one server configuration uses 'cookie' auth_type, enter here a
- * pass phrase that will be used by AES. The maximum length seems to be 46
- * characters.
+ * The 'cookie' auth_type uses the Sodium extension to encrypt the cookies. If at least one server configuration
+ * uses 'cookie' auth_type, enter here a generated string of random bytes to be used as an encryption key. The
+ * encryption key must be 32 bytes long.
  *
  * @global string $cfg['blowfish_secret']
  */