From 69bc86677345a875c442c0a40d2836369bc7afbb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Maur=C3=ADcio=20Meneghini=20Fauth?= <mauricio@fauth.dev>
Date: Thu, 15 Sep 2022 18:41:32 -0300
Subject: [PATCH] Document how to generate a string of random bytes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Maurício Meneghini Fauth <mauricio@fauth.dev>
---
 config.sample.inc.php |  2 +-
 doc/config.rst        |  4 ++++
 doc/faq.rst           | 31 +++++++++++++++++++++++++++++++
 3 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/config.sample.inc.php b/config.sample.inc.php
index 5ba637c759..2fca0b5bc4 100644
--- a/config.sample.inc.php
+++ b/config.sample.inc.php
@@ -11,7 +11,7 @@ declare(strict_types=1);
 
 /**
  * This is needed for cookie based authentication to encrypt the cookie.
- * Needs to be a 32-bytes long string of random bytes.
+ * Needs to be a 32-bytes long string of random bytes. See FAQ 2.10.
  */
 $cfg['blowfish_secret'] = ''; /* YOU MUST FILL IN THIS FOR COOKIE AUTH! */
 
diff --git a/doc/config.rst b/doc/config.rst
index 95cd0aa841..11f5b1d893 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
 -----------------------------
 
@@ -1933,6 +1935,8 @@ Cookie authentication options
         `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
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