Skip to content

Commit 6a9fe03

Browse files
MauricioFauthMauricioFauth
committed
Merge branch 'QA_5_2'
Signed-off-by: Maurício Meneghini Fauth <mauricio@fauth.dev>
2 parents 000bf39 + add68b4 commit 6a9fe03

File tree

19 files changed

+292
-139
lines changed

19 files changed

+292
-139
lines changed

‎ChangeLog‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,8 @@ phpMyAdmin - ChangeLog
3636
- issue Fix PHP warning on GIS visualization when there is only one GIS column
3737
- issue #17728 Some select HTML tags will now have the correct UI style
3838
- issue #17734 PHP deprecations will only be shown when in a development environment
39+
- issue #17369 Fix server error when blowfish_secret is not exactly 32 bytes long
40+
- issue #17736 Add utf8mb3 as an alias of utf8 on the charset description page
3941

4042
5.2.0 (2022-05-10)
4143
- issue #16521 Upgrade Bootstrap to version 5

‎config.sample.inc.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,8 @@
1010
declare(strict_types=1);
1111

1212
/**
13-
* This is needed for cookie based authentication to encrypt password in
14-
* cookie. Needs to be 32 chars long.
13+
* This is needed for cookie based authentication to encrypt the cookie.
14+
* Needs to be a 32-bytes long string of random bytes. See FAQ 2.10.
1515
*/
1616
$cfg['blowfish_secret'] = ''; /* YOU MUST FILL IN THIS FOR COOKIE AUTH! */
1717

‎doc/config.rst‎

Lines changed: 40 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1888,6 +1888,8 @@ Generic settings
18881888
A secret key used to encrypt/decrypt the URL query string.
18891889
Should be 32 bytes long.
18901890

1891+
.. seealso:: :ref:`faq2_10`
1892+
18911893
Cookie authentication options
18921894
-----------------------------
18931895

@@ -1896,25 +1898,55 @@ Cookie authentication options
18961898
:type: string
18971899
:default: ``''``
18981900

1899-
The "cookie" auth\_type uses AES algorithm to encrypt the password. If you
1900-
are using the "cookie" auth\_type, enter here a random passphrase of your
1901-
choice. It will be used internally by the AES algorithm: you won’t be
1902-
prompted for this passphrase.
1901+
The "cookie" auth\_type uses the :term:`Sodium` extension to encrypt the cookies (see :term:`Cookie`). If you are
1902+
using the "cookie" auth\_type, enter here a generated string of random bytes to be used as an encryption key. It
1903+
will be used internally by the :term:`Sodium` extension: you won't be prompted for this encryption key.
1904+
1905+
Since a binary string is usually not printable, it can be converted into a hexadecimal representation (using a
1906+
function like `sodium_bin2hex <https://www.php.net/sodium_bin2hex>`_) and then used in the configuration file. For
1907+
example:
1908+
1909+
.. code-block:: php
1910+
1911+
// The string is a hexadecimal representation of a 32-bytes long string of random bytes.
1912+
$cfg['blowfish_secret'] = sodium_hex2bin('f16ce59f45714194371b48fe362072dc3b019da7861558cd4ad29e4d6fb13851');
1913+
1914+
Using a binary string is recommended. However, if all 32 bytes of the string are visible
1915+
characters, then a function like `sodium_bin2hex <https://www.php.net/sodium_bin2hex>`_ is not required. For
1916+
example:
1917+
1918+
.. code-block:: php
19031919
1904-
The secret should be 32 characters long. Using shorter will lead to weaker security
1905-
of encrypted cookies, using longer will cause no harm.
1920+
// A string of 32 characters.
1921+
$cfg['blowfish_secret'] = 'JOFw435365IScA&Q!cDugr!lSfuAz*OW';
1922+
1923+
.. warning::
1924+
1925+
The encryption key must be 32 bytes long. If it is longer than the length of bytes, only the first 32 bytes will
1926+
be used, and if it is shorter, a new temporary key will be automatically generated for you. However, this
1927+
temporary key will only last for the duration of the session.
19061928

19071929
.. note::
19081930

19091931
The configuration is called blowfish_secret for historical reasons as
19101932
Blowfish algorithm was originally used to do the encryption.
19111933

19121934
.. versionchanged:: 3.1.0
1935+
19131936
Since version 3.1.0 phpMyAdmin can generate this on the fly, but it
19141937
makes a bit weaker security as this generated secret is stored in
19151938
session and furthermore it makes impossible to recall user name from
19161939
cookie.
19171940

1941+
.. versionchanged:: 5.2.0
1942+
1943+
Since version 5.2.0, phpMyAdmin uses the
1944+
`sodium\_crypto\_secretbox <https://www.php.net/sodium_crypto_secretbox>`_ and
1945+
`sodium\_crypto\_secretbox\_open <https://www.php.net/sodium_crypto_secretbox_open>`_ PHP functions to encrypt
1946+
and decrypt cookies, respectively.
1947+
1948+
.. seealso:: :ref:`faq2_10`
1949+
19181950
.. config:option:: $cfg['CookieSameSite']
19191951
19201952
:type: string
@@ -3809,8 +3841,8 @@ following example shows two of them:
38093841
.. code-block:: php
38103842
38113843
<?php
3812-
$cfg['blowfish_secret'] = 'multiServerExample70518';
3813-
// any string of your choice
3844+
// The string is a hexadecimal representation of a 32-bytes long string of random bytes.
3845+
$cfg['blowfish_secret'] = sodium_hex2bin('f16ce59f45714194371b48fe362072dc3b019da7861558cd4ad29e4d6fb13851');
38143846
$i = 0;
38153847
38163848
$i++; // server 1 :

‎doc/faq.rst‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -867,6 +867,37 @@ If using PHP 5.4.0 or higher, you must set
867867
starting from phpMyAdmin version 4.0.4, session-based upload progress has
868868
been temporarily deactivated due to its problematic behavior.
869869

870+
.. _faq2_10:
871+
872+
2.10 How to generate a string of random bytes
873+
---------------------------------------------
874+
875+
One way to generate a string of random bytes suitable for cryptographic use is using the
876+
`random_bytes <https://www.php.net/random_bytes>`_ :term:`PHP` function. Since this function returns a binary string,
877+
the returned value should be converted to printable format before being able to copy it.
878+
879+
For example, the :config:option:`$cfg['blowfish_secret']` configuration directive requires a 32-bytes long string. The
880+
following command can be used to generate a hexadecimal representation of this string.
881+
882+
.. code-block:: sh
883+
884+
php -r 'echo bin2hex(random_bytes(32)) . PHP_EOL;'
885+
886+
The above example will output something similar to:
887+
888+
.. code-block:: sh
889+
890+
f16ce59f45714194371b48fe362072dc3b019da7861558cd4ad29e4d6fb13851
891+
892+
And then this hexadecimal value can be used in the configuration file.
893+
894+
.. code-block:: php
895+
896+
$cfg['blowfish_secret'] = sodium_hex2bin('f16ce59f45714194371b48fe362072dc3b019da7861558cd4ad29e4d6fb13851');
897+
898+
The `sodium_hex2bin <https://www.php.net/sodium_hex2bin>`_ is used here to convert the hexadecimal value back to the
899+
binary format.
900+
870901
.. _faqlimitations:
871902

872903
Known limitations

‎doc/glossary.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -335,6 +335,11 @@ From Wikipedia, the free encyclopedia
335335

336336
.. seealso:: <https://en.wikipedia.org/wiki/Server_(computing)>
337337

338+
Sodium
339+
The Sodium PHP extension.
340+
341+
.. seealso:: `PHP manual for Sodium extension <https://www.php.net/manual/en/book.sodium.php>`_
342+
338343
Storage Engines
339344
MySQL can use several different formats for storing data on disk, these
340345
are called storage engines or table types. phpMyAdmin allows a user to

‎doc/setup.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -587,8 +587,8 @@ simple configuration may look like this:
587587
.. code-block:: xml+php
588588

589589
<?php
590-
// use here a value of your choice at least 32 chars long
591-
$cfg['blowfish_secret'] = '1{dd0`<Q),5XP_:R9UK%%8\"EEcyH#{o';
590+
// The string is a hexadecimal representation of a 32-bytes long string of random bytes.
591+
$cfg['blowfish_secret'] = sodium_hex2bin('f16ce59f45714194371b48fe362072dc3b019da7861558cd4ad29e4d6fb13851');
592592

593593
$i=0;
594594
$i++;

‎libraries/classes/Charsets/Collation.php‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -344,6 +344,7 @@ private function getNameForLevel0(
344344
// Fall through to other unicode
345345
case 'ucs2':
346346
case 'utf8':
347+
case 'utf8mb3':
347348
case 'utf16':
348349
case 'utf16le':
349350
case 'utf16be':

‎libraries/classes/Config/ServerConfigChecks.php‎

Lines changed: 20 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -11,17 +11,17 @@
1111
use PhpMyAdmin\Sanitize;
1212
use PhpMyAdmin\Setup\Index as SetupIndex;
1313
use PhpMyAdmin\Url;
14-
use PhpMyAdmin\Util;
1514

1615
use function __;
17-
use function count;
1816
use function function_exists;
1917
use function htmlspecialchars;
20-
use function implode;
2118
use function ini_get;
22-
use function preg_match;
19+
use function is_string;
20+
use function mb_strlen;
21+
use function sodium_crypto_secretbox_keygen;
2322
use function sprintf;
24-
use function strlen;
23+
24+
use const SODIUM_CRYPTO_SECRETBOX_KEYBYTES;
2525

2626
/**
2727
* Performs various compatibility, security and consistency checks on current config
@@ -247,9 +247,12 @@ protected function performConfigChecksServersSetBlowfishSecret(
247247
$cookieAuthServer,
248248
$blowfishSecretSet
249249
): array {
250-
if ($cookieAuthServer && $blowfishSecret === null) {
250+
if (
251+
$cookieAuthServer
252+
&& (! is_string($blowfishSecret) || mb_strlen($blowfishSecret, '8bit') !== SODIUM_CRYPTO_SECRETBOX_KEYBYTES)
253+
) {
251254
$blowfishSecretSet = true;
252-
$this->cfg->set('blowfish_secret', Util::generateRandom(32));
255+
$this->cfg->set('blowfish_secret', sodium_crypto_secretbox_keygen());
253256
}
254257

255258
return [
@@ -345,55 +348,21 @@ protected function performConfigChecksCookieAuthUsed(
345348
): void {
346349
// $cfg['blowfish_secret']
347350
// it's required for 'cookie' authentication
348-
if (! $cookieAuthUsed) {
349-
return;
350-
}
351-
352-
if ($blowfishSecretSet) {
353-
// 'cookie' auth used, blowfish_secret was generated
354-
SetupIndex::messagesSet(
355-
'notice',
356-
'blowfish_secret_created',
357-
Descriptions::get('blowfish_secret'),
358-
Sanitize::sanitizeMessage(__(
359-
'You didn\'t have blowfish secret set and have enabled '
360-
. '[kbd]cookie[/kbd] authentication, so a key was automatically '
361-
. 'generated for you. It is used to encrypt cookies; you don\'t need to '
362-
. 'remember it.'
363-
))
364-
);
365-
366-
return;
367-
}
368-
369-
$blowfishWarnings = [];
370-
// check length
371-
if (strlen($blowfishSecret) < 32) {
372-
// too short key
373-
$blowfishWarnings[] = __('Key is too short, it should have at least 32 characters.');
374-
}
375-
376-
// check used characters
377-
$hasDigits = (bool) preg_match('/\d/', $blowfishSecret);
378-
$hasChars = (bool) preg_match('/\S/', $blowfishSecret);
379-
$hasNonword = (bool) preg_match('/\W/', $blowfishSecret);
380-
if (! $hasDigits || ! $hasChars || ! $hasNonword) {
381-
$blowfishWarnings[] = Sanitize::sanitizeMessage(
382-
__(
383-
'Key should contain letters, numbers [em]and[/em] special characters.'
384-
)
385-
);
386-
}
387-
388-
if (empty($blowfishWarnings)) {
351+
if (! $cookieAuthUsed || ! $blowfishSecretSet) {
389352
return;
390353
}
391354

355+
// 'cookie' auth used, blowfish_secret was generated
392356
SetupIndex::messagesSet(
393-
'error',
394-
'blowfish_warnings' . count($blowfishWarnings),
357+
'notice',
358+
'blowfish_secret_created',
395359
Descriptions::get('blowfish_secret'),
396-
implode('<br>', $blowfishWarnings)
360+
Sanitize::sanitizeMessage(__(
361+
'You didn\'t have blowfish secret set and have enabled '
362+
. '[kbd]cookie[/kbd] authentication, so a key was automatically '
363+
. 'generated for you. It is used to encrypt cookies; you don\'t need to '
364+
. 'remember it.'
365+
))
397366
);
398367
}
399368

‎libraries/classes/Config/Settings.php‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -118,10 +118,9 @@ final class Settings
118118
public $AllowThirdPartyFraming;
119119

120120
/**
121-
* The 'cookie' auth_type uses AES algorithm to encrypt the password. If
122-
* at least one server configuration uses 'cookie' auth_type, enter here a
123-
* pass phrase that will be used by AES. The maximum length seems to be 46
124-
* characters.
121+
* The 'cookie' auth_type uses the Sodium extension to encrypt the cookies. If at least one server configuration
122+
* uses 'cookie' auth_type, enter here a generated string of random bytes to be used as an encryption key. The
123+
* encryption key must be 32 bytes long.
125124
*
126125
* @var string
127126
*/

‎libraries/classes/Controllers/HomeController.php‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -318,19 +318,23 @@ private function checkRequirements(): void
318318
* Check if user does not have defined blowfish secret and it is being used.
319319
*/
320320
if (! empty($_SESSION['encryption_key'])) {
321-
if (empty($GLOBALS['cfg']['blowfish_secret'])) {
321+
$encryptionKeyLength = mb_strlen($GLOBALS['cfg']['blowfish_secret'], '8bit');
322+
if ($encryptionKeyLength < SODIUM_CRYPTO_SECRETBOX_KEYBYTES) {
322323
$this->errors[] = [
323324
'message' => __(
324-
'The configuration file now needs a secret passphrase (blowfish_secret).'
325+
'The configuration file needs a valid key for cookie encryption.'
326+
. ' A temporary key was automatically generated for you.'
327+
. ' Please refer to the [doc@cfg_blowfish_secret]documentation[/doc].'
325328
),
326329
'severity' => 'warning',
327330
];
328-
} elseif (mb_strlen($GLOBALS['cfg']['blowfish_secret'], '8bit') !== SODIUM_CRYPTO_SECRETBOX_KEYBYTES) {
331+
} elseif ($encryptionKeyLength > SODIUM_CRYPTO_SECRETBOX_KEYBYTES) {
329332
$this->errors[] = [
330333
'message' => sprintf(
331334
__(
332-
'The secret passphrase in configuration (blowfish_secret) is not the correct length.'
333-
. ' It should be %d bytes long.'
335+
'The cookie encryption key in the configuration file is longer than necessary.'
336+
. ' It should only be %d bytes long.'
337+
. ' Please refer to the [doc@cfg_blowfish_secret]documentation[/doc].'
334338
),
335339
SODIUM_CRYPTO_SECRETBOX_KEYBYTES
336340
),

0 commit comments

Comments
 (0)