Expand description
§ironauth-hash-scheme
Algorithm-tagged verification of foreign password hashes.
This is the one layer of an identity-provider migration that is useful to somebody who is not running IronAuth. If you are importing users out of another system, you have a column full of strings in half a dozen formats and you need to answer one question per row: does this password match. That is all this crate does.
It depends on no ironauth-* crate, and that is deliberate rather than incidental.
§Supported schemes
| Scheme | Encodings |
|---|---|
| bcrypt | $2a$, $2b$, $2x$, $2y$ |
| Argon2 | $argon2i$, $argon2d$, $argon2id$ |
| scrypt | $scrypt$ (PHC string) |
| PBKDF2 | $pbkdf2-sha256$, $pbkdf2-sha512$ (PHC string) |
| Firebase | modified scrypt, with the project’s base64 signer key and salt separator |
| SHA-crypt | $5$ (SHA-256), $6$ (SHA-512), with the optional rounds= |
| LDAP / RFC 2307 | {SHA}, {SSHA}, {SHA256}, {SSHA256}, {SHA512}, {SSHA512} |
The LDAP digests carry no cost parameter at all, and that is the reason
Scheme::rehash_is_urgent exists. They are one unsalted or lightly salted digest pass,
so there is nothing to bound and nothing an import check can do to make a stolen row
expensive to attack; the only fix is to stop storing them, which means rehashing on the
first successful login rather than eventually. The MD5 LDAP schemes ({MD5}, {SMD5})
are deliberately NOT recognized.
The four bcrypt variants are listed separately because they are not interchangeable
prefixes: $2x$ exists to reproduce a bug in a specific PHP implementation, and treating it
as $2b$ silently fails to verify passwords that were valid in the source system.
§Cost bounds
Every scheme carries bounds on its cost parameters, checked at parse time. A record whose cost is outside them is rejected with a typed per-record error rather than accepted and verified later.
This matters more on import than anywhere else. A cost parameter is an attacker-controlled integer when it arrives in an import file, and a bcrypt cost of 31 or an Argon2 memory parameter of several gigabytes is a denial of service against the importing server, not a strong password hash. The bounds are the reason an import of untrusted data cannot be turned into a resource-exhaustion attack by editing one column.
§Usage
use ironauth_hash_scheme::{ForeignHash, HashError, Scheme};
// Parsing is where the cost bounds are enforced, so an out-of-bounds record is refused
// before anything expensive happens with it.
let hash = ForeignHash::parse("$2b$12$K3JNi5Aw17Xa9x6nHtDlKuLGrLmjbJmn0BEjKcOJ1jRfLIhs3xLtC")?;
assert_eq!(hash.scheme(), Scheme::Bcrypt);
assert_eq!(hash.tag(), "bcrypt");
// Verification dispatches on the recognized scheme and FAILS CLOSED: a wrong password and
// a corrupt stored value both answer false, and neither panics.
assert!(!hash.verify(b"not the password"));
// An out-of-bounds cost is a typed error, not a slow verification later.
assert!(matches!(
ForeignHash::parse("$2b$99$K3JNi5Aw17Xa9x6nHtDlKuLGrLmjbJmn0BEjKcOJ1jRfLIhs3xLtC"),
Err(HashError::OutOfBounds(_))
));Whether a verified hash should be REPLACED with your own scheme is deliberately not decided here. This crate answers “does this match”, and the rehash policy belongs to whatever owns your password policy, because it depends on parameters this crate has no view of.
§Why it is a separate crate
Two reasons, and the second is the one that constrains its contents.
It is independently useful: verifying a foreign hash has nothing to do with issuing tokens, and somebody migrating between two other providers can use this without adopting anything else.
And it is the only part of the import path that can be published on its own. Everything
else in the import pipeline reaches into the store, the envelope substrate, or the audit
log. Adding an ironauth-* dependency here would revoke that quietly, so
the_crate_depends_on_no_ironauth_crate asserts the absence rather than leaving it to a
comment.
§Licence
MIT OR Apache-2.0. The algorithm-tagged foreign password-hash scheme layer (issue #55).
This is the passwap-style reusable core: a stored foreign hash is PARSED into a
recognized Scheme, VERIFIED against a candidate password by dispatching on
that scheme, and (at import) BOUNDS-CHECKED so an attacker-supplied cost
parameter cannot turn a later login verification into a denial-of-service vector
(the Kratos lesson: out-of-bounds imported costs are rejected at import, never
silently accepted). The module has NO database or store dependency, so it is
self-contained and the login path (ironauth-oidc) can consume it directly.
§Storage contract
A foreign hash is stored AS-IS: the canonical, self-describing string is the
verifier and the Scheme::tag is the non-secret algorithm label. There is no
function here that recovers a plaintext password; every scheme is a one-way
verifier.
§Recognized schemes and their string forms
| Scheme | Detected prefix |
|---|---|
Scheme::Bcrypt | $2a$ / $2b$ / $2x$ / $2y$ |
Scheme::Scrypt | $scrypt$ (PHC) |
Scheme::Pbkdf2 | $pbkdf2-sha256$ / $pbkdf2-sha512$ |
Scheme::Argon2 | $argon2i$ / $argon2d$ / $argon2id$ |
Scheme::FirebaseScrypt | $fbscrypt$ (canonical, see below) |
Scheme::ShaCrypt | $5$ (SHA-256) / $6$ (SHA-512) |
Scheme::Ldap | {SHA} / {SSHA} / {SHA256} / … |
§Two schemes with no cost to bound, and why that is the dangerous case
Every bound in this crate exists because an attacker-supplied cost turns a later
login into a denial-of-service vector. The LDAP schemes invert that: {SHA} and
its relatives are a SINGLE unsalted or lightly salted digest pass, so they verify
in microseconds and there is no cost parameter to reject. The hazard is not that
verification is slow, it is that the stored hash is nearly free to attack offline.
So this crate recognizes them (a user who cannot be verified cannot be migrated at
all) and Scheme::rehash_is_urgent reports which schemes must not survive a
first successful login. {MD5} and {SMD5} are deliberately NOT recognized: MD5
is not in the issue’s list and accepting it would be adding a scheme nothing asked
for on the strength of it being easy.
Firebase’s modified scrypt is not self-describing in the wild (its
account-wide signer key, salt separator, and cost live outside the per-user
hash), so this crate defines a canonical, self-contained serialization that
round-trips through firebase_stored:
$fbscrypt$n=<mem_cost>,r=<rounds>,p=1$<salt_sep_b64>$<signer_key_b64>$<salt_b64>$<hash_b64>Structs§
- Foreign
Hash - A parsed, bounds-checked foreign password hash (issue #55): the recognized
Schemeand the canonical stored verifier string. Constructing one proves the string is a well-formed hash of a recognized scheme whose cost parameters are within the documented bounds, so a laterForeignHash::verifycan never be a denial-of-service vector.
Enums§
- Hash
Error - Why a foreign hash string could not be accepted at import (issue #55).
- Scheme
- A recognized foreign password-hash scheme (issue #55). The variant is the algorithm tag stored alongside the hash; verification dispatches on it.
Constants§
- MAX_
ARGO N2_ MEMORY_ KIB - The documented maximum Argon2 memory cost, in KiB, accepted at import.
- MAX_
ARGO N2_ PARALLELISM - The documented maximum Argon2 parallelism accepted at import.
- MAX_
ARGO N2_ PASSES - The documented maximum Argon2 pass count accepted at import.
- MAX_
BCRYPT_ COST - The documented maximum bcrypt cost accepted at import (a work factor of
2^cost). Above this a single verification is a denial-of-service vector, so the record is rejected at import (the Kratos lesson). - MAX_
FIREBASE_ MEM_ COST - The documented maximum Firebase modified-scrypt memory cost (
log2(N)) accepted at import. - MAX_
FIREBASE_ ROUNDS - The documented maximum Firebase modified-scrypt rounds (
r) accepted at import. - MAX_
PBKD F2_ ITERATIONS - The documented maximum PBKDF2 iteration count accepted at import.
- MAX_
SCRYPT_ LOG_ N - The documented maximum scrypt
log2(N)accepted at import (CPU/memory cost). - MAX_
SCRYPT_ P - The documented maximum scrypt parallelism
paccepted at import. - MAX_
SCRYPT_ R - The documented maximum scrypt block-size parameter
raccepted at import. - MAX_
SHA_ CRYPT_ ROUNDS - The documented maximum SHA-crypt
rounds=accepted at import. glibc permits up to 999999999, which is minutes of CPU for ONE verification and therefore exactly the vector the bounds exist for. A million rounds is already far beyond any deployment that expects to serve logins. - MIN_
BCRYPT_ COST - The minimum bcrypt cost bcrypt itself permits; below it the hash is malformed.
- MIN_
SHA_ CRYPT_ ROUNDS - The minimum SHA-crypt
rounds=glibc itself accepts; below it the string is malformed rather than merely cheap.
Functions§
- firebase_
stored - Serialize Firebase modified-scrypt operands into this crate’s canonical
$fbscrypt$storage string. The four byte operands are supplied already standard-base64-encoded exactly as a Firebase account export carries them.