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 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:

• unprotected_as_encoded() returns the hashed password in an encoded form. The encoding specifies the settings used to hash the password.
• 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 u32::max_value().
• The password hash does not match expected.

Panics:

A panic will occur if:

• Failure to generate random bytes securely.

Security:

• unprotected_as_encoded() and unprotected_as_bytes() should never be used to compare password hashes, as these will not run in constant-time. Either use pwhash::hash_password_verify or compare two PasswordHashes.
• The base64 encoding and decoding operations that PasswordHash performs, do NOT run in constant-time.
• 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, 3, 1<<16).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.