public final class KdfProfile

The portable password key derivation this package uses, as a versioned profile rather than a set of numbers each caller picks.

Why PBKDF2 and not something better

Argon2id and scrypt are better password KDFs, and neither exists in a browser. Web Crypto implements exactly one – PBKDF2 – and a password vault whose whole point is that Android, iOS and the browser derive the same key from the same password cannot use a KDF that one of the three has to emulate in application code. A JavaScript Argon2 would be orders of magnitude slower than the native one the phone uses, which in practice means the parameters get lowered until the browser is usable and every platform is then weaker than PBKDF2 would have been.

So: PBKDF2-HMAC-SHA256, with the iteration count carried in the envelope so it can be raised without breaking anything already written. current() is what new material is derived with; needsUpgrade() tells a caller that an envelope it just opened was written under a weaker profile and should be rewrapped.

Bounds

The iteration count is clamped into MIN_ITERATIONS to MAX_ITERATIONS on the way in and rejected rather than clamped on the way out of a parsed envelope. The asymmetry is the point: an attacker who can edit stored bytes would otherwise set the count to 1 and turn a password check into a guessable one, or set it to two billion and make the application hang on open. A count outside the range in a stored envelope is VaultError.UNSUPPORTED_FORMAT.

Where the work happens

The derivation is one native call on every port that has one (Util.pbkdf2), and a pure Java loop over Hmac where there is none. The pure Java path produces identical bytes – it is RFC 8018 with no latitude in it – but 600000 iterations of software HMAC is slow enough to be a problem, so a port without the hook should add one rather than rely on it.