Merge branch 'QA_5_2'

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

4 files changed, 78 insertions, 10 deletions

diff --git a/doc/config.rst b/doc/config.rst
index 5594823827..20366d140d 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -1888,6 +1888,8 @@ Generic settings
     A secret key used to encrypt/decrypt the URL query string.
     Should be 32 bytes long.
 
+    .. seealso:: :ref:`faq2_10`
+
 Cookie authentication options
 -----------------------------
 
@@ -1896,13 +1898,33 @@ 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.
+
+    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');
+
+    Using a binary string is recommended. However, if all 32 bytes of the string are visible
+    characters, then a function like `sodium_bin2hex <https://www.php.net/sodium_bin2hex>`_ is not required. For
+    example:
+
+    .. code-block:: php
 
-    The secret should be 32 characters long. Using shorter will lead to weaker security
-    of encrypted cookies, using longer will cause no harm.
+        // A string of 32 characters.
+        $cfg['blowfish_secret'] = 'JOFw435365IScA&Q!cDugr!lSfuAz*OW';
+
+    .. warning::
+
+        The encryption key must be 32 bytes long. If it is longer than the length of bytes, only the first 32 bytes will
+        be used, and if it is shorter, a new temporary key will be automatically generated for you. However, this
+        temporary key will only last for the duration of the session.
 
     .. note::
 
@@ -1910,11 +1932,21 @@ 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.
+
+    .. seealso:: :ref:`faq2_10`
+
 .. config:option:: $cfg['CookieSameSite']
 
     :type: string
@@ -3809,8 +3841,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/faq.rst b/doc/faq.rst
index 866a920dab..ff1e928f0d 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -867,6 +867,37 @@ If using PHP 5.4.0 or higher, you must set
 starting from phpMyAdmin version 4.0.4, session-based upload progress has
 been temporarily deactivated due to its problematic behavior.
 
+.. _faq2_10:
+
+2.10 How to generate a string of random bytes
+---------------------------------------------
+
+One way to generate a string of random bytes suitable for cryptographic use is using the
+`random_bytes <https://www.php.net/random_bytes>`_ :term:`PHP` function. Since this function returns a binary string,
+the returned value should be converted to printable format before being able to copy it.
+
+For example, the :config:option:`$cfg['blowfish_secret']` configuration directive requires a 32-bytes long string. The
+following command can be used to generate a hexadecimal representation of this string.
+
+.. code-block:: sh
+
+    php -r 'echo bin2hex(random_bytes(32)) . PHP_EOL;'
+
+The above example will output something similar to:
+
+.. code-block:: sh
+
+    f16ce59f45714194371b48fe362072dc3b019da7861558cd4ad29e4d6fb13851
+
+And then this hexadecimal value can be used in the configuration file.
+
+.. code-block:: php
+
+    $cfg['blowfish_secret'] = sodium_hex2bin('f16ce59f45714194371b48fe362072dc3b019da7861558cd4ad29e4d6fb13851');
+
+The `sodium_hex2bin <https://www.php.net/sodium_hex2bin>`_ is used here to convert the hexadecimal value back to the
+binary format.
+
 .. _faqlimitations:
 
 Known limitations
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++;