Module orion::pwhash

Available on crate feature safe_api only.

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 than isize::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() and PasswordHash::unprotected_as_bytes() should never be used to compare password hashes, as these will not run in constant-time. Either use hash_password_verify() or compare two PasswordHashes.
• 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.
• 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.