Crate hsh 

Hash (HSH) — multi-algorithm password hashing for Rust

PHC-formatted hash storage with constant-time verification, KMS-backed peppering, FIPS 140-3 fail-closed contract, and automatic rehash on policy drift. Built on the RustCrypto stack with #![forbid(unsafe_code)] workspace-wide.

Quick start

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

fn main() -> Result<(), hsh::Error> {
    let policy = Policy::owasp_minimum_2025();
    let stored = api::hash(&policy, "correct horse battery staple")?;

    let outcome = api::verify_and_upgrade(
        &policy,
        "correct horse battery staple",
        &stored,
    )?;

    assert!(outcome.is_valid());
    assert!(!outcome.needs_rehash());
    Ok(())
}

What hsh ships in v0.0.9

Algorithm	Status	OWASP-2025 default
Argon2id (default)	✅ Recommended	m = 19 456 KiB, t = 2, p = 1
Bcrypt	✅ Hardened — 72-byte safety rail (CVE-2025-22228)	cost = 10
Scrypt	✅ Configurable	N = 2^17, r = 8, p = 1
PBKDF2-HMAC-SHA-256/512	✅ FIPS-eligible	iters = 600 000 / 210 000
Argon2i / Argon2d	Verify-only (legacy)	—

The verifier accepts any of the four production algorithms above interchangeably (plus the legacy Argon2 variants); the live Policy only governs new hashes and rehash targets.

What hsh is not

• Not post-quantum cryptography. Memory-hard KDFs like Argon2id raise the cost of offline brute-force on both classical and quantum hardware (Grover yields only a √-speedup), but they are not PQ primitives. For ML-KEM, ML-DSA, or SLH-DSA, use aws-lc-rs.
• Not a self-validating FIPS 140-3 module. The crate carries a Backend::Fips140Required contract — api::hash refuses to mint hashes outside FIPS-routed primitives — but the underlying crypto today is the pure-Rust RustCrypto stack. The dedicated hsh-backend-awslc follow-up routes through the validated aws-lc-rs FIPS module without changing the public API. See doc/FIPS.md and doc/adr/0004-fips-strategy.md.
• Not a general-purpose digest library. For SHA-2 / SHA-3 / BLAKE3 content addressing, use the companion hsh-digest crate.

Architecture

• Policy-driven: a versioned Policy declares the primary algorithm and per-algorithm parameters. Construct via the Policy::owasp_minimum_2025 / Policy::rfc9106_first_recommended / Policy::fips_140_pbkdf2 presets or the policy::PolicyBuilder.
• Auto-rehash on drift: api::verify_and_upgrade returns an Outcome whose Valid variant folds the new PHC string into rehashed: Option<String> — Some(_) precisely when the stored hash falls below current policy. The caller persists the new value on next login.
• Optional peppering: with the pepper feature, Policy::with_pepper attaches an HMAC-SHA-256 pepper provider with versioned key rotation. Hashes carry a hsh-pepper:<version>: wrapper; rotation is non-destructive.
• Structured errors: Error is a #[non_exhaustive] thiserror enum with Clone + Send + Sync and a typed error::HashingErrorKind discriminant for downcasting without parsing strings.

Cargo features

Feature	Default	What it adds
pepper	off	KMS-backed peppering via the hsh-kms companion crate
fips	off	Forward-compat marker for the aws-lc-rs FIPS backend
compat-v0_0_x	off	Re-exposes the pre-0.0.9 stringly-typed API for migration

License

Dual-licensed under MIT or Apache-2.0, at your option.

Re-exports

pub use backend::Backend;

pub use error::Error;

pub use error::Result;

pub use outcome::Outcome;

pub use policy::Policy;

pub use policy::PrimaryAlgorithm;

Modules

algorithms

Password hashing algorithm wrappers. Password hashing algorithm wrappers built on the RustCrypto stack.

api

High-level enterprise API — PHC-format hashing and api::verify_and_upgrade with policy-driven rehash. High-level enterprise API: PHC-formatted hash storage with multi-algorithm verification and automatic rehash on policy drift.

backend

Backend selector — declares whether the Policy requires FIPS 140-3 validated crypto. Backend selector — declares whether the crate::Policy requires FIPS 140-3 validated crypto.

error

Structured error type for fallible operations. Structured error type for the hsh crate.

models

Core data models — models::hash::Hash and the models::hash_algorithm::HashAlgorithm enum.

outcome

Verification outcome::Outcome reported by api::verify_and_upgrade. The Outcome of a verification — used by crate::api::verify_and_upgrade to signal whether the caller should re-hash the password under the current crate::Policy.

policy

Versioned policy::Policy describing primary algorithm + params. Versioned Policy describing the primary algorithm and per-algorithm parameters used by the high-level crate::api surface.

Functions

run

Library entry point used by the hsh binary.