Getting started

Your first stored password

From an empty Rust project to a hash you can store and verify, in one file.

What do I need?

Rust 1.85 or newer for the library. Its manifest declares 1.75, but the bcrypt dependency it pulls in today needs 1.85: on Rust 1.80 the build stops while reading a dependency's manifest, and on 1.85 it succeeds. The hsh command-line tool needs Rust 1.88. CI tests the workspace on Linux, macOS and Windows.

How do I add it?

cargo add hsh

or in Cargo.toml:

[dependencies]
hsh = "0.0.10"

0.0.10 is the latest release of hsh on crates.io. No Cargo features are on by default.

How do I hash and verify a password?

use hsh::{api, Outcome, Policy};

fn main() -> Result<(), hsh::Error> {
    let policy = Policy::owasp_minimum_2025();

    // At sign-up: store this string.
    let stored = api::hash(&policy, "correct horse battery staple")?;

    // At sign-in: check the password, and save the new hash if one comes back.
    match api::verify_and_upgrade(&policy, "correct horse battery staple", &stored)? {
        Outcome::Valid { rehashed: Some(new_hash) } => {
            println!("signed in; save {new_hash}");
        }
        Outcome::Valid { rehashed: None } => println!("signed in"),
        Outcome::Invalid => println!("wrong password"),
    }
    Ok(())
}

stored is a PHC string such as $argon2id$v=19$m=19456,t=2,p=1$..., which carries the algorithm, its parameters and the salt, so it is all you need to store.

How do I use another algorithm?

Start a builder from the preset and change the primary algorithm:

use hsh::{api, Policy, PrimaryAlgorithm};
use hsh::policy::PolicyBuilder;

let policy = PolicyBuilder::from_preset(&Policy::owasp_minimum_2025())
    .primary(PrimaryAlgorithm::Bcrypt)
    .build()?;
let stored = api::hash(&policy, "hunter2")?; // $2b$10$...

The choices are Argon2id, Bcrypt, Scrypt and Pbkdf2. Whatever the policy, verify_and_upgrade accepts hashes from all four.

How do I use it from the shell?

cargo install hsh-cli --locked
echo -n "correct horse battery staple" | hsh hash --algorithm argon2id

Where next?

  • The API guide for presets, the builder, Cargo features and the crates in the workspace.
  • The migration guide if you are coming from bcrypt, rust-argon2, argonautica or an older hsh.
  • The full API reference on docs.rs.