Module pwhash
Available on crate feature
dep_orion
only.Expand description
Password hashing and verification.
§Use case:
orion::pwhash
is suitable for securely storing passwords.
An example of this would be needing to store user passwords (from a sign-up at a webstore) in a server database, where a potential disclosure of the data in this database should not result in the user’s actual passwords being disclosed as well.
§About:
- Uses Argon2i.
- A salt of 16 bytes is automatically generated.
- The password hash length is set to 32.
PasswordHash
provides two ways of retrieving the hashed password:
PasswordHash::unprotected_as_encoded()
returns the hashed password in an encoded form. The encoding specifies the settings used to hash the password.PasswordHash::unprotected_as_bytes()
returns only the hashed password in raw bytes.
The following is an example of how the encoded password hash might look:
$argon2i$v=19$m=8192,t=3,p=1$c21hbGxzYWx0$lmO1aPPy3x0CcvrKpFLi1TL/uSVJ/eO5hPHiWZFaWvY
See a more detailed description of the encoding format here.
§Note:
This implementation only supports a single thread/lane.
§Parameters:
password
: The password to be hashed.expected
: The expected password hash.iterations
: Iterations cost parameter for Argon2i.memory
: Memory (in kibibytes (KiB)) cost parameter for Argon2i.
§Errors:
An error will be returned if:
memory
is less than 8.iterations
is less than 3.- The length of the
password
is greater thanisize::MAX
. - The password hash does not match
expected
.
§Panics:
A panic will occur if:
- Failure to generate random bytes securely.
§Security:
PasswordHash::unprotected_as_encoded()
andPasswordHash::unprotected_as_bytes()
should never be used to compare password hashes, as these will not run in constant-time. Either usehash_password_verify()
or compare twoPasswordHash
es.- Choosing the correct cost parameters is important for security. Please refer to libsodium’s docs for a description of how to do this.
If the concrete cost parameters needed are unclear, please refer to OWASP for recommended minimum values.
§Example:
use orion::pwhash;
let password = pwhash::Password::from_slice(b"Secret password")?;
let hash = pwhash::hash_password(&password, 3, 1<<16)?;
assert!(pwhash::hash_password_verify(&hash, &password).is_ok());
Structs§
- Password
- A type to represent the
Password
that Argon2i hashes and uses for key derivation. - Password
Hash - A type to represent the
PasswordHash
that Argon2i returns when used for password hashing.
Constants§
- PWHASH_
LENGTH - The length of the hashed password.
- SALT_
LENGTH - The length of the salt used for password hashing.
Functions§
- hash_
password - Hash a password using Argon2i.
- hash_
password_ verify - Hash and verify a password using Argon2i. The Argon2i parameters
iterations
andmemory
will be pulled from theexpected: &PasswordHash
argument. If you want to manually specify the iterations and memory for Argon2i to use in hashing thepassword
argument, see thehazardous::kdf
module.