Struct PwHash 

pub struct PwHash<Hash: Bytes + Zeroize, Salt: Bytes + Zeroize> { /* private fields */ }

Password hash implementation based on Argon2, compatible with libsodium’s crypto_pwhash_* functions.

Implementations

impl<Hash: NewBytes + ResizableBytes + Zeroize, Salt: NewBytes + ResizableBytes + Zeroize> PwHash<Hash, Salt>

pub fn hash<Password: Bytes>( password: &Password, config: Config, ) -> Result<Self, Error>

Hashes password with a random salt and config, returning the hash, salt, and config upon success.

Errors

Returns an error if a work limit, memory limit, hash length, or password length is outside the supported range, or if the underlying Argon2 operation fails.

pub fn hash_interactive<Password: Bytes>( password: &Password, ) -> Result<Self, Error>

Hashes password with a random salt and a default configuration suitable for interactive hashing, returning the hash, salt, and config upon success.

Errors

Returns the same errors as PwHash::hash.

pub fn hash_moderate<Password: Bytes>( password: &Password, ) -> Result<Self, Error>

Hashes password with a random salt and a default configuration suitable for moderate hashing, returning the hash, salt, and config upon success.

Errors

Returns the same errors as PwHash::hash.

pub fn hash_sensitive<Password: Bytes>( password: &Password, ) -> Result<Self, Error>

Hashes password with a random salt and a default configuration suitable for sensitive hashing, returning the hash, salt, and config upon success.

Errors

Returns the same errors as PwHash::hash.

impl<Hash: NewBytes + ResizableBytes + Zeroize, Salt: Bytes + Zeroize> PwHash<Hash, Salt>

pub fn hash_with_salt<Password: Bytes>( password: &Password, salt: Salt, config: Config, ) -> Result<Self, Error>

Hashes password with salt and config, returning the hash, salt, and config upon success.

The caller must provide a unique, unpredictable salt for each password. Prefer PwHash::hash unless an existing salt must be reused.

Errors

Returns an error if a work limit, memory limit, hash length, salt length, or password length is outside the supported range, or if the underlying Argon2 operation fails.

impl<Hash: Bytes + From<Vec<u8>> + Zeroize, Salt: Bytes + From<Vec<u8>> + Zeroize> PwHash<Hash, Salt>

pub fn from_string(hashed_password: &str) -> Result<Self, Error>

Available on crate feature base64 only.

Creates a new password hash instance by parsing hashed_password. Compatible with libsodium’s crypto_pwhash_str* functions, including valid Argon2 strings with non-default salt lengths or parallelism.

Errors

Returns an error if the string is malformed, uses an unsupported algorithm or version, omits a required field, or contains an invalid encoded value.

impl<Hash: Bytes + Zeroize, Salt: Bytes + Zeroize> PwHash<Hash, Salt>

pub fn to_encoded_string(&self) -> Result<String, Error>

Available on crate feature base64 only.

Returns a string-encoded representation of this hash, salt, and config, suitable for storage in a database.

The string returned is compatible with libsodium’s crypto_pwhash_str, crypto_pwhash_str_verify, and crypto_pwhash_str_needs_rehash functions when the hash length matches libsodium’s string format. The lower-level hashing API also supports variable-length hash output.

Errors

Returns an error if the stored parameters are invalid or the resulting string would not fit libsodium’s password-hash string format.

Example

use dryoc::pwhash::*;

let password = b"Come what come may, time and the hour runs through the roughest day.";

let pwhash = PwHash::hash_with_defaults(password).expect("unable to hash");
let pw_string = pwhash.to_encoded_string().expect("unable to encode hash");

let parsed_pwhash =
    PwHash::from_string_with_defaults(&pw_string).expect("couldn't parse hashed password");

parsed_pwhash.verify(password).expect("verification failed");
parsed_pwhash
    .verify(b"invalid password")
    .expect_err("verification should have failed");

pub fn verify<Password: Bytes>(&self, password: &Password) -> Result<(), Error>

Verifies password against this hash using its salt and configuration.

Errors

Returns an error if the password does not match, if the stored salt or configuration is invalid, or if the underlying Argon2 operation fails.

pub fn from_parts(hash: Hash, salt: Salt, config: Config) -> Self

Constructs a new instance from hash, salt, and config, consuming them.

This function does not validate the parts. Invalid values are reported when an operation such as PwHash::verify or PwHash::to_encoded_string uses them.

pub fn into_parts(self) -> (Hash, Salt, Config)

Moves the hash, salt, and config out of this instance, returning them as a tuple.

impl<Salt: Bytes + Zeroize> PwHash<Hash, Salt>

pub fn derive_keypair<Password: Bytes + Zeroize, PublicKey: NewByteArray<CRYPTO_BOX_PUBLICKEYBYTES> + Zeroize, SecretKey: NewByteArray<CRYPTO_BOX_SECRETKEYBYTES> + Zeroize>( password: &Password, salt: Salt, config: Config, ) -> Result<KeyPair<PublicKey, SecretKey>, Error>

Derives a keypair from password and salt, using config.

The same password and salt derive the same keypair. Store the salt, keep it unique per derived key, and do not treat it as secret.

Errors

Returns an error if a work limit, memory limit, salt length, or password length is outside the supported range, or if the underlying Argon2 operation fails.

impl PwHash<Hash, Salt>

pub fn hash_with_defaults<Password: Bytes>( password: &Password, ) -> Result<Self, Error>

Hashes password using default (interactive) config parameters, returning the Vec<u8>-based hash and salt, with config, upon success.

This function provides reasonable defaults, and is provided for convenience.

Errors

Returns an error if the password length is unsupported or the underlying Argon2 operation fails.

pub fn from_string_with_defaults(hashed_password: &str) -> Result<Self, Error>

Available on crate feature base64 only.

Parses the hashed_password string, returning a new hash instance upon success. Wraps PwHash::from_string, provided for convenience.

Errors

Returns an error if the string is malformed, uses an unsupported algorithm or version, omits a required field, or contains an invalid encoded value.

Trait Implementations

impl<Hash: Clone + Bytes + Zeroize, Salt: Clone + Bytes + Zeroize> Clone for PwHash<Hash, Salt>

fn clone(&self) -> PwHash<Hash, Salt>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Hash: Debug + Bytes + Zeroize, Salt: Debug + Bytes + Zeroize> Debug for PwHash<Hash, Salt>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de, Hash, Salt> Deserialize<'de> for PwHash<Hash, Salt>

where Hash: Deserialize<'de> + Bytes + Zeroize, Salt: Deserialize<'de> + Bytes + Zeroize,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<Hash, Salt> Serialize for PwHash<Hash, Salt>

where Hash: Serialize + Bytes + Zeroize, Salt: Serialize + Bytes + Zeroize,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<Hash, Salt> Zeroize for PwHash<Hash, Salt>

where Hash: Zeroize + Bytes, Salt: Zeroize + Bytes,

fn zeroize(&mut self)

Zero out this object from memory using Rust intrinsics which ensure the zeroization operation is not “optimized away” by the compiler.