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:

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 than isize::MAX.
  • The password hash does not match expected.

§Panics:

A panic will occur if:

  • Failure to generate random bytes securely.

§Security:

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.
PasswordHash
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 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.