Skip to main content

Module pwhash

dryoc

Module pwhash 

Source
Expand description

§Password hashing functions

PwHash implements libsodium’s password hashing functions, based on Argon2.

Argon2 is a memory-hard password hashing function. Its work and memory settings make each password guess more expensive, which slows offline guessing if a password database is stolen. These settings do not compensate for weak passwords, so applications should still encourage long, unique passwords.

You should use PwHash when you want to:

  • authenticate with passwords, and store their salted hashes in a database
  • derive secret keys based on passphrases

Use a general-purpose hash such as crate::generichash or crate::sha256 for arbitrary data. Password hashing is deliberately much more expensive.

If the serde feature is enabled, the serde::Deserialize and serde::Serialize traits will be implemented for PwHash.

§Rustaceous API example

use dryoc::pwhash::*;

// A strong passphrase
let password = b"But, for my own part, it was Greek to me.";

// Hash the password, generating a random salt
let pwhash = PwHash::hash_with_defaults(password).expect("unable to hash");

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

§Using a custom config, or your own salt

use dryoc::pwhash::*;

// Generate a random salt
let mut salt = Salt::default();
salt.resize(dryoc::constants::CRYPTO_PWHASH_SALTBYTES, 0);
dryoc::rng::copy_randombytes(&mut salt);

// A strong passphrase
let password = b"What's in a name? That which we call a rose\n
                 By any other word would smell as sweet...";

// Start with a preset, then increase its work factor if your deployment can
// tolerate the extra time. Benchmark the result on the slowest target.
let mut config = Config::interactive()
    .with_opslimit(dryoc::constants::CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE + 1);

// With customized configuration parameters, the return type must be explicit.
let pwhash: VecPwHash = PwHash::hash_with_salt(password, salt, config)
    .expect("unable to hash password with salt and custom config");

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

§Deriving a keypair from a passphrase and salt

use dryoc::keypair::StackKeyPair;
use dryoc::pwhash::*;

// Generate a random salt
let mut salt = Salt::default();
salt.resize(dryoc::constants::CRYPTO_PWHASH_SALTBYTES, 0);
dryoc::rng::copy_randombytes(&mut salt);

// Use a strong passphrase
let password = b"Is this a dagger which I see before me, the handle toward my hand?";

let keypair: StackKeyPair = PwHash::derive_keypair(password, salt, Config::interactive())
    .expect("couldn't derive keypair");

// now you can use `keypair` with DryocBox

§String-based encoding

See PwHash::to_encoded_string() for an example of using the string-based encoding API, compatible with crypto_pwhash_str* functions.

§Additional resources

Re-exports§

pub use crate::classic::crypto_pwhash::PasswordHashAlgorithm;

Modules§

protectedprotected
Protected memory type aliases for PwHash

Structs§

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

Type Aliases§

Hash
Heap-allocated hash type alias for password hashing with PwHash.
Salt
Heap-allocated salt type alias for password hashing with PwHash.
VecPwHash
Vec<u8>-based PwHash type alias, provided for convenience.