Password Encoding

/**
 * Service interface for encoding passwords
 */
interface PasswordEncoder {
    /**
     * Encode the raw password
     * @param rawPassword the password to encode
     * @return the encoded password
     */
    String encode(CharSequence rawPassword);
    
    /**
     * Verify the encoded password obtained from storage matches the submitted raw password
     * @param rawPassword the raw password to encode and match
     * @param encodedPassword the encoded password from storage to compare with
     * @return true if the raw password, after encoding, matches the encoded password from storage
     */
    boolean matches(CharSequence rawPassword, String encodedPassword);
    
    /**
     * Returns true if the encoded password should be encoded again for better security
     * @param encodedPassword the encoded password to check
     * @return true if the encoded password should be re-encoded, false otherwise
     */
    default boolean upgradeEncoding(String encodedPassword) {
        return false;
    }
}

/**
 * Implementation of PasswordEncoder that uses the BCrypt strong hashing function
 */
class BCryptPasswordEncoder implements PasswordEncoder {
    /**
     * Constructs a BCryptPasswordEncoder with default strength (10)
     */
    BCryptPasswordEncoder();
    
    /**
     * Constructs a BCryptPasswordEncoder with the specified strength
     * @param strength the log rounds to use, between 4 and 31
     */
    BCryptPasswordEncoder(int strength);
    
    /**
     * Constructs a BCryptPasswordEncoder with the specified version
     * @param version the BCrypt version to use
     */
    BCryptPasswordEncoder(BCryptVersion version);
    
    /**
     * Constructs a BCryptPasswordEncoder with version and SecureRandom
     * @param version the BCrypt version to use
     * @param random the SecureRandom instance to use
     */
    BCryptPasswordEncoder(BCryptVersion version, SecureRandom random);
    
    /**
     * Constructs a BCryptPasswordEncoder with strength and SecureRandom
     * @param strength the log rounds to use, between 4 and 31
     * @param random the SecureRandom instance to use
     */
    BCryptPasswordEncoder(int strength, SecureRandom random);
    
    /**
     * Constructs a BCryptPasswordEncoder with version and strength
     * @param version the BCrypt version to use
     * @param strength the log rounds to use, between 4 and 31
     */
    BCryptPasswordEncoder(BCryptVersion version, int strength);
    
    /**
     * Constructs a BCryptPasswordEncoder with full configuration
     * @param version the BCrypt version to use
     * @param strength the log rounds to use, between 4 and 31
     * @param random the SecureRandom instance to use
     */
    BCryptPasswordEncoder(BCryptVersion version, int strength, SecureRandom random);
    
    enum BCryptVersion {
        $2A("$2a"),
        $2Y("$2y"),
        $2B("$2b");
        
        private final String version;
        
        BCryptVersion(String version) {
            this.version = version;
        }
        
        public String getVersion() {
            return this.version;
        }
    }
}

import org.springframework.security.crypto.password.BCryptPasswordEncoder;

// Default BCrypt encoder (strength 10)
BCryptPasswordEncoder encoder = new BCryptPasswordEncoder();
String encoded = encoder.encode("myPassword");
boolean matches = encoder.matches("myPassword", encoded);

// Custom strength
BCryptPasswordEncoder strongEncoder = new BCryptPasswordEncoder(12);
String strongEncoded = strongEncoder.encode("myPassword");

/**
 * Implementation of PasswordEncoder that uses the Argon2 hashing function
 */
class Argon2PasswordEncoder implements PasswordEncoder {
    /**
     * Constructs an Argon2PasswordEncoder with the specified parameters
     * @param saltLength the salt length in bytes
     * @param hashLength the hash length in bytes
     * @param parallelism the parallelism factor
     * @param memory the memory usage in KB
     * @param iterations the number of iterations
     */
    Argon2PasswordEncoder(int saltLength, int hashLength, int parallelism, int memory, int iterations);
    
    /**
     * Get defaults for Spring Security v5.2 (deprecated)
     * @return Argon2PasswordEncoder with v5.2 defaults
     */
    static Argon2PasswordEncoder defaultsForSpringSecurity_v5_2();
    
    /**
     * Get current defaults for Spring Security v5.8
     * @return Argon2PasswordEncoder with v5.8 defaults
     */
    static Argon2PasswordEncoder defaultsForSpringSecurity_v5_8();
}

import org.springframework.security.crypto.password.Argon2PasswordEncoder;

// Use current defaults
Argon2PasswordEncoder encoder = Argon2PasswordEncoder.defaultsForSpringSecurity_v5_8();
String encoded = encoder.encode("myPassword");
boolean matches = encoder.matches("myPassword", encoded);

// Custom parameters
Argon2PasswordEncoder customEncoder = new Argon2PasswordEncoder(16, 32, 1, 4096, 3);

/**
 * Implementation of PasswordEncoder that uses the SCrypt hashing function
 */
class SCryptPasswordEncoder implements PasswordEncoder {
    /**
     * Constructs an SCryptPasswordEncoder with the specified parameters
     * @param cpuCost CPU cost parameter
     * @param memoryCost memory cost parameter
     * @param parallelization parallelization parameter
     * @param keyLength derived key length
     * @param saltLength salt length
     */
    SCryptPasswordEncoder(int cpuCost, int memoryCost, int parallelization, int keyLength, int saltLength);
    
    /**
     * Get defaults for Spring Security v4.1 (legacy)
     * @return SCryptPasswordEncoder with v4.1 defaults
     */
    static SCryptPasswordEncoder defaultsForSpringSecurity_v4_1();
    
    /**
     * Get current defaults for Spring Security v5.8
     * @return SCryptPasswordEncoder with v5.8 defaults
     */
    static SCryptPasswordEncoder defaultsForSpringSecurity_v5_8();
}

/**
 * A PasswordEncoder implementation that uses PBKDF2 with a configurable number of iterations
 */
class Pbkdf2PasswordEncoder implements PasswordEncoder {
    /**
     * Constructs a PBKDF2 password encoder with default settings
     */
    Pbkdf2PasswordEncoder();
    
    /**
     * Constructs a PBKDF2 password encoder with the specified secret
     * @param secret the secret key used for encoding
     */
    Pbkdf2PasswordEncoder(CharSequence secret);
    
    /**
     * Constructs a PBKDF2 password encoder with full configuration
     * @param secret the secret key used for encoding
     * @param saltLength the salt length in bytes
     * @param iterations the number of iterations
     * @param algorithm the SecretKeyFactory algorithm to use
     */
    Pbkdf2PasswordEncoder(CharSequence secret, int saltLength, int iterations, SecretKeyFactoryAlgorithm algorithm);
    
    /**
     * Get defaults for Spring Security v5.5
     * @return Pbkdf2PasswordEncoder with v5.5 defaults
     */
    static Pbkdf2PasswordEncoder defaultsForSpringSecurity_v5_5();
    
    /**
     * Get current defaults for Spring Security v5.8
     * @return Pbkdf2PasswordEncoder with v5.8 defaults
     */
    static Pbkdf2PasswordEncoder defaultsForSpringSecurity_v5_8();
    
    enum SecretKeyFactoryAlgorithm {
        PBKDF2WithHmacSHA1("PBKDF2WithHmacSHA1"),
        PBKDF2WithHmacSHA256("PBKDF2WithHmacSHA256"),
        PBKDF2WithHmacSHA512("PBKDF2WithHmacSHA512");
        
        private final String algorithm;
        
        SecretKeyFactoryAlgorithm(String algorithm) {
            this.algorithm = algorithm;
        }
        
        public String getAlgorithm() {
            return this.algorithm;
        }
    }
}

/**
 * A password encoder that delegates to another PasswordEncoder based upon a prefixed identifier
 */
class DelegatingPasswordEncoder implements PasswordEncoder {
    /**
     * Creates a new instance
     * @param idForEncode the id used to lookup which PasswordEncoder should be used to encode passwords
     * @param idToPasswordEncoder a Map of id to PasswordEncoder used to determine which PasswordEncoder should be used for the id
     */
    DelegatingPasswordEncoder(String idForEncode, Map<String, PasswordEncoder> idToPasswordEncoder);
}

/**
 * MessageDigest-based password encoder
 */
class MessageDigestPasswordEncoder implements PasswordEncoder {
    MessageDigestPasswordEncoder(String algorithm);
}

/**
 * LDAP SHA password encoder
 */
class LdapShaPasswordEncoder implements PasswordEncoder {
    LdapShaPasswordEncoder();
}

/**
 * MD4 password encoder
 */
class Md4PasswordEncoder implements PasswordEncoder {
    Md4PasswordEncoder();
}

/**
 * No-operation password encoder (for testing only)
 */
class NoOpPasswordEncoder implements PasswordEncoder {
    static NoOpPasswordEncoder getInstance();
}

/**
 * Standard password encoder using SHA-1 (deprecated)
 */
class StandardPasswordEncoder implements PasswordEncoder {
    StandardPasswordEncoder();
    StandardPasswordEncoder(CharSequence secret);
}

/**
 * Used for creating PasswordEncoder instances
 */
class PasswordEncoderFactories {
    /**
     * Creates a DelegatingPasswordEncoder with default mappings
     * @return the delegating password encoder
     */
    static PasswordEncoder createDelegatingPasswordEncoder();
}

import org.springframework.security.crypto.factory.PasswordEncoderFactories;
import org.springframework.security.crypto.password.PasswordEncoder;

// Get the default delegating password encoder
PasswordEncoder passwordEncoder = PasswordEncoderFactories.createDelegatingPasswordEncoder();

// This will use BCrypt by default for new passwords
String encoded = passwordEncoder.encode("myPassword");

// Can verify passwords encoded with any supported algorithm
boolean matches = passwordEncoder.matches("myPassword", encoded);