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 PBKDF2-HMAC-SHA512.
- A salt of 64 bytes is automatically generated.
- The password hash length is set to 64.
The first 64 bytes of the PasswordHash
returned by pwhash::hash_password
is the salt used to hash the password and the last 64 bytes is the actual
hashed password. When using this function with
pwhash::hash_password_verify()
, then the separation of the salt and the
password hash is automatically handled.
Parameters:
password
: The password to be hashed.expected_with_salt
: The expected password hash with the corresponding salt prepended.iterations
: The number of iterations performed by PBKDF2, i.e. the cost parameter.
Exceptions:
An exception will be thrown if:
iterations
is 0.- The
OsRng
fails to initialize or read from its source. - The
expected_with_salt
is not constructed exactly as inpwhash::hash_password
. - The password hash does not match
expected_with_salt
.
Security:
- The iteration count should be set as high as feasible. The recommended minimum is 100000.
Example:
use orion::pwhash;
let password = pwhash::Password::from_slice(b"Secret password").unwrap();
let hash = pwhash::hash_password(&password, 100000).unwrap();
assert!(pwhash::hash_password_verify(&hash, &password, 100000).unwrap());
Structs
A type to represent the
Password
that PBKDF2 hashes and uses for key derivation.A type to represent the
PasswordHash
that PBKDF2 returns when used for password hashing.Functions
Hash a password using PBKDF2-HMAC-SHA512.
Hash and verify a password using PBKDF2-HMAC-SHA512.