password_hash
Hash a password into a verifiable storage string or check a password against an existing hash. Supports bcrypt, argon2, scrypt, and PBKDF2 schemes.
Instructions
Hash a password into a verifiable storage string, or check one against it.
action=hash (needs scheme) returns encoded, a self-describing string that
carries the scheme, its cost params and the salt: bcrypt's $2b$… and
argon2's PHC string verbatim, and for the stdlib schemes the PHC-shaped
$scrypt$ln=14,r=8,p=1$<salt>$<hash> / $pbkdf2-sha256$i=600000$<salt>$<hash>
(base64 fields, padding stripped). action=verify reads the scheme back out of
encoded and returns {"valid": true|false} — a wrong password is a result,
not an error (§2.0.5); only a malformed encoded raises. The password itself
is never echoed (§2.0.6). bcrypt/argon2* need the crypto extra.
Example: password_hash("hash", "hunter2", scheme="pbkdf2",
params={"iterations": 100000}) -> {"encoded": "$pbkdf2-sha256$i=100000$..."}
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| salt | No | Salt as hex, for reproducible hashing (action='hash'). bcrypt needs exactly 16 bytes, argon2 at least 8. Omit — the default — to draw 16 fresh CSPRNG bytes, which is what you want in production. | |
| action | Yes | 'hash' derives a storage string from `password` (needs `scheme`); 'verify' checks `password` against `encoded`. | |
| params | No | Cost parameters overriding the scheme's defaults: bcrypt {rounds:12}; argon2 {time_cost:3, memory_cost:65536 (KiB), parallelism:4, hash_len:32}; scrypt {ln:14, r:8, p:1, dklen:32}; pbkdf2 {iterations:600000, prf:'sha256', dklen:32}. Default None. | |
| scheme | No | Password-hashing scheme (required for action='hash'). bcrypt and the argon2 variants need the `crypto` extra; scrypt and pbkdf2 are stdlib. On action='verify' it is read from `encoded`, and if given must agree with it. Default None. | |
| encoded | No | The stored hash string to check against (action='verify'). Default None. | |
| password | Yes | The password, read as UTF-8. Never echoed back. |