Add Argon2 and BCrypt and Scrypt password encoders using Password4j library

Closes gh-17706

Author: mehrdadbozorgmehr

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

@@ -0,0 +1,74 @@
+/*
+ * Copyright 2004-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.crypto.password4j;
+
+import com.password4j.AlgorithmFinder;
+import com.password4j.Argon2Function;
+
+/**
+ * Implementation of {@link org.springframework.security.crypto.password.PasswordEncoder}
+ * that uses the Password4j library with Argon2 hashing algorithm.
+ *
+ * <p>
+ * Argon2 is the winner of the Password Hashing Competition (2015) and is recommended for
+ * new applications. It provides excellent resistance against GPU-based attacks and
+ * includes built-in salt generation. This implementation leverages Password4j's Argon2
+ * support which properly includes the salt in the output hash.
+ * </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 Argon2 settings (recommended)
+ * PasswordEncoder encoder = new Argon2Password4jPasswordEncoder();
+ *
+ * // Using custom Argon2 configuration
+ * PasswordEncoder customEncoder = new Argon2Password4jPasswordEncoder(
+ *     Argon2Function.getInstance(65536, 3, 4, 32, Argon2.ID));
+ * }</pre>
+ *
+ * @author Mehrdad Bozorgmehr
+ * @since 7.0
+ * @see Argon2Function
+ * @see AlgorithmFinder#getArgon2Instance()
+ */
+public class Argon2Password4jPasswordEncoder extends Password4jPasswordEncoder {
+
+	/**
+	 * Constructs an Argon2 password encoder using the default Argon2 configuration from
+	 * Password4j's AlgorithmFinder.
+	 */
+	public Argon2Password4jPasswordEncoder() {
+		super(AlgorithmFinder.getArgon2Instance());
+	}
+
+	/**
+	 * Constructs an Argon2 password encoder with a custom Argon2 function.
+	 * @param argon2Function the Argon2 function to use for encoding passwords, must not
+	 * be null
+	 * @throws IllegalArgumentException if argon2Function is null
+	 */
+	public Argon2Password4jPasswordEncoder(Argon2Function argon2Function) {
+		super(argon2Function);
+	}
+
+}

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

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2004-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.crypto.password4j;
+
+import com.password4j.AlgorithmFinder;
+import com.password4j.BcryptFunction;
+
+/**
+ * Implementation of {@link org.springframework.security.crypto.password.PasswordEncoder}
+ * that uses the Password4j library with BCrypt hashing algorithm.
+ *
+ * <p>
+ * BCrypt is a well-established password hashing algorithm that includes built-in salt
+ * generation and is resistant to rainbow table attacks. This implementation leverages
+ * Password4j's BCrypt support which properly includes the salt in the output hash.
+ * </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 BCrypt settings (recommended)
+ * PasswordEncoder encoder = new BcryptPassword4jPasswordEncoder();
+ *
+ * // Using custom round count
+ * PasswordEncoder customEncoder = new BcryptPassword4jPasswordEncoder(BcryptFunction.getInstance(12));
+ * }</pre>
+ *
+ * @author Mehrdad Bozorgmehr
+ * @since 7.0
+ * @see BcryptFunction
+ * @see AlgorithmFinder#getBcryptInstance()
+ */
+public class BcryptPassword4jPasswordEncoder extends Password4jPasswordEncoder {
+
+	/**
+	 * Constructs a BCrypt password encoder using the default BCrypt configuration from
+	 * Password4j's AlgorithmFinder.
+	 */
+	public BcryptPassword4jPasswordEncoder() {
+		super(AlgorithmFinder.getBcryptInstance());
+	}
+
+	/**
+	 * Constructs a BCrypt password encoder with a custom BCrypt function.
+	 * @param bcryptFunction the BCrypt function to use for encoding passwords, must not
+	 * be null
+	 * @throws IllegalArgumentException if bcryptFunction is null
+	 */
+	public BcryptPassword4jPasswordEncoder(BcryptFunction bcryptFunction) {
+		super(bcryptFunction);
+	}
+
+}

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

@@ -16,116 +16,56 @@
 
 package org.springframework.security.crypto.password4j;
 
-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.
+ * Abstract base class for Password4j-based password encoders. This class provides the
+ * common functionality for password encoding and verification using the Password4j
+ * library.
  *
  * <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.
+ * This class is package-private and should not be used directly. Instead, use the
+ * specific public subclasses that support verified hashing algorithms such as BCrypt,
+ * Argon2, and SCrypt implementations.
  * </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 7.0
- * @see AlgorithmFinder
  */
-public class Password4jPasswordEncoder extends AbstractValidatingPasswordEncoder {
-
-	private final Log logger = LogFactory.getLog(getClass());
+abstract class Password4jPasswordEncoder extends AbstractValidatingPasswordEncoder {
 
 	private final HashingFunction hashingFunction;
 
 	/**
-	 * Constructs a Password4j password encoder with the specified 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>
-	 *
-	 * <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>
+	 * Constructs a Password4j password encoder with the specified hashing function. This
+	 * constructor is package-private and intended for use by subclasses only.
 	 * @param hashingFunction the hashing function to use for encoding passwords, must not
 	 * be null
 	 * @throws IllegalArgumentException if hashingFunction is null
 	 */
-	public Password4jPasswordEncoder(HashingFunction hashingFunction) {
+	Password4jPasswordEncoder(HashingFunction hashingFunction) {
 		Assert.notNull(hashingFunction, "hashingFunction cannot be null");
 		this.hashingFunction = hashingFunction;
 	}
 
 	@Override
 	protected String encodeNonNullPassword(String rawPassword) {
-		try {
-			Hash hash = Password.hash(rawPassword).with(this.hashingFunction);
-			return hash.getResult();
-		}
-		catch (Exception ex) {
-			throw new IllegalStateException("Failed to encode password using Password4j", ex);
-		}
+		Hash hash = Password.hash(rawPassword).with(this.hashingFunction);
+		return hash.getResult();
 	}
 
 	@Override
 	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) {
-			this.logger.warn("Password verification failed for encoded password: " + encodedPassword, ex);
-			return false;
-		}
+		return Password.check(rawPassword, encodedPassword).with(this.hashingFunction);
 	}
 
 	@Override

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

@@ -0,0 +1,74 @@
+/*
+ * Copyright 2004-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.crypto.password4j;
+
+import com.password4j.AlgorithmFinder;
+import com.password4j.ScryptFunction;
+
+/**
+ * Implementation of {@link org.springframework.security.crypto.password.PasswordEncoder}
+ * that uses the Password4j library with SCrypt hashing algorithm.
+ *
+ * <p>
+ * SCrypt is a memory-hard password hashing algorithm designed to be resistant to hardware
+ * brute-force attacks. It includes built-in salt generation and is particularly effective
+ * against ASIC and GPU-based attacks. This implementation leverages Password4j's SCrypt
+ * support which properly includes the salt in the output hash.
+ * </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 SCrypt settings (recommended)
+ * PasswordEncoder encoder = new ScryptPassword4jPasswordEncoder();
+ *
+ * // Using custom SCrypt configuration
+ * PasswordEncoder customEncoder = new ScryptPassword4jPasswordEncoder(
+ *     ScryptFunction.getInstance(32768, 8, 1, 32));
+ * }</pre>
+ *
+ * @author Mehrdad Bozorgmehr
+ * @since 7.0
+ * @see ScryptFunction
+ * @see AlgorithmFinder#getScryptInstance()
+ */
+public class ScryptPassword4jPasswordEncoder extends Password4jPasswordEncoder {
+
+	/**
+	 * Constructs an SCrypt password encoder using the default SCrypt configuration from
+	 * Password4j's AlgorithmFinder.
+	 */
+	public ScryptPassword4jPasswordEncoder() {
+		super(AlgorithmFinder.getScryptInstance());
+	}
+
+	/**
+	 * Constructs an SCrypt password encoder with a custom SCrypt function.
+	 * @param scryptFunction the SCrypt function to use for encoding passwords, must not
+	 * be null
+	 * @throws IllegalArgumentException if scryptFunction is null
+	 */
+	public ScryptPassword4jPasswordEncoder(ScryptFunction scryptFunction) {
+		super(scryptFunction);
+	}
+
+}