Class Pbkdf2PasswordHashProvider

java.lang.Object

com.svenruppert.jsentinel.credential.password.pbkdf2.Pbkdf2PasswordHashProvider

All Implemented Interfaces:

PasswordHashProvider

public final class Pbkdf2PasswordHashProvider
extends Object
implements PasswordHashProvider

JDK/JCA-only PBKDF2 password hash provider.

This is the secure core default and must remain JDK-only so that security-core introduces no runtime dependencies. Modern memory-hard algorithms (Argon2id, scrypt) live in the optional security-crypto-bc module that ships in Phase 1b.

Implementation notes:

• The provider never modifies the global JCA provider order. A specific JCA provider can be pinned through the jcaProviderName constructor argument; the lookup is performed via SecretKeyFactory.getInstance(String, String) on every call.
• Salt is drawn fresh from a caller-supplied SecureRandom for every hash(...) so that two identical passwords never yield identical envelopes (CWE-759 / CWE-760).
• The constant-time comparison uses MessageDigest.isEqual(byte[], byte[]).
• Temporary byte[] arrays holding salt and derived key material are zeroed before the method returns. The PBEKeySpec.clearPassword() hook is invoked even on failure paths.
• The provider returns ProviderVerificationResult.ProviderError on JCA-level failures (missing algorithm or provider, invalid key spec) so the surrounding pipeline can keep public messaging generic (CWE-209).

Constructor Summary

Constructors

Constructor	Description
Pbkdf2PasswordHashProvider()
Pbkdf2PasswordHashProvider(PasswordHashCodec codec, SecureRandom random, Optional<String> jcaProviderName)	Test/SPI constructor that lets callers inject a deterministic SecureRandom (for known-answer assertions) or pin the JCA provider (for FIPS-mode deployments).
Pbkdf2PasswordHashProvider(String jcaProviderName)

Method Summary

Modifier and Type	Method	Description
String	algorithm()	Canonical algorithm identifier this provider handles by default.
PasswordHashResult	hash(char[] password, PasswordHashPolicy policy, Optional<PepperReference> pepper)	Derives a fresh hash for the supplied password under the active policy.
String	providerId()	Logical provider identifier, stable across releases.
ProviderVerificationResult	verify(char[] password, PasswordHashEnvelope envelope, Optional<PepperReference> pepper)	Verifies the supplied password against the parsed envelope.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface PasswordHashProvider

resourceEstimate, supports

Modifier and Type	Method	Description
default ResourceEstimate	resourceEstimate(Map<String,String> parameters)	Optional resource estimate for the supplied parameter map.
default boolean	supports(String providerId, String algorithm)	Returns whether this provider can serve the given combination.

Constructor Details

Pbkdf2PasswordHashProvider

public Pbkdf2PasswordHashProvider()

Pbkdf2PasswordHashProvider

public Pbkdf2PasswordHashProvider(String jcaProviderName)

Pbkdf2PasswordHashProvider

public Pbkdf2PasswordHashProvider(PasswordHashCodec codec,
 SecureRandom random,
 Optional<String> jcaProviderName)

Test/SPI constructor that lets callers inject a deterministic SecureRandom (for known-answer assertions) or pin the JCA provider (for FIPS-mode deployments).

Method Details

providerId

public String providerId()

Description copied from interface: PasswordHashProvider

Logical provider identifier, stable across releases. Stored in the envelope so that verification can resolve the same implementation regardless of the active policy.

Specified by:

providerId in interface PasswordHashProvider

algorithm

public String algorithm()

Description copied from interface: PasswordHashProvider

Canonical algorithm identifier this provider handles by default.

Specified by:

algorithm in interface PasswordHashProvider

hash

public PasswordHashResult hash(char[] password,
 PasswordHashPolicy policy,
 Optional<PepperReference> pepper)

Description copied from interface: PasswordHashProvider

Derives a fresh hash for the supplied password under the active policy.

Specified by:

hash in interface PasswordHashProvider

Parameters:

password - caller-owned character array; the provider must not zero or modify it

policy - active policy from which to read parameters

pepper - resolved active pepper key, or Optional.empty() when peppering is off; the provider applies the pepper as HMAC-SHA-256(pepper.key, KDF(password,salt)) and writes the pepper.keyId into the envelope

verify

public ProviderVerificationResult verify(char[] password,
 PasswordHashEnvelope envelope,
 Optional<PepperReference> pepper)

Description copied from interface: PasswordHashProvider

Verifies the supplied password against the parsed envelope.

Implementations must use a constant-time comparison and must never throw on a genuine mismatch. Provider-level failures (missing JCA service, unsupported parameter combination) collapse onto ProviderVerificationResult.ProviderError so the pipeline can keep public messaging generic.

Specified by:

verify in interface PasswordHashProvider

Parameters:

pepper - resolved pepper key matching envelope.pepperKeyId(), or Optional.empty() when the envelope has no pepper field