Refactor Password4jPasswordEncoder to use AlgorithmFinder for algorithm selection and enhance documentation

Closes gh-17706

Signed-off-by: M.Bozorgmehr <[email protected]>

Author: mehrdadbozorgmehr

crypto/src/main/java/org/springframework/security/crypto/factory/PasswordEncoderFactories.java

@@ -24,7 +24,6 @@
 import org.springframework.security.crypto.password.DelegatingPasswordEncoder;
 import org.springframework.security.crypto.password.PasswordEncoder;
 import org.springframework.security.crypto.password.Pbkdf2PasswordEncoder;
-import org.springframework.security.crypto.password4j.Password4jPasswordEncoder;
 import org.springframework.security.crypto.scrypt.SCryptPasswordEncoder;
 
 /**
@@ -66,10 +65,6 @@ private PasswordEncoderFactories() {
 	 * <li>argon2 - {@link Argon2PasswordEncoder#defaultsForSpringSecurity_v5_2()}</li>
 	 * <li>argon2@SpringSecurity_v5_8 -
 	 * {@link Argon2PasswordEncoder#defaultsForSpringSecurity_v5_8()}</li>
-	 * <li>password4j-bcrypt - {@link Password4jPasswordEncoder} with BCrypt</li>
-	 * <li>password4j-scrypt - {@link Password4jPasswordEncoder} with SCrypt</li>
-	 * <li>password4j-argon2 - {@link Password4jPasswordEncoder} with Argon2</li>
-	 * <li>password4j-pbkdf2 - {@link Password4jPasswordEncoder} with PBKDF2</li>
 	 * </ul>
 	 * @return the {@link PasswordEncoder} to use
 	 */
@@ -92,14 +87,6 @@ public static PasswordEncoder createDelegatingPasswordEncoder() {
 		encoders.put("sha256", new org.springframework.security.crypto.password.StandardPasswordEncoder());
 		encoders.put("argon2", Argon2PasswordEncoder.defaultsForSpringSecurity_v5_2());
 		encoders.put("argon2@SpringSecurity_v5_8", Argon2PasswordEncoder.defaultsForSpringSecurity_v5_8());
-
-		// Password4j implementations
-		encoders.put("password4j-bcrypt", Password4jPasswordEncoder.bcrypt(10));
-		encoders.put("password4j-scrypt", Password4jPasswordEncoder.scrypt(16384, 8, 1, 32));
-		encoders.put("password4j-argon2", Password4jPasswordEncoder.argon2(65536, 3, 4, 32,
-			com.password4j.types.Argon2.ID));
-		encoders.put("password4j-pbkdf2", Password4jPasswordEncoder.pbkdf2(310000, 32));
-
 		return new DelegatingPasswordEncoder(encodingId, encoders);
 	}
 

crypto/src/main/java/org/springframework/security/crypto/password4j/Password4jPasswordEncoder.java

@@ -16,179 +16,102 @@
 
 package org.springframework.security.crypto.password4j;
 
-import com.password4j.*;
-import com.password4j.types.Argon2;
+import com.password4j.AlgorithmFinder;
+import com.password4j.Hash;
+import com.password4j.HashingFunction;
+import com.password4j.Password;
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
+
 import org.springframework.security.crypto.password.AbstractValidatingPasswordEncoder;
 import org.springframework.util.Assert;
 
 /**
- * Implementation of {@link org.springframework.security.crypto.password.PasswordEncoder} that uses the Password4j library.
- * This encoder supports multiple password hashing algorithms including BCrypt, SCrypt, Argon2, and PBKDF2.
+ * Implementation of {@link org.springframework.security.crypto.password.PasswordEncoder}
+ * that uses the Password4j library. This encoder supports multiple password hashing
+ * algorithms including BCrypt, SCrypt, Argon2, and PBKDF2.
+ *
+ * <p>
+ * The encoder uses the provided {@link HashingFunction} for both encoding and
+ * verification. Password4j can automatically detect the algorithm used in existing hashes
+ * during verification.
+ * </p>
  *
- * <p>The encoder determines the algorithm used based on the algorithm type specified during construction.
- * For verification, it can automatically detect the algorithm used in existing hashes.</p>
+ * <p>
+ * This implementation is thread-safe and can be shared across multiple threads.
+ * </p>
  *
- * <p>This implementation is thread-safe and can be shared across multiple threads.</p>
+ * <p>
+ * <strong>Usage Examples:</strong>
+ * </p>
+ * <pre>{@code
+ * // Using default algorithms from AlgorithmFinder (recommended approach)
+ * PasswordEncoder bcryptEncoder = new Password4jPasswordEncoder(AlgorithmFinder.getBcryptInstance());
+ * PasswordEncoder argon2Encoder = new Password4jPasswordEncoder(AlgorithmFinder.getArgon2Instance());
+ * PasswordEncoder scryptEncoder = new Password4jPasswordEncoder(AlgorithmFinder.getScryptInstance());
+ * PasswordEncoder pbkdf2Encoder = new Password4jPasswordEncoder(AlgorithmFinder.getPBKDF2Instance());
+ *
+ * // Using customized algorithm parameters
+ * PasswordEncoder customBcrypt = new Password4jPasswordEncoder(BcryptFunction.getInstance(12));
+ * PasswordEncoder customArgon2 = new Password4jPasswordEncoder(
+ *     Argon2Function.getInstance(65536, 3, 4, 32, Argon2.ID));
+ * PasswordEncoder customScrypt = new Password4jPasswordEncoder(
+ *     ScryptFunction.getInstance(32768, 8, 1, 32));
+ * PasswordEncoder customPbkdf2 = new Password4jPasswordEncoder(
+ *     CompressedPBKDF2Function.getInstance("SHA256", 310000, 32));
+ * }</pre>
  *
  * @author Mehrdad Bozorgmehr
- * @since 6.5
+ * @since 7.0
+ * @see AlgorithmFinder
  */
 public class Password4jPasswordEncoder extends AbstractValidatingPasswordEncoder {
 
 	private final Log logger = LogFactory.getLog(getClass());
 
 	private final HashingFunction hashingFunction;
 
-	private final Password4jAlgorithm algorithm;
-
-
-	/**
-	 * Enumeration of supported Password4j algorithms.
-	 */
-	public enum Password4jAlgorithm {
-		/**
-		 * BCrypt algorithm.
-		 */
-		BCRYPT,
-		/**
-		 * SCrypt algorithm.
-		 */
-		SCRYPT,
-		/**
-		 * Argon2 algorithm.
-		 */
-		ARGON2,
-		/**
-		 * PBKDF2 algorithm.
-		 */
-		PBKDF2,
-		/**
-		 * Compressed PBKDF2 algorithm.
-		 */
-		COMPRESSED_PBKDF2
-	}
-
-	/**
-	 * Constructs a Password4j password encoder with the default BCrypt algorithm.
-	 */
-	public Password4jPasswordEncoder() {
-		this(Password4jAlgorithm.BCRYPT);
-	}
-
 	/**
-	 * Constructs a Password4j password encoder with the specified algorithm using default parameters.
+	 * Constructs a Password4j password encoder with the specified hashing function.
 	 *
-	 * @param algorithm the password hashing algorithm to use
-	 */
-	public Password4jPasswordEncoder(Password4jAlgorithm algorithm) {
-		Assert.notNull(algorithm, "algorithm cannot be null");
-		this.algorithm = algorithm;
-		this.hashingFunction = createDefaultHashingFunction(algorithm);
-	}
-
-	/**
-	 * Constructs a Password4j password encoder with a custom hashing function.
+	 * <p>
+	 * It is recommended to use password4j's {@link AlgorithmFinder} to obtain default
+	 * instances with secure configurations:
+	 * </p>
+	 * <ul>
+	 * <li>{@code AlgorithmFinder.getBcryptInstance()} - BCrypt with default settings</li>
+	 * <li>{@code AlgorithmFinder.getArgon2Instance()} - Argon2 with default settings</li>
+	 * <li>{@code AlgorithmFinder.getScryptInstance()} - SCrypt with default settings</li>
+	 * <li>{@code AlgorithmFinder.getPBKDF2Instance()} - PBKDF2 with default settings</li>
+	 * </ul>
 	 *
-	 * @param hashingFunction the custom hashing function to use
-	 * @param algorithm       the password hashing algorithm type
+	 * <p>
+	 * For custom configurations, you can create specific function instances:
+	 * </p>
+	 * <ul>
+	 * <li>{@code BcryptFunction.getInstance(12)} - BCrypt with 12 rounds</li>
+	 * <li>{@code Argon2Function.getInstance(65536, 3, 4, 32, Argon2.ID)} - Custom
+	 * Argon2</li>
+	 * <li>{@code ScryptFunction.getInstance(16384, 8, 1, 32)} - Custom SCrypt</li>
+	 * <li>{@code CompressedPBKDF2Function.getInstance("SHA256", 310000, 32)} - Custom
+	 * PBKDF2</li>
+	 * </ul>
+	 * @param hashingFunction the hashing function to use for encoding passwords, must not
+	 * be null
+	 * @throws IllegalArgumentException if hashingFunction is null
 	 */
-	public Password4jPasswordEncoder(HashingFunction hashingFunction, Password4jAlgorithm algorithm) {
+	public Password4jPasswordEncoder(HashingFunction hashingFunction) {
 		Assert.notNull(hashingFunction, "hashingFunction cannot be null");
-		Assert.notNull(algorithm, "algorithm cannot be null");
 		this.hashingFunction = hashingFunction;
-		this.algorithm = algorithm;
-	}
-
-	/**
-	 * Creates a Password4j password encoder with BCrypt algorithm and specified rounds.
-	 *
-	 * @param rounds the number of rounds (cost factor) for BCrypt
-	 * @return a new Password4j password encoder
-	 */
-	public static Password4jPasswordEncoder bcrypt(int rounds) {
-		return new Password4jPasswordEncoder(BcryptFunction.getInstance(rounds), Password4jAlgorithm.BCRYPT);
-	}
-
-	/**
-	 * Creates a Password4j password encoder with SCrypt algorithm and specified parameters.
-	 *
-	 * @param workFactor       the work factor (N parameter)
-	 * @param resources        the resources (r parameter)
-	 * @param parallelization  the parallelization (p parameter)
-	 * @param derivedKeyLength the derived key length
-	 * @return a new Password4j password encoder
-	 */
-	public static Password4jPasswordEncoder scrypt(int workFactor, int resources, int parallelization, int derivedKeyLength) {
-		return new Password4jPasswordEncoder(
-				ScryptFunction.getInstance(workFactor, resources, parallelization, derivedKeyLength),
-				Password4jAlgorithm.SCRYPT
-		);
-	}
-
-	/**
-	 * Creates a Password4j password encoder with Argon2 algorithm and specified parameters.
-	 *
-	 * @param memory       the memory cost
-	 * @param iterations   the number of iterations
-	 * @param parallelism  the parallelism
-	 * @param outputLength the output length
-	 * @param type         the Argon2 type
-	 * @return a new Password4j password encoder
-	 */
-	public static Password4jPasswordEncoder argon2(int memory, int iterations, int parallelism, int outputLength, Argon2 type) {
-		return new Password4jPasswordEncoder(
-				Argon2Function.getInstance(memory, iterations, parallelism, outputLength, type),
-				Password4jAlgorithm.ARGON2
-		);
-	}
-
-	/**
-	 * Creates a Password4j password encoder with PBKDF2 algorithm and specified parameters.
-	 *
-	 * @param iterations       the number of iterations
-	 * @param derivedKeyLength the derived key length
-	 * @return a new Password4j password encoder
-	 */
-	public static Password4jPasswordEncoder pbkdf2(int iterations, int derivedKeyLength) {
-		return new Password4jPasswordEncoder(
-				CompressedPBKDF2Function.getInstance("SHA256", iterations, derivedKeyLength),
-				Password4jAlgorithm.PBKDF2
-		);
-	}
-
-	/**
-	 * Creates a Password4j password encoder with compressed PBKDF2 algorithm.
-	 *
-	 * @param iterations       the number of iterations
-	 * @param derivedKeyLength the derived key length
-	 * @return a new Password4j password encoder
-	 */
-	public static Password4jPasswordEncoder compressedPbkdf2(int iterations, int derivedKeyLength) {
-		return new Password4jPasswordEncoder(
-				CompressedPBKDF2Function.getInstance("SHA256", iterations, derivedKeyLength),
-				Password4jAlgorithm.COMPRESSED_PBKDF2
-		);
-	}
-
-	/**
-	 * Creates a Password4j password encoder with default settings for Spring Security v5.8+.
-	 * This uses BCrypt with 10 rounds.
-	 *
-	 * @return a new Password4j password encoder with recommended defaults
-	 * @since 6.5
-	 */
-	public static Password4jPasswordEncoder defaultsForSpringSecurity() {
-		return bcrypt(10);
 	}
 
 	@Override
 	protected String encodeNonNullPassword(String rawPassword) {
 		try {
 			Hash hash = Password.hash(rawPassword).with(this.hashingFunction);
 			return hash.getResult();
-		} catch (Exception ex) {
+		}
+		catch (Exception ex) {
 			throw new IllegalStateException("Failed to encode password using Password4j", ex);
 		}
 	}
@@ -198,7 +121,8 @@ protected boolean matchesNonNull(String rawPassword, String encodedPassword) {
 		try {
 			// Use the specific hashing function for verification
 			return Password.check(rawPassword, encodedPassword).with(this.hashingFunction);
-		} catch (Exception ex) {
+		}
+		catch (Exception ex) {
 			this.logger.warn("Password verification failed for encoded password: " + encodedPassword, ex);
 			return false;
 		}
@@ -211,39 +135,4 @@ protected boolean upgradeEncodingNonNull(String encodedPassword) {
 		return false;
 	}
 
-	/**
-	 * Creates a default hashing function for the specified algorithm.
-	 *
-	 * @param algorithm the password hashing algorithm
-	 * @return the default hashing function
-	 */
-	private static HashingFunction createDefaultHashingFunction(Password4jAlgorithm algorithm) {
-        return switch (algorithm) {
-            case BCRYPT -> BcryptFunction.getInstance(10); // Default 10 rounds
-            case SCRYPT -> ScryptFunction.getInstance(16384, 8, 1, 32); // Default parameters
-            case ARGON2 -> Argon2Function.getInstance(65536, 3, 4, 32, Argon2.ID); // Default parameters
-            case PBKDF2 ->
-                    CompressedPBKDF2Function.getInstance("SHA256", 310000, 32); // Use compressed format for self-contained encoding
-            case COMPRESSED_PBKDF2 -> CompressedPBKDF2Function.getInstance("SHA256", 310000, 32);
-        };
-	}
-
-	/**
-	 * Gets the algorithm used by this encoder.
-	 *
-	 * @return the password hashing algorithm
-	 */
-	public Password4jAlgorithm getAlgorithm() {
-		return this.algorithm;
-	}
-
-	/**
-	 * Gets the hashing function used by this encoder.
-	 *
-	 * @return the hashing function
-	 */
-	public HashingFunction getHashingFunction() {
-		return this.hashingFunction;
-	}
-
 }

crypto/src/main/java/org/springframework/security/crypto/password4j/package-info.java

@@ -14,7 +14,6 @@
  * limitations under the License.
  */
 
-
 @NullMarked
 package org.springframework.security.crypto.password4j;