Interface PasswordHashProvider

All Known Implementing Classes:
Pbkdf2PasswordHashProvider
public interface PasswordHashProvider
Service-provider contract for a concrete password hashing implementation.

Providers are discovered through Java's ServiceLoader or registered explicitly by the bootstrap layer. Phase 1a ships a single PBKDF2 provider in security-core; the optional security-crypto-bc module adds Argon2id, bcrypt and scrypt.

Providers must not:

  • change the global JCA provider order through Security.insertProviderAt or equivalent;
  • log password material, derived key material or secret salts;
  • throw on a genuine credential mismatch — return ProviderVerificationResult.NotMatched instead.

Pepper material is threaded through as an Optional byte array; Phase 1a always supplies Optional.empty() (the NoOpPepperService).

  • Method Details

    • providerId

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

    • algorithm

      String algorithm()
      Canonical algorithm identifier this provider handles by default.

    • supports

      default boolean supports(String providerId, String algorithm)
      Returns whether this provider can serve the given combination. The default implementation requires an exact match on both identifiers; providers that handle multiple algorithms or migration aliases override this.

    • hash

      PasswordHashResult hash(char[] password, PasswordHashPolicy policy, Optional<PepperReference> pepper)
      Derives a fresh hash for the supplied password under the active policy.
      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

      ProviderVerificationResult verify(char[] password, PasswordHashEnvelope envelope, Optional<PepperReference> pepper)
      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.

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

    • resourceEstimate

      default ResourceEstimate resourceEstimate(Map<String,String> parameters)
      Optional resource estimate for the supplied parameter map. Default: ResourceEstimate.UNKNOWN.