Skip to content

Password Handling

ZubZet hashes passwords with PHP's native Argon2id. The framework stores enough information alongside every hash to verify it, to recognise older hashes, and to upgrade them to the current algorithm automatically. Application code normally never touches a hash directly: the User API covers creating users, setting passwords, and checking a login.

Where passwords are stored

Credentials live on the z_user table:

Column Purpose
password The stored credential, VARCHAR(255) (an Argon2id hash for current accounts).
password_scheme Which format password is in: native, legacy, onion, or wordpress. NULL for accounts without a password: User::add() inserts NULL and sets native once a password is set.
salt VARCHAR(255), per row salt for legacy and onion rows. NULL for native and wordpress, because those hashes embed their own salt; every upgrade to native resets it to NULL.
last_password_rehash_at TIMESTAMP NULL: when the stored hash was last produced (password change or rehash); the migration backfilled it from created for rows with a password. Useful for credential age policies.

There is no separate salt for native hashes. A native password value already contains the algorithm, the cost parameters, and a random salt in one self describing string, which is what makes transparent upgrades possible.

The schemes

The password_scheme column tells the verifier how to read a stored value, so the formats can coexist while older accounts upgrade on their own.

Scheme password holds salt Notes
native An Argon2id hash from password_hash(). NULL The target format for every account.
legacy The raw SHA-512 hex produced by the framework's previous scheme. set Verify only. Upgraded to native on the next login.
onion A native Argon2id hash wrapping the legacy value. set A dormant account moved onto Argon2id ahead of its next login. Upgraded to native when the owner logs in.
wordpress A hash imported from WordPress, $wp$2y$… (6.8 and later) or $P$… (phpass, earlier). NULL Verify only. Upgraded to native on the next login. See Importing WordPress users.

Adding users and setting passwords

For building features and APIs, work through the User object. The plaintext is hashed for you, and the resulting account is always native.

Create a user with a password

use ZubZet\Framework\Authentication\Permission\User;

$user = User::add("[email protected]", "the-plaintext-password");

User::add() also accepts null for the password to create an account whose credential is set later (for example invite or single sign on flows):

$user = User::add("[email protected]", null);
// ... later ...
$user->updatePassword("the-plaintext-password");

Set or change a password

$user->updatePassword("the-new-plaintext-password");

This writes a fresh native Argon2id hash, clears the salt, stamps last_password_rehash_at, and invalidates the user's existing sessions.

Check a password during login

$user = User::byEmail($email);

if ($user && $user->verifyPassword($plaintext)) {
    // success
}

User::verifyPassword() returns a boolean and is self healing: on a correct login it transparently upgrades a stale stored hash to a current native hash (see Self healing upgrades). It is the password check used by the framework's own login flow.

Reset codes

The forgot-password flow stores a code per request in z_password_reset (userId, refId, reason, active, created; reason is always forgot). The reset page accepts a code while its row is active = 1 and created is newer than the booter setting forgotPasswordTimeSpan. After a successful reset the code is deactivated. A code is ZIT- plus 64 random hex characters, a new request does not deactivate earlier codes, and login/forgot_password has no rate limit and answers {"result":"success"} or {"result":"error"}, so it reveals whether an email is registered. The email is matched exactly, without an active or verified filter. An invalid reset code dies with the bare text ERROR: This code is not or no longer valid!; a successful reset ends all sessions of the user without logging them in, and the server checks no confirmation field (the view compares both in JS only, with a client-side minlength="4").

forgotPasswordTimeSpan is a relative time string such as 60 minutes (the project stub ships exactly that), which is handed to strtotime('-' . $value). When the setting is unset, that call fails and the cut-off becomes 1970-01-01 00:00:00, so an active code never expires. Always set it if codes should have a lifetime.

The hash and verify API

User is built on the lower level ZubZet\Framework\Authentication\PasswordHash\Password class, which you can use directly when you are not working with a User object.

Hashing

use ZubZet\Framework\Authentication\PasswordHash\Password;

$stored = Password::hash($plaintext); // Argon2id

Password::hash() rejects input outside MIN_LENGTH_BYTES to MAX_LENGTH_BYTES (3 to 1024 bytes by strlen, the upper bound being a denial of service guard) by throwing InvalidArgumentException("Invalid password length.").

Verifying

$result = Password::verify($plaintext, $stored);

if ($result->isCorrect()) {
    // password matched
}

Password::verify() returns a Verification value object rather than a bare boolean, so a single call can also report whether the stored hash should be refreshed:

Method Returns
isCorrect() Whether the password matched.
isUpgradeNeeded() Whether the stored hash is stale and should be replaced.
upgradePassword() The fresh native hash to persist. Guard with isUpgradeNeeded() first; calling it when no upgrade is pending throws a LogicException.

The hash inside upgradePassword() is computed only when you call it, so a plain isCorrect() check never pays for an upgrade it does not use. An empty stored value, a password outside the length limits and an unknown scheme (including null) give a wrong result instead of throwing.

For legacy and onion values, pass the scheme and a non-empty salt (otherwise an InvalidArgumentException is thrown) so the verifier knows how to read them:

$result = Password::verify($plaintext, $stored, Password::LEGACY, $salt);

Importing WordPress users

To take over the accounts of a WordPress site, copy each user_pass value into password unchanged and set password_scheme to wordpress. The stored string says which WordPress format it is, so one scheme covers both:

Prefix Produced by Verified as
$wp$2y$ WordPress 6.8 and later bcrypt over an HMAC-SHA-384 pre-hash of the trimmed password, as wp_hash_password() does.
$P$ (or $H$) WordPress before 6.8, and any account that has not logged in since the upgrade to 6.8 The phpass portable hash: salted MD5 iterated 2^count times.

Both verify through the ordinary login path and are replaced by a native Argon2id hash on the first successful login. Nothing else WordPress may store (plain MD5 from before WordPress 2.5, or unprefixed hashes written by a plugin that overrides the algorithm) is recognised; those users need a password reset. The phpass format is weak at rest, and the onion command only covers legacy rows, so consider a reset for $P$ accounts that stay dormant after the import.

Two framework rules apply to imported accounts as they do to every other: passwords shorter than MIN_LENGTH_BYTES are rejected, and WordPress trims the password before hashing, so the verifier trims it as well.

WordPress hashes upgrade themselves

No separate migration step is needed for imported accounts. A wordpress row goes through the same self healing path as a legacy or onion row: on the first correct login, User::verifyPassword() verifies the WordPress hash, writes a fresh native Argon2id hash in its place, sets the scheme to native and stamps last_password_rehash_at. From then on the account is indistinguishable from one created in ZubZet. The WordPress verifiers are only ever consulted for rows still marked wordpress, so they can be removed once that count reaches zero.

Self healing upgrades

ZubZet keeps stored hashes current without ever asking users to reset a working password. On a successful login, the stored hash is upgraded to a fresh native Argon2id hash when any of the following is true:

  • the account is still legacy or onion, or
  • the account is native but was hashed below the current cost.

The second case relies on PHP's password_needs_rehash(). When you raise the Argon2id cost (see below), existing users are migrated one at a time as they log in, with no bulk operation and no forced reset.

Future proofing the work factor

The work factor is PHP's Argon2id default cost. Hardware gets faster over time, so the recommended practice is to re measure every year or two and raise the cost when appropriate. Because the cost is embedded in each stored hash, raising it does not invalidate existing passwords: password_needs_rehash() simply reports the older hashes as stale, and the self healing path upgrades them on the next login.

Migrating an existing installation

When you upgrade the framework, the schema migration runs automatically and marks every existing password row as legacy. Those accounts keep working unchanged and upgrade themselves to native on the next login.

Rehash on login only reaches accounts that actually log in. To bring accounts that have not logged in yet onto Argon2id as well, run the onion migration once:

php index.php auth:migrate-hashing

This wraps every legacy hash in an Argon2id layer and marks the row onion, so the whole table moves onto the modern algorithm rather than only the active accounts. It is idempotent, so it is safe to run more than once, and the first successful login peels an onion row back to a single native hash.

Wrapping an existing hash inside a stronger one is the same layered "onion" technique Facebook has publicly described for modernising its own password storage, which is where the name comes from.

A short history

For years ZubZet hashed passwords with SHA-512 plus a per user salt and an additional transformation step, provided by a dedicated hashing library. That scheme served the framework reliably and shipped in production for a long time.

Version 1.2.0 modernises password storage onto PHP's native Argon2id, the algorithm recommended by the current OWASP Password Storage guidance. Argon2id is memory hard and purpose built for password storage, the native PHP functions are maintained as part of the language and run in constant time, and every stored value embeds its own algorithm, cost, and salt. That self describing format is what lets ZubZet recognise existing hashes and upgrade them transparently, and it makes raising the work factor in the future a one line change.

Existing passwords are safe and keep working. They are verified through the legacy path and re hashed onto Argon2id automatically the next time their owner logs in, so adopting the modern format needs no password reset.