Struct PwHash 

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

Available on crate feature alloc only.

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

The hash bytes are redacted from Debug output and wiped when the instance is dropped. PwHash::into_parts transfers ownership of the hash to the caller, who is then responsible for its handling and zeroization.

Implementations

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

pub fn hash<Password: Bytes + ?Sized>( 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.

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

pub fn hash_with_salt<Password: Bytes + ?Sized>( 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 = VecPwHash::hash(password, Config::interactive()).expect("unable to hash");
let pw_string = pwhash.to_encoded_string().expect("unable to encode hash");

let parsed_pwhash = VecPwHash::from_string(&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 + ?Sized>( &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. The returned hash no longer benefits from the instance’s drop-time zeroization.

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

pub fn derive_keypair<PublicKey: NewByteArray<CRYPTO_BOX_PUBLICKEYBYTES> + Zeroize, SecretKey: NewByteArray<CRYPTO_BOX_SECRETKEYBYTES> + Zeroize, Password: Bytes + Zeroize + ?Sized>( 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.

Trait Implementations

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

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<Hash: Bytes + Zeroize, Salt: 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: Bytes + Zeroize, Salt: Bytes + Zeroize> Drop for PwHash<Hash, Salt>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

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.