[PATCH access-control/docs v2 0/2] Update default password hash function to yescrypt

[PATCH access-control/docs v2 0/2] Update default password hash function to yescrypt

[Shannon Sterz]

Also updates the password hash when a user logs in.

Changelog
---------

* v1: https://lore.proxmox.com/pve-devel/20261009122729.178682-2-s.sterz@proxmox.com/

- changes since v1:
    + added a patch that actually opts in the pve and pam realm to yescrypt
      hashes and updates hashes on login


access-control:

Shannon Sterz (1):
  pam/pve: use yescrypt for new password hashes

 src/PVE/Auth/PAM.pm | 2 +-
 src/PVE/Auth/PVE.pm | 9 ++++++++-
 2 files changed, 9 insertions(+), 2 deletions(-)


docs:

Shannon Sterz (1):
  pveum: document that the pve realm now uses yescrypt

 pveum.adoc | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)


Summary over all repositories:
  3 files changed, 21 insertions(+), 7 deletions(-)

-- 
Generated by murpp 0.12.0

[PATCH access-control v2 1/2] pam/pve: use yescrypt for new password hashes

[Shannon Sterz]

and in the case of the pve realm, update old stored hashes on
authentication. this should improve the security of passwords.
yescrypt is the default in Debian since the Bullseye release [1].

[1]: Section 5.1.4,
https://www.debian.org/releases/bullseye/amd64/release-notes.en.txt

Signed-off-by: Shannon Sterz <s.sterz@proxmox.com>
---

Notes:
    note that the change for pam also means that previously if a new
    password for a pam user was set via the PVE API, the hash function
    used for that password would effectively have been downgraded.

 src/PVE/Auth/PAM.pm | 2 +-
 src/PVE/Auth/PVE.pm | 9 ++++++++-
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/src/PVE/Auth/PAM.pm b/src/PVE/Auth/PAM.pm
index 8586da5..b67eb03 100755
--- a/src/PVE/Auth/PAM.pm
+++ b/src/PVE/Auth/PAM.pm
@@ -85,7 +85,7 @@ sub store_password {
 
     my $cmd = ['usermod'];
 
-    my $epw = PVE::Tools::encrypt_pw($password);
+    my $epw = PVE::Tools::encrypt_pw($password, 'y');
 
     push @$cmd, '-p', $epw, $username;
 
diff --git a/src/PVE/Auth/PVE.pm b/src/PVE/Auth/PVE.pm
index ab439a8..cd0e5af 100755
--- a/src/PVE/Auth/PVE.pm
+++ b/src/PVE/Auth/PVE.pm
@@ -11,6 +11,7 @@ use PVE::Cluster qw(cfs_register_file cfs_read_file cfs_write_file cfs_lock_file
 use base qw(PVE::Auth::Plugin);
 
 my $shadowconfigfile = "priv/shadow.cfg";
+my $hash_prefix = "y";
 
 cfs_register_file($shadowconfigfile, \&parse_shadow_passwd, \&write_shadow_config);
 
@@ -81,6 +82,12 @@ sub authenticate_user {
         my $encpw =
             crypt(Encode::encode('utf8', $password), $shadow_cfg->{users}->{$username}->{shadow});
         die "invalid credentials\n" if ($encpw ne $shadow_cfg->{users}->{$username}->{shadow});
+
+        # If the password was stored with a different hash function than the currently configured
+        # one, update it here.
+        if ($shadow_cfg->{users}->{$username}->{shadow} !~ m/^\$${hash_prefix}\$/) {
+            store_password($class, $config, $realm, $username, $password);
+        }
     } else {
         die "no password set\n";
     }
@@ -93,7 +100,7 @@ sub store_password {
 
     lock_shadow_config(sub {
         my $shadow_cfg = cfs_read_file($shadowconfigfile);
-        my $epw = PVE::Tools::encrypt_pw($password);
+        my $epw = PVE::Tools::encrypt_pw($password, $hash_prefix);
         $shadow_cfg->{users}->{$username}->{shadow} = $epw;
         cfs_write_file($shadowconfigfile, $shadow_cfg);
     });
-- 
2.47.3

[PATCH docs v2 2/2] pveum: document that the pve realm now uses yescrypt

[Shannon Sterz]

and document that passwords will be updated on login.

Signed-off-by: Shannon Sterz <s.sterz@proxmox.com>
---

Notes:
    we may want to implement a scheme similar to pbs and pdm where
    passwords are updated to the latest hashing scheme on log in,
    requiring less user interaction.

 pveum.adoc | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/pveum.adoc b/pveum.adoc
index d089cb6..b970f1e 100644
--- a/pveum.adoc
+++ b/pveum.adoc
@@ -147,11 +147,18 @@ these users to log in via their system username and password.
 {pve} Authentication Server::
 
 This is a Unix-like password store, which stores hashed passwords in
-`/etc/pve/priv/shadow.cfg`. Passwords are hashed using the SHA-256 hashing
-algorithm. This is the most convenient realm for small-scale (or even
-mid-scale) installations, where users do not need access to anything outside of
-{pve}. In this case, users are fully managed by {pve} and are able to change
-their own passwords via the GUI.
+`/etc/pve/priv/shadow.cfg`. Passwords are hashed and salted using the yescrypt
+algorithm footnote:[yescrypt https://www.openwall.com/yescrypt/]. It provides
+strong protections against offline password cracking attempts. This realm is the
+most convenient realm for small-scale (or even mid-scale) installations, where
+users do not need access to anything outside of {pve}. In this case, users are
+fully managed by {pve} and are able to change their own passwords via the GUI.
+
+NOTE: Passwords created with older versions of Proxmox VE  used a hashing scheme
+based on SHA-256 that is now considered insecure. If the file
+`/etc/pve/priv/shadow.cfg` shows a password hash starting with `$5$` for an
+account that account still uses such a password. The hash will be updated on the
+next login of that user or when a new password is set.
 
 LDAP::
 
-- 
2.47.3

Re: [PATCH docs v2 2/2] pveum: document that the pve realm now uses yescrypt

[Maximiliano Sandoval]

Comments below.

Shannon Sterz <s.sterz@proxmox.com> writes:

> and document that passwords will be updated on login.
>
> Signed-off-by: Shannon Sterz <s.sterz@proxmox.com>
> ---
>
> Notes:
>     we may want to implement a scheme similar to pbs and pdm where
>     passwords are updated to the latest hashing scheme on log in,
>     requiring less user interaction.
>
>  pveum.adoc | 17 ++++++++++++-----
>  1 file changed, 12 insertions(+), 5 deletions(-)
>
> diff --git a/pveum.adoc b/pveum.adoc
> index d089cb6..b970f1e 100644
> --- a/pveum.adoc
> +++ b/pveum.adoc
> @@ -147,11 +147,18 @@ these users to log in via their system username and password.
>  {pve} Authentication Server::
>  
>  This is a Unix-like password store, which stores hashed passwords in
> -`/etc/pve/priv/shadow.cfg`. Passwords are hashed using the SHA-256 hashing
> -algorithm. This is the most convenient realm for small-scale (or even
> -mid-scale) installations, where users do not need access to anything outside of
> -{pve}. In this case, users are fully managed by {pve} and are able to change
> -their own passwords via the GUI.
> +`/etc/pve/priv/shadow.cfg`. Passwords are hashed and salted using the yescrypt
> +algorithm footnote:[yescrypt https://www.openwall.com/yescrypt/]. It provides
> +strong protections against offline password cracking attempts. This realm is the

nit: Perhaps /protections/protection/?

> +most convenient realm for small-scale (or even mid-scale) installations, where
> +users do not need access to anything outside of {pve}. In this case, users are
> +fully managed by {pve} and are able to change their own passwords via the GUI.
> +
> +NOTE: Passwords created with older versions of Proxmox VE  used a hashing scheme

nit: This should be '{pve}' rather than 'Proxmox VE '.

> +based on SHA-256 that is now considered insecure. If the file

nit: By whom? Is there any good source to link here?

> +`/etc/pve/priv/shadow.cfg` shows a password hash starting with `$5$` for an
> +account that account still uses such a password. The hash will be updated on the
> +next login of that user or when a new password is set.
>  
>  LDAP::

-- 
Maximiliano

Re: [PATCH access-control/docs v2 0/2] Update default password hash function to yescrypt

[Maximiliano Sandoval]

Shannon Sterz <s.sterz@proxmox.com> writes:

> Also updates the password hash when a user logs in.
>
> Changelog
> ---------
>
> * v1: https://lore.proxmox.com/pve-devel/20261009122729.178682-2-s.sterz@proxmox.com/
>
> - changes since v1:
>     + added a patch that actually opts in the pve and pam realm to yescrypt
>       hashes and updates hashes on login
>
> access-control:
>
> [...]
>
> docs:
>
> [...]

Modulo some very small comments regarding documentation (see reply to
commit), the series looks good to me.

Reviewed-by: Maximiliano Sandoval <m.sandoval@proxmox.com>

-- 
Maximiliano

Re: [PATCH docs v2 2/2] pveum: document that the pve realm now uses yescrypt

[Shannon Sterz]

On Wed Oct 21, 2026 at 3:57 PM CEST, Maximiliano Sandoval wrote:
-->8 snip 8<--

>> +`/etc/pve/priv/shadow.cfg`. Passwords are hashed and salted using the yescrypt
>> +algorithm footnote:[yescrypt https://www.openwall.com/yescrypt/]. It provides
>> +strong protections against offline password cracking attempts. This realm is the
>
> nit: Perhaps /protections/protection/?

No protections is right. It offers tunable hardness for all three the
runtime, memory usage and parallelism. So I'd say those are multiple
protections.

>
>> +most convenient realm for small-scale (or even mid-scale) installations, where
>> +users do not need access to anything outside of {pve}. In this case, users are
>> +fully managed by {pve} and are able to change their own passwords via the GUI.
>> +
>> +NOTE: Passwords created with older versions of Proxmox VE  used a hashing scheme
>
> nit: This should be '{pve}' rather than 'Proxmox VE '.

Yep will update this for a potential v3. Same for the related PMG patch.

>
>> +based on SHA-256 that is now considered insecure. If the file
>
> nit: By whom? Is there any good source to link here?
>

> The default processing cost parameter is 5000, which is too low  for  modern
> hardware.
>
> - man 5 crypt

We never modified the default of 5000. So technically if you want to
capture all nuances here, the function itself *could* still be fine.
However, the way we used it wasn't (incidentally, SHA-256 is still used
by yescrypt, just in a different construction).

I'll add that to the commit message of the first patch for more clarity,
but I think for the docs the text is fine as-is. What's important for
users is that if they see a `$5$` in that file, they should log in again
or, alternatively, set a new password (e.g. by having an admin account
set a new password for that account).

Note that PDM and PBS already use yescrypt for that reason [1].

[1]: https://lore.proxmox.com/all/20240306123609.164021-7-s.sterz@proxmox.com/

-->8 snip 8<--

Re: [PATCH access-control/docs v2 0/2] Update default password hash function to yescrypt

[Shannon Sterz]

On Wed Oct 21, 2026 at 4:04 PM CEST, Maximiliano Sandoval wrote:
> Shannon Sterz <s.sterz@proxmox.com> writes:
>
>> Also updates the password hash when a user logs in.
>>
>> Changelog
>> ---------
>>
>> * v1: https://lore.proxmox.com/pve-devel/20261009122729.178682-2-s.sterz@proxmox.com/
>>
>> - changes since v1:
>>     + added a patch that actually opts in the pve and pam realm to yescrypt
>>       hashes and updates hashes on login
>>
>> access-control:
>>
>> [...]
>>
>> docs:
>>
>> [...]
>
> Modulo some very small comments regarding documentation (see reply to
> commit), the series looks good to me.
>
> Reviewed-by: Maximiliano Sandoval <m.sandoval@proxmox.com>

Thanks. If nothing comes up, I'll send a v3 with the nits addressed.