Interface PasswordHashingService

All Known Implementing Classes:

DefaultPasswordHashingService

public interface PasswordHashingService

Front-door facade for the Phase-1a password hashing and verification pipeline.

The pipeline order is fixed:

  parse -> validate -> resolveProvider -> resolvePepper
        -> verify -> rehashDecision

verify(char[], String) returns only CredentialVerificationResult; the boolean shape of the experimental API is intentionally gone (see CWE-287, CWE-203).

needsRehash(String) is callable after a successful verify (or independently) to drive transparent upgrades against a compare-and-swap credential store.

Method Summary

Modifier and Type	Method	Description
PasswordHashResult	hash(char[] password)	Produces a fresh hash for the given password under the active policy.
default PasswordHashResult	hash(SecretValue password)	SecretValue overload for hash(char[]).
RehashDecision	needsRehash(String encodedHash)	Reports whether the supplied envelope should be rehashed under the active policy.
CredentialVerificationResult	verify(char[] password, String encodedHash)	Runs the verification pipeline on the supplied envelope.
default CredentialVerificationResult	verify(SecretValue password, String encodedHash)	SecretValue overload for verify(char[], String).
CredentialVerificationResult	verifyAgainstNothing(char[] password)	Convenience entry point for callers that already know there is no stored envelope to verify against (typically "unknown user" paths).
default CredentialVerificationResult	verifyAgainstNothing(SecretValue password)	SecretValue overload for verifyAgainstNothing(char[]).

Method Details

hash

PasswordHashResult hash(char[] password)

Produces a fresh hash for the given password under the active policy.

Parameters:

password - caller-owned character buffer; the implementation must not modify or zero it

verify

CredentialVerificationResult verify(char[] password,
 String encodedHash)

Runs the verification pipeline on the supplied envelope.

needsRehash

RehashDecision needsRehash(String encodedHash)

Reports whether the supplied envelope should be rehashed under the active policy.

verifyAgainstNothing

CredentialVerificationResult verifyAgainstNothing(char[] password)

Convenience entry point for callers that already know there is no stored envelope to verify against (typically "unknown user" paths). The implementation still performs a comparable KDF call so the response is not distinguishable from a real verification (CWE-203, CWE-208).

hash

default PasswordHashResult hash(SecretValue password)

SecretValue overload for hash(char[]). The borrowed char[] copy returned by SecretValue.asChars() is zeroed in a finally block (CWE-226).

verify

default CredentialVerificationResult verify(SecretValue password,
 String encodedHash)

SecretValue overload for verify(char[], String).

verifyAgainstNothing

default CredentialVerificationResult verifyAgainstNothing(SecretValue password)

SecretValue overload for verifyAgainstNothing(char[]).