Experimental cryptographic software. Do not use it to store production passwords.
Prefer Argon2id, scrypt, bcrypt, or your platform’s password APIs until ForgeHash has had serious independent review.
ForgeHash-B3 is a configurable, memory-hard password hashing construction for research, benchmarking, and cross-language ports. The first variant uses BLAKE3.
| Algorithm | ForgeHash-B3 |
| Encoded id | forgeh |
| Version | v=1 |
| .NET | ForgeHash · ForgeHashX · tool ForgeHash.Cli |
| PyPI / npm / crates | forgeh · forgehx (same names on npm / crates.io) |
| Spec | SPECIFICATION.md |
| Docs site | https://thomasbehappy.github.io/Forgehash/ |
Encoded form (unpadded RFC 4648 Base64; parameter order always m,t,p):
$forgeh$v=1$m=<memoryKiB>,t=<iterations>,p=<parallelism>$<salt-b64>$<hash-b64>
Separate research sandbox with a custom ForgeX sponge (no BLAKE3). Encoded as $forgehx$v=0$…. Not production-ready, not reviewed, not compatible with B3. Spec and .NET reference: docs/forgehx/. Toy vectors + KATs: implementers/x0/. Sample: samples/ForgeHash.X.Sample/. CI: .github/workflows/forgehx.yml. Empirical notes: docs/forgehx/RESEARCH_NOTES.md. Full research paper (PDF): docs/forgehx/paper/ForgeHash_X_Research_Paper.pdf. Site: X Vectors.
| Audience | Start here |
|---|---|
| App developers (.NET) | docs/USAGE.md |
| Language porters | docs/IMPLEMENTING.md + implementers/v1/ |
| Researchers | docs/RESEARCH_REPORT.md |
| Cryptographers reviewing the design | SPECIFICATION.md |
| Security reports | SECURITY.md |
Static HTML under website/, published by GitHub Actions (Pages Source must be GitHub Actions, not the /docs folder).
npx --yes serve websiteSPECIFICATION.md Normative B3 algorithm
docs/ Usage, porting, research
docs/forgehx/ ForgeHash-X sandbox spec + README
implementers/v1/ Official B3 vectors + checklist
implementers/x0/ ForgeHash-X toy vectors + ForgeX KATs
samples/ForgeHash.X.Sample/ ForgeHash-X usage demo
src/ForgeHash.Core .NET B3 reference library
src/ForgeHash.X.Core .NET X sandbox (ForgeX sponge)
src/ForgeHash.Analysis Traces, TMTO heuristic, collision engine
src/ForgeHash.CollisionLab Windows GUI for mass uniqueness hunts
src/ForgeHash.Visualizer Export analysis artifacts
src/ForgeHash.Cli hash / verify / benchmark / vector
langs/ B3 (`forgeh`) + X (`forgehx`) ports
tests/ xUnit suites + frozen vectors
website/ GitHub Pages site
# .NET — https://www.nuget.org/packages/ForgeHash/
dotnet add package ForgeHash --prerelease
dotnet add package ForgeHashX --prerelease
dotnet tool install -g ForgeHash.Cli --prerelease
# Python / Node / Rust
pip install forgeh --pre # https://pypi.org/project/forgeh/
pip install forgehx --pre # https://pypi.org/project/forgehx/
npm install forgeh@experimental # https://www.npmjs.com/package/forgeh
npm install forgehx@experimental # https://www.npmjs.com/package/forgehx
cargo add forgeh --precise 1.0.0-experimental # https://crates.io/crates/forgeh
cargo add forgehx --precise 0.1.0-experimental # https://crates.io/crates/forgehxusing ForgeHash;
using ForgeHashApi = ForgeHash.ForgeHash; // class name matches the namespace
string encoded = ForgeHashApi.HashPassword(password, ForgeHashParameters.Interactive);
bool ok = ForgeHashApi.VerifyPassword(password, encoded);forgeh hash --algo b3 --password-stdin
dotnet run --project samples/ForgeHash.Sample -- "demo-password"Publisher ops: docs/PUBLISHING.md.
| Language | Path | Registry | Notes |
|---|---|---|---|
| Rust | langs/rust/forgeh |
crates.io/forgeh | Native + C ABI |
| Node.js | langs/nodejs/forgeh |
npm/forgeh | Native JS |
| Python | langs/python/forgeh |
PyPI/forgeh | Native Python |
| C++ | langs/cpp/forgeh |
— | C++20 over Rust C ABI |
| PHP | langs/php/forgeh |
— | FFI over Rust (ext-ffi) |
X ports use the same registries under forgehx / ForgeHashX. See langs/README.md.
Claim ForgeHash-B3 v1 compatible only when every official vector matches bit-exactly.
dotnet build ForgeHash.sln -c Release
dotnet test ForgeHash.sln -c Release| Profile | Memory | Iterations | Parallelism |
|---|---|---|---|
| Development | 8192 KiB | 1 | 1 |
| Interactive | 65536 KiB | 3 | 1 |
| Sensitive | 262144 KiB | 4 | 2 |
Development is for tests and mass campaigns only.
Report: docs/RESEARCH_REPORT.md (includes a logged run of 100 000 random pairs with 0 collisions at Development cost).
# Mass uniqueness / collision lab (Windows) — B3 or X via Algorithm combo
dotnet run --project src/ForgeHash.CollisionLab -c Release
# Reference graphs / TMTO heuristic export
dotnet run --project src/ForgeHash.Visualizer -c Release -- all --out artifacts/analysis --memory 8192 --parallelism 2
# BenchmarkDotNet
dotnet run --project src/ForgeHash.Benchmarks -c Release# CLI
dotnet run --project src/ForgeHash.Cli -- hash --memory 8192 --iterations 1 --parallelism 1
dotnet run --project src/ForgeHash.Cli -- verify "$forgeh$..."SECURITY.mdLICENSEAI.md— AI assisted some development and research drafting; most design and writing is human-authored