Interface PasswordEncoder

public interface PasswordEncoder
Encodes passwords for storage and verifies a password against a stored encoding.

Implementations must honour the following contract:

  • The encoding is a salted, one-way hash. Encoding the same password twice produces different results, and the encoding never contains the raw password.
  • Every character of the raw password is significant. Implementations must not truncate the password or alter its whitespace or case.
  • Blank values, which are null, empty or contain only whitespace, are rejected. The parameters of encode(String) and matches(String, String) are constrained with NotBlank, so an implementation that is a validated bean throws a ConstraintViolationException for them.
  • matches(String, String) returns false, instead of throwing an exception, for an encoded password that is not blank and that the implementation cannot parse.
  • Implementations are safe for use by multiple threads.
Since:
5.5.0

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    encode(@NotBlank String rawPassword)
    Encodes a raw password for storage.
    boolean
    matches(@NotBlank String rawPassword, @NotBlank String encodedPassword)
    Verifies a raw password against an encoded password.

  • Method Details

    • encode

      String encode(@NotBlank @NotBlank String rawPassword)
      Encodes a raw password for storage.
      Parameters:
      rawPassword - the raw password, which must not be blank
      Returns:
      the encoded password, which includes the salt and any parameters required to verify it
      Throws:
      jakarta.validation.ConstraintViolationException - if the raw password is blank

    • matches

      boolean matches(@NotBlank @NotBlank String rawPassword, @NotBlank @NotBlank String encodedPassword)
      Verifies a raw password against an encoded password.

      Both parameters are constrained with NotBlank. Callers that may hold a blank value, for example for a user without a stored password, must check for it before calling this method.

      Parameters:
      rawPassword - the raw password to verify, which must not be blank
      encodedPassword - the encoded password, as returned by encode(String), which must not be blank
      Returns:
      true if the raw password matches the encoded password
      Throws:
      jakarta.validation.ConstraintViolationException - if the raw password or the encoded password is blank