sodium_crypto_pwhash derives a raw binary key from a password and random salt using a configurable memory-hard Argon2 algorithm.
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 derives a raw binary key from a password and random salt using a configurable memory-hard Argon2 algorithm.
The sodium extension must be enabled.
Syntax and Return Value
sodium_crypto_pwhash(int $length, string $password, string $salt, int $opslimit, int $memlimit, int $algo = ...): string| Parameter | Purpose |
|---|---|
| $length (int) | Requested output length; consult byte-versus-text units for the chosen API. |
| $password (string) | Secret password input. Never print or log a live password. |
| $salt (string) | A salt with the exact required length; use random_bytes for password-derived keys. |
| $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. |
| $algo (int) | The exact algorithm identifier supported by this API. |
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
$salt = random_bytes(SODIUM_CRYPTO_PWHASH_SALTBYTES);
$key = sodium_crypto_pwhash(32, "example-password", $salt, SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE);
echo strlen($key);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.
$salt = random_bytes(SODIUM_CRYPTO_PWHASH_SALTBYTES);
$key = sodium_crypto_pwhash(32, "different-password", $salt, SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE);
var_dump(strlen($key) === 32);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.
$salt = random_bytes(SODIUM_CRYPTO_PWHASH_SALTBYTES);
$key = sodium_crypto_pwhash(32, "longer-example-password", $salt, SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE);
echo bin2hex(hash("sha256", $key, true));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 requires purpose-built salted, slow hashes; a fast cryptographic digest must never be used as a substitute.
Comparison with Related Functions
| Approach | Key distinction |
|---|---|
| sodium_crypto_pwhash | sodium_crypto_pwhash derives a raw binary key from a password and random salt using a configurable memory-hard Argon2 algorithm. |
| 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 derives a raw binary key from a password and random salt using a configurable memory-hard Argon2 algorithm.
- 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.