Switch to argon2 as the default password hashing algorithm

CI images has both now

constructor only changes looks ok but it require container rebuild so needs update hook to request it, otherwise looks ready

Thank you! CR is ready and the code too

Looks good to me, added a question about the update hook though.

Thanks for working on this issue. As I said on #3536662: Properly handle that PHP bcrypt passwords are truncated to 72 bytes,

• I think this issue is the right way to go. Let's make it easy to use something other than bcrypt.
• I think we should implement hook_requirements. We could do that as part of this issue or on #3536662.

@longwave mentioned #2951046 to me. I am adding that as a related issue. Once that issue gets in, we can use something like !php/const PASSWORD_ARGON2ID in services.yml.

The Needs Review Queue Bot tested this issue. It no longer applies to Drupal core. Therefore, this issue status is now "Needs work".

This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.

Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.

I think requirements exposition of available hashes should be done in #3536662: Properly handle that PHP bcrypt passwords are truncated to 72 bytes

This issue exactly about to add support of argon and make it configurable, also soduim open doors to fast encrypted storage

Left a minor question on the MR, fine to self RTBC

@catch mentioned on slack

don't think we need the empty post update on 3530186 because the default deployment identifier is based on \Drupal::version() and that's used in the container cache key. Doesn't really matter except it's less updates to remove when the time comes later. Mentioning in here because it went around a couple of times in the issue already

Sorry for the runaround @znerol - can we remove that?

We discussed this on the security team triage call in relation to #3536662: Properly handle that PHP bcrypt passwords are truncated to 72 bytes - in particular that issue's reintroduction of the legacy phpass hashing for users with passwords longer than 72 bytes where the bcypt algorithm is in use.

We decided we would instead prefer to move forward with this issue rather than what is effectively backwards with the reuse of phpass.

We decided we would prefer to have the hook_requirements from that issue added here that:

1. Shows a warning if the site only has bcrypt hashing available - detailing the 72 char/null byte risk with links to PHP.net regarding argon2
2. Shows an error if the site has argon2 available but it isn't the default hashing algorithm

I've manually tested that changing the hashing algorithm with existing users successfully rehashes their password in the new algorithm when they next login.

I will mark the other issue as postponed on this one in the meantime.

We also decided to re-purpose the php_password contrib module as a BC layer as the changes in this MR can't be backported.

So this issue here will fix 11.3/10.6 and the contrib module will decorate the core service to bring this functionality to stable branches. The contrib module will have a forward compatibility layer that will be a no-op if it detects the container param added here - which would indicate the module is no longer needed as the site has updated to a version with this feature.

With this issue and the contrib module ready, we will likely issue a PSA

Crediting those involved in the discussion.

Removed post update hook

I think this needs:

We decided we would prefer to have the hook_requirements from that issue added here that:

Shows a warning if the site only has bcrypt hashing available - detailing the 72 char/null byte risk with links to PHP.net regarding argon2
Shows an error if the site has argon2 available but it isn't the default hashing algorithm

from #24.

forwards compatibility layer is ready for review here https://git.drupalcode.org/project/php_password/-/merge_requests/6/diffs

I think transition to new hash should be done in follow-up, moreover old passwords makes no sense when Argon2 available

@andypost:

What transition do you mean?

Passwords should be rehashed automatically when users log in with their passwords. The Q&A for the Password Compatiblity module apply to this situation, too.

From #24 here:

I've manually tested that changing the hashing algorithm with existing users successfully rehashes their password in the new algorithm when they next login.

@znerol:

Should we add a config and a proper UI to make these requirement checks more actionable?

I have been thinking that this is something that would be managed through services.yml, not the UI. In fact, I like the idea of relying on something in the filesystem. Otherwise, XSS can be exploited to change the password hashing algorithm.

If you still want to provide a configuration form, then let's have a followup issue for further discussion.

Edit: I initially wrote settings.yml. I meant services.yml.

How is it easier to use the \PASSWORD_* constants? Using drush php:

> password_algos()
= [
    "2y",
    "argon2i",
    "argon2id",
  ]

I think we should let people set a hashing algorithm in services.yml.

Have we considered what to do if the service parameter is invalid? Do we fall back to PASSWORD_DEFAULT? Is there a requirements check (for the status page)?

I updated the change record to add an example of setting the parameters via a services.yml file
Fixed a couple of typos in the MR.
Going to try to simplify the hook_requirements a bit

Moved the requirements checking logic to a new private method which enabled me to reduce the cyclic complexity/nesting.

As this was just moving things around I think I'm still ok to mark this as RTBC. So doing so.

https://www.drupal.org/project/php_password/releases/3.0.0 has been released with the forward compat layer

+1 RTBC as no code change just move and s/know/known text change

With the change record, is password.options really required? It looks like it defaults to empty array anyway and could be omitted.

Also should some documentation be going into default.services.yml? The issue summary mentions this but there's no changes in the MR.

Updated the CR to make it clear that password.options is optional.
Added docs to core.services.yml and default.services.yml

The link in the message is to a change record. Should that be to a documentation page instead?

I think we should consider removing the hook_requirements() from here altogether, and sorting that out in #3536662: Properly handle that PHP bcrypt passwords are truncated to 72 bytes where we have multiple options that might not require it (at least on all sites, we still might end up with something similar on some sites).

I hadn't read the other issue, #3536662: Properly handle that PHP bcrypt passwords are truncated to 72 bytes, until now. I like the suggestion in #43.

sadly it will go to 12 now

Could 1 MR be closed?

In Comment #31, I wrote,

I have been thinking that this is something that would be managed through services.yml, not the UI. In fact, I like the idea of relying on something in the filesystem. Otherwise, XSS can be exploited to change the password hashing algorithm.

I have not seen any reply to that comment. The current approach does not provide a configuration form, but it does provide a module that sets the hashing algorithm to argon2.

My point is that something in the filesystem is fundamentally more secure than something in the database. Enabling the module is simple, and it reliably sets the algorithm name to a valid value, but it is not as secure as changing services.yml. If an attacker can disable the module, then hashing goes back to bcrypt, and no one will notice until they look at the status report.

There are other, less important, reasons I do not like the module:

1. Instead of having one place to look for where the algorithm is set, there are now two: either services.yml or /admin/modules.
2. It is a single-purpose module, unlike most of the core modules. (I also dislike the announcements_feed module for that reason.)
3. It adds to the complexity of the MR: more than 25% of the added lines are in this module.

Some of the new interface text:

• The Password Argon2 module enforces the argon2 password hashing algorithm for new user account passwords.
• New passwords are being hashed with the %algorithm algorithm.

I would like to get rid of the word "new" in this text. Unless I am confused, existing passwords will be re-hashed with the current algorithm the first time they are used after the algorithm is updated. How about something like this?

• The Password Argon2 module hashes account passwords with the argon2 algorithm.
• Passwords are hashed with the %algorithm algorithm.

As I commented in Slack: I wonder if this is something that should be controlled by settings.php? That feels like an easier place to document opt-in functionality. If we are confident argon2 is widely available in PHP 8.5 we could default to that in new installs, and fall back to bcrypt only on existing sites where the setting is not set at all. Sites can upgrade by copying the default stanza from default.settings.php to settings.php, and we can mention this in the D12 release notes.

Discussed in Slack with @benjifisher and @catch. I am also not convinced that a separate module is the right way to go here, it leaves us with something more complicated to deprecate and remove in future.

A combined suggestion from the Slack discussion:

• keep the container parameters
• default to argon2 in Drupal 12
• use a compiler pass to detect lack of argon2 and fall back to bcrypt
• use hook_requirements to notify site owners if bcrypt is in use

Assuming that we think argon2 will be generally available in PHP 8.5, this seems reasonable to me. Sites are more secure by default, with backward compatibility. The warning will be shown to site owners who are either unaware or who have explicitly chosen bcrypt.

Benji raised the point that it is possible that users will transfer databases (or more explicitly, password hashes) from an argon2 environment to a non-argon2 environment, and logins will not work. We could technically detect an unsupported algorithm at login time by inspecting the hash, but I'm not sure whether we would want to warn users or not. I assume that most site owners who move databases between environments will also have Drush available as a backup login mechanism, and the status report would warn them that bcrypt is in use (and perhaps we could even extend it to detect unsupported hashes - we had a similar idea to inform site owners that it is safe to remove phpass).

Change record said it will fallback to bcrypt if no argon available but constructor set it to null, not clear how it will work and how to test as all my PHP installs has argon2 available

Thank you, then it looks RTBC

Looking good - thanks for adjusting the MR so quickly, thanks to other reviewers for feedback so far. I've added a couple more comments but this looks pretty close to me.

Thanks - there is a bug in one of the tests, other than that this looks good to me.

I don't think we will accidentally break that test again, this all looks good to me now.

I like this version of the MR much better than the last time I looked (Comment #57). Thanks for continuing to work on it, @znerol, @longwave, and others! In particular, there is no longer a module that enables argon2, which I consider less secure than setting the password algorithm in services.yml.

The change record refers to 11.3 (So does the project page for https://www.drupal.org/project/php_password), so I am adding the issue tag for a CR update. I also think the CR should mention that site owners can use services.yml to set a different algorithm (if their version of PHP supports it) or add parameters. I can update the CR, pending an answer to the next question.

What is the plan for Drupal 11? I guess the idea is that Drupal 12 requires PHP 8.5, so argon2 will be more widely available, but that does not apply to Drupal 11.4. I think we should make the same changes to 11.4 that we make to 12.0, except that core.services.yml should have password.algorithm: ~ (default to PASSWORD_DEFAULT) for BC. That way, any site owners who care can start using argon2 as soon as they update to 11.4. Also, we will get a little closer to the goal of "D12.0 is the same as D11.4, with deprecated code removed and a few other necessary differences".

Eventually, maybe in PHP 9, PASSWORD_DEFAULT will be something other than 2y (bcrypt). When we require such a version of PHP, we should change password.algorithm: argon2id to password.algorithm: ~ in core.services.yml. Should we add a code comment to that effect? Is there a better way to keep track? In the far future, PASSWORD_DEFAULT will be something better than argon2id.

We should document that argon2 support is required for Drupal 12. (Or maybe just recommended, since site owners can override it in services.yml.) Is #3534144: [meta] Set Drupal 12 platform and browser requirements by Jan 15 2026 the right place to do that? I think the right documentation page is PHP requirements. Should we also add something to the release notes? The issue summary does not yet have anything under "Release notes snippet".

We consider this issue to be a Security improvement, don't we? I am adding the issue tag for that.

I plan to do some more manual testing tomorrow.

I did some manual testing. Before Comment #73, I also reviewed the non-test portion of the CR. +1 for RTBC.

Manual testing

I wanted to make sure that the changes for this issue work with the core phpass module. These are my steps:

1. In a Drupal 7 site, create several user accounts with known passwords (kp).
2. Install Drupal 11.x with the Standard profile.
3. Enable the migrate_drupal module and its dependencies (migrate and phpass).
4. Migrate the users from the D7 site: ddev drush migrate:import d7_user --execute-dependencies.
5. Log in as kp-user1.
6. Uninstall the migrate_drupal module (only).
7. Switch the branch for this issue and composer install.
8. Run database updates.
9. Log in as kp-user1.
10. Log in as kp-user2.

To set up for migration, settings.php for the D11 site defines $databases['migrate']['default'], setting host to ddev-drupal7-db. Reference: Managing projects > Inter-Project Communication. Confirm the setting with ddev drush --database=migrate and then check the hashed passwords on the D7 site:

MariaDB [db]> SELECT uid, name, pass FROM users WHERE name LIKE 'kp-%' AND status = 1;
+--------+----------+---------------------------------------------------------+
| uid    | name     | pass                                                    |
+--------+----------+---------------------------------------------------------+
| 181690 | kp-user1 | $S$D1f1NxH98.5IcSmhTPS2xDi4kVo9Kz8jMQSKe2LbxAWE1nyh2DW7 |
| 181691 | kp-user2 | $S$DuK.yXmY8dHhqBW1trM72xPHRr6P6XMHcsL.JnsTCQ9SFmRybYKj |
| 181692 | kp-user3 | $S$DWWrpUPC3N7yLRf2PsBj1bhajikmAD4d5A8Hqf9bC.4PacCHevNN |
| 181693 | kp-user4 | $S$DLYem82dZjsmJ2cinvBgIiG8xKoQbgo8uXAfa6mtPbAYZKe7hETn |
+--------+----------+---------------------------------------------------------+
4 rows in set (0.000 sec)

After Step 5, phpass has updated the hash for kp-user1 on the D11 site:

MariaDB [db]> SELECT uid, name, pass FROM users_field_data WHERE name LIKE 'kp-%' AND status = 1;
+--------+----------+--------------------------------------------------------------+
| uid    | name     | pass                                                         |
+--------+----------+--------------------------------------------------------------+
| 181690 | kp-user1 | $2y$12$h9JXyrs.9bD6faJ2TDofFu2hINSpnArhHlwBnn.XfLL.JRxQIEL4O |
| 181691 | kp-user2 | $S$DuK.yXmY8dHhqBW1trM72xPHRr6P6XMHcsL.JnsTCQ9SFmRybYKj      |
| 181692 | kp-user3 | $S$DWWrpUPC3N7yLRf2PsBj1bhajikmAD4d5A8Hqf9bC.4PacCHevNN      |
| 181693 | kp-user4 | $S$DLYem82dZjsmJ2cinvBgIiG8xKoQbgo8uXAfa6mtPbAYZKe7hETn      |
+--------+----------+--------------------------------------------------------------+
4 rows in set (0.001 sec)

I get the same result after Step 8. After Step 10:

MariaDB [db]> SELECT uid, name, pass FROM users_field_data WHERE name LIKE 'kp-%' AND status = 1;
+--------+----------+---------------------------------------------------------------------------------------------------+
| uid    | name     | pass                                                                                              |
+--------+----------+---------------------------------------------------------------------------------------------------+
| 181690 | kp-user1 | $argon2id$v=19$m=65536,t=4,p=1$WjhKNmRubXBvcEw3MUN2Wg$0nZedQ+L01jv1UQmqm5W/tL1dZgAlBo3HdJ9MY1s34s |
| 181691 | kp-user2 | $argon2id$v=19$m=65536,t=4,p=1$T0dWdi5sYWM1VVNtTXZMMQ$0iA+TtLFDw5l2RYGglxfD0DaF/0JNPn7XJlQGZg4bC8 |
| 181692 | kp-user3 | $S$DWWrpUPC3N7yLRf2PsBj1bhajikmAD4d5A8Hqf9bC.4PacCHevNN                                           |
| 181693 | kp-user4 | $S$DLYem82dZjsmJ2cinvBgIiG8xKoQbgo8uXAfa6mtPbAYZKe7hETn                                           |
+--------+----------+---------------------------------------------------------------------------------------------------+
4 rows in set (0.001 sec)

I've added a note to the PHP requirements page on https://www.drupal.org/docs/getting-started/system-requirements/php-requ... - would be good to get a second set of eyes on that.

@catch:

I looked at the new section https://www.drupal.org/docs/getting-started/system-requirements/php-requ....

I updated the draft change record. In part, I added the following section:

Find available hashing algorithms

Run this command on your server:

php -r 'echo implode("\n", password_algos()) . "\n";'

The output should be something like this:

2y
argon2i
argon2id

The value "2y" corresponds to bcrypt; "argon2i" and "argon2id" correspond to argon2.

Then I replaced the second sentence you added to the PHP requirements page with

For more information, see the change record https://www.drupal.org/node/3530196.

Thanks for checking the docs @benjifisher.

Committed/pushed to main, thanks!

Add the release notes snippet to the alpha1 release notes draft and published the CR.

@znerol Let's open a followup for that - the title of this one should stay the same, the change we are backporting is a bit different.

Belatedly tagging for a release highlight, doesn't hurt to tell people their sites will get more secure after a major update.