Available on crate feature
safe_api
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.
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
A type to represent the
Password
that Argon2i hashes and uses for key derivation.A type to represent the
PasswordHash
that Argon2i returns when used for password hashing.Constants
The length of the hashed password.
The length of the salt used for password hashing.
Functions
Hash a password using Argon2i.
Hash and verify a password using Argon2i. The Argon2i parameters
iterations
and memory
will be pulled from the expected: &PasswordHash
argument. If
you want to manually specify the iterations and memory for Argon2i to use in
hashing the password
argument, see the
hazardous::kdf
module.