Allow selecting password_hash algorithm (#17199)

* proof of concept for selecting password_hash algorithm

* better code stlye

* update expected screenshot

* Add entry to changelog for new INI config options.

Co-authored-by: diosmosis <diosmosis@users.noreply.github.com>

4 files changed, 78 insertions, 2 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bfde3d2fe9..34ead19711 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,12 @@ This is the Developer Changelog for Matomo platform developers. All changes in o
 
 The Product Changelog at **[matomo.org/changelog](https://matomo.org/changelog)** lets you see more details about any Matomo release, such as the list of new guides and FAQs, security fixes, and links to all closed issues. 
 
+## Matomo 4.3.0
+
+### New config.ini.php settings
+
+* The `password_hash_algorithm`, `password_hash_argon2_threads`, `password_hash_argon2_memory_cost` and `password_hash_argon2_time_cost` INI config options have been added to allow using specific `password_hash` algorithms and options if desired.
+
 ## Matomo 4.2.0
 
 ### New config.ini.php settings
diff --git a/config/global.ini.php b/config/global.ini.php
index 68c712aa86..5a6e4fbbef 100755
--- a/config/global.ini.php
+++ b/config/global.ini.php
@@ -394,6 +394,25 @@ disable_checks_usernames_attributes = 0
 ; For legacy data, fallback or non-security scenarios, we use md5.
 hash_algorithm = whirlpool
 
+; set the algorithm used by password_hash()
+; "default" for the algorithm used by the PHP version or one of ["bcrypt", "argon2i", "argon2id"]
+; "argon2id" requires at least PHP 7.3.0
+; for all argon2 algorithms, additional parameters can be changed below
+; any changes are applied to the stored hash on the next login of a user
+; see https://www.php.net/manual/en/function.password-hash.php and https://wiki.php.net/rfc/argon2_password_hash
+; for more information
+password_hash_algorithm = default
+
+; The number of CPU threads used for calculating the hash
+password_hash_argon2_threads = default
+
+; The amount of memory (in KB) used for calculating the hash
+; a minimum of 8 times the number of threads
+password_hash_argon2_memory_cost = default
+
+; The number of iterations for calculating the hash
+password_hash_argon2_time_cost = default
+
 ; If set to 1, Matomo will automatically redirect all http:// requests to https://
 ; If SSL / https is not correctly configured on the server, this will break Matomo
 ; If you set this to 1, and your SSL configuration breaks later on, you can always edit this back to 0
diff --git a/core/Auth/Password.php b/core/Auth/Password.php
index b1ac2d0d34..51634ec9ed 100644
--- a/core/Auth/Password.php
+++ b/core/Auth/Password.php
@@ -5,8 +5,12 @@
  * @link https://matomo.org
  * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
  */
+
 namespace Piwik\Auth;
 
+use Exception;
+use Piwik\Config;
+
 /**
  * Main class to handle actions related to password hashing and verification.
  *
@@ -15,6 +19,53 @@ namespace Piwik\Auth;
 class Password
 {
     /**
+     * Choose the used algorithm for password_hash depending on the config option
+     *
+     * @return string|int depending on PHP version
+     * @throws Exception
+     */
+    private function preferredAlgorithm()
+    {
+        $passwordHashAlogrithm = Config::getInstance()->General['password_hash_algorithm'];
+        switch ($passwordHashAlogrithm) {
+            case "default":
+                return PASSWORD_DEFAULT;
+            case "bcrypt":
+                return PASSWORD_BCRYPT;
+            case "argon2i":
+                return PASSWORD_ARGON2I;
+            case "argon2id":
+                if (version_compare(PHP_VERSION, '7.3.0', '<')) {
+                    throw new Exception("argon2id needs at leat PHP 7.3.0");
+                }
+                return PASSWORD_ARGON2ID;
+            default:
+                throw new Exception("invalid password_hash_algorithm");
+        }
+    }
+
+    /**
+     * Fetches argon2 options from config.ini.php
+     *
+     * @return array
+     */
+    private function algorithmOptions()
+    {
+        $options = [];
+        $generalConfig = Config::getInstance()->General;
+        if ($generalConfig["password_hash_argon2_threads"] != "default") {
+            $options["threads"] = max($generalConfig["password_hash_argon2_threads"], 1);
+        }
+        if ($generalConfig["password_hash_argon2_memory_cost"] != "default") {
+            $options["memory_cost"] = max($generalConfig["password_hash_argon2_memory_cost"], 8 * $options["threads"]);
+        }
+        if ($generalConfig["password_hash_argon2_time_cost"] != "default") {
+            $options["time_cost"] = max($generalConfig["password_hash_argon2_time_cost"], 1);
+        }
+        return $options;
+    }
+
+    /**
      * Hashes a password with the configured algorithm.
      *
      * @param string $password
@@ -22,7 +73,7 @@ class Password
      */
     public function hash($password)
     {
-        return password_hash($password, PASSWORD_BCRYPT);
+        return password_hash($password, $this->preferredAlgorithm(), $this->algorithmOptions());
     }
 
     /**
@@ -49,7 +100,7 @@ class Password
      */
     public function needsRehash($hash)
     {
-        return password_needs_rehash($hash, PASSWORD_BCRYPT);
+        return password_needs_rehash($hash, $this->preferredAlgorithm(), $this->algorithmOptions());
     }
 
     /**
diff --git a/tests/UI/expected-screenshots/UIIntegrationTest_admin_diagnostics_configfile.png b/tests/UI/expected-screenshots/UIIntegrationTest_admin_diagnostics_configfile.png
index 675a7f0302..55d19e35f4 100644
--- a/tests/UI/expected-screenshots/UIIntegrationTest_admin_diagnostics_configfile.png
+++ b/tests/UI/expected-screenshots/UIIntegrationTest_admin_diagnostics_configfile.png