[−][src]Module orion::pwhash

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.

Errors:

An error will be returned if:

iterations is 0.
The expected_with_salt is not constructed exactly as in pwhash::hash_password.
The password hash does not match expected_with_salt.

Panics:

A panic will occur if:

The OsRng fails to initialize or read from its source.

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")?;

let hash = pwhash::hash_password(&password, 100000)?;
assert!(pwhash::hash_password_verify(&hash, &password, 100000)?);

Structs

Password	A type to represent the `Password` that PBKDF2 hashes and uses for key derivation.
PasswordHash	A type to represent the `PasswordHash` that PBKDF2 returns when used for password hashing.
Salt	A type to represent the `Salt` that PBKDF2 uses during key derivation.

Functions

hash_password	Hash a password using PBKDF2-HMAC-SHA512.
hash_password_verify	Hash and verify a password using PBKDF2-HMAC-SHA512.