Skip to main content

Crate ironauth_hash_scheme

Crate ironauth_hash_scheme 

Source
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

SchemeEncodings
bcrypt$2a$, $2b$, $2x$, $2y$
Argon2$argon2i$, $argon2d$, $argon2id$
scrypt$scrypt$ (PHC string)
PBKDF2$pbkdf2-sha256$, $pbkdf2-sha512$ (PHC string)
Firebasemodified 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

SchemeDetected 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§

ForeignHash
A parsed, bounds-checked foreign password hash (issue #55): the recognized Scheme and 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 later ForeignHash::verify can never be a denial-of-service vector.

Enums§

HashError
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_ARGON2_MEMORY_KIB
The documented maximum Argon2 memory cost, in KiB, accepted at import.
MAX_ARGON2_PARALLELISM
The documented maximum Argon2 parallelism accepted at import.
MAX_ARGON2_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_PBKDF2_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 p accepted at import.
MAX_SCRYPT_R
The documented maximum scrypt block-size parameter r accepted 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.