sodium_crypto_pwhash_str creates a self-contained password hash encoded with salt and work parameters.
The examples explain the data format, expected results and the difference between this API and nearby cryptographic operations.
What It Does
The operation is intended for: sodium_crypto_pwhash_str creates a self-contained password hash encoded with salt and work parameters.
The sodium extension must be enabled.
Syntax and Return Value
sodium_crypto_pwhash_str(string $password, int $opslimit, int $memlimit): string| Parameter | Purpose |
|---|---|
| $password (string) | Secret password input. Never print or log a live password. |
| $opslimit (int) | Work factor for a password KDF, balanced against login latency. |
| $memlimit (int) | Memory cost for password derivation, chosen with the deployment budget in mind. |
The declared return type is shown above. Errors can include false results or exceptions depending on this API: Password storage must use the encoded _str variant or password_hash; raw derived bytes need salt and parameter retention.
Example 1: Basic Operation
The _str variant is for password storage; the raw KDF output is not a self-describing password hash.
<?php
$hash = sodium_crypto_pwhash_str("example-password", SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE);
echo strlen($hash) . " encoded bytes";Example 2: A Different Use Case
Try a different password and inspect the encoded hash or raw derived key without displaying secrets.
<?php
// Check the alternative case.
$hash = sodium_crypto_pwhash_str("different-password", SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE);
var_dump(is_string($hash) && str_starts_with($hash, "$"));Practical Example: Checking the Result
Try a different password and inspect the encoded hash or raw derived key without displaying secrets.
<?php
// Verify the expected behavior before using results.
$hash = sodium_crypto_pwhash_str("longer-example-password", SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE);
var_dump(strlen($hash) > 20);Important Behavior and Edge Cases
Password storage must use the encoded _str variant or password_hash; raw derived bytes need salt and parameter retention.
Password storage must use the encoded _str variant or password_hash; raw derived bytes need salt and parameter retention.
Comparison with Related Functions
| Approach | Key distinction |
|---|---|
| sodium_crypto_pwhash_str | sodium_crypto_pwhash_str creates a self-contained password hash encoded with salt and work parameters. |
| Related technique | password_hash is the normal application-login password storage interface. |
Common Beginner Mistakes
| Mistake | Correct approach |
|---|---|
| Confusing this operation with a neighboring cryptographic or security mechanism | password_hash is the normal application-login password storage interface. |
| Ignoring a security prerequisite or failure case | Password storage must use the encoded _str variant or password_hash; raw derived bytes need salt and parameter retention. |
Key Takeaways
- sodium_crypto_pwhash_str creates a self-contained password hash encoded with salt and work parameters.
- Password storage must use the encoded _str variant or password_hash; raw derived bytes need salt and parameter retention.
- password_hash is the normal application-login password storage interface.
Apply this behavior to a real application only after confirming the required extension, configuration and failure handling on the deployment runtime.