0
# Password Encoding
1

2
Comprehensive password encoding utilities with support for multiple secure hashing algorithms including BCrypt, Argon2, SCrypt, PBKDF2, and other implementations.
3

4
## Capabilities
5

6
### PasswordEncoder Interface
7

8
Core interface for password encoding operations.
9

10
```java { .api }
11
/**
12
 * Service interface for encoding passwords
13
 */
14
interface PasswordEncoder {
15
    /**
16
     * Encode the raw password
17
     * @param rawPassword the password to encode
18
     * @return the encoded password
19
     */
20
    String encode(CharSequence rawPassword);
21
    
22
    /**
23
     * Verify the encoded password obtained from storage matches the submitted raw password
24
     * @param rawPassword the raw password to encode and match
25
     * @param encodedPassword the encoded password from storage to compare with
26
     * @return true if the raw password, after encoding, matches the encoded password from storage
27
     */
28
    boolean matches(CharSequence rawPassword, String encodedPassword);
29
    
30
    /**
31
     * Returns true if the encoded password should be encoded again for better security
32
     * @param encodedPassword the encoded password to check
33
     * @return true if the encoded password should be re-encoded, false otherwise
34
     */
35
    default boolean upgradeEncoding(String encodedPassword) {
36
        return false;
37
    }
38
}
39
```
40

41
### BCrypt Password Encoder
42

43
BCrypt strong hashing function implementation with configurable strength and version.
44

45
```java { .api }
46
/**
47
 * Implementation of PasswordEncoder that uses the BCrypt strong hashing function
48
 */
49
class BCryptPasswordEncoder implements PasswordEncoder {
50
    /**
51
     * Constructs a BCryptPasswordEncoder with default strength (10)
52
     */
53
    BCryptPasswordEncoder();
54
    
55
    /**
56
     * Constructs a BCryptPasswordEncoder with the specified strength
57
     * @param strength the log rounds to use, between 4 and 31
58
     */
59
    BCryptPasswordEncoder(int strength);
60
    
61
    /**
62
     * Constructs a BCryptPasswordEncoder with the specified version
63
     * @param version the BCrypt version to use
64
     */
65
    BCryptPasswordEncoder(BCryptVersion version);
66
    
67
    /**
68
     * Constructs a BCryptPasswordEncoder with version and SecureRandom
69
     * @param version the BCrypt version to use
70
     * @param random the SecureRandom instance to use
71
     */
72
    BCryptPasswordEncoder(BCryptVersion version, SecureRandom random);
73
    
74
    /**
75
     * Constructs a BCryptPasswordEncoder with strength and SecureRandom
76
     * @param strength the log rounds to use, between 4 and 31
77
     * @param random the SecureRandom instance to use
78
     */
79
    BCryptPasswordEncoder(int strength, SecureRandom random);
80
    
81
    /**
82
     * Constructs a BCryptPasswordEncoder with version and strength
83
     * @param version the BCrypt version to use
84
     * @param strength the log rounds to use, between 4 and 31
85
     */
86
    BCryptPasswordEncoder(BCryptVersion version, int strength);
87
    
88
    /**
89
     * Constructs a BCryptPasswordEncoder with full configuration
90
     * @param version the BCrypt version to use
91
     * @param strength the log rounds to use, between 4 and 31
92
     * @param random the SecureRandom instance to use
93
     */
94
    BCryptPasswordEncoder(BCryptVersion version, int strength, SecureRandom random);
95
    
96
    enum BCryptVersion {
97
        $2A("$2a"),
98
        $2Y("$2y"),
99
        $2B("$2b");
100
        
101
        private final String version;
102
        
103
        BCryptVersion(String version) {
104
            this.version = version;
105
        }
106
        
107
        public String getVersion() {
108
            return this.version;
109
        }
110
    }
111
}
112
```
113

114
**Usage Example:**
115

116
```java
117
import org.springframework.security.crypto.password.BCryptPasswordEncoder;
118

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

124
// Custom strength
125
BCryptPasswordEncoder strongEncoder = new BCryptPasswordEncoder(12);
126
String strongEncoded = strongEncoder.encode("myPassword");
127
```
128

129
### Argon2 Password Encoder
130

131
Argon2 hashing function implementation with configurable parameters.
132

133
```java { .api }
134
/**
135
 * Implementation of PasswordEncoder that uses the Argon2 hashing function
136
 */
137
class Argon2PasswordEncoder implements PasswordEncoder {
138
    /**
139
     * Constructs an Argon2PasswordEncoder with the specified parameters
140
     * @param saltLength the salt length in bytes
141
     * @param hashLength the hash length in bytes
142
     * @param parallelism the parallelism factor
143
     * @param memory the memory usage in KB
144
     * @param iterations the number of iterations
145
     */
146
    Argon2PasswordEncoder(int saltLength, int hashLength, int parallelism, int memory, int iterations);
147
    
148
    /**
149
     * Get defaults for Spring Security v5.2 (deprecated)
150
     * @return Argon2PasswordEncoder with v5.2 defaults
151
     */
152
    static Argon2PasswordEncoder defaultsForSpringSecurity_v5_2();
153
    
154
    /**
155
     * Get current defaults for Spring Security v5.8
156
     * @return Argon2PasswordEncoder with v5.8 defaults
157
     */
158
    static Argon2PasswordEncoder defaultsForSpringSecurity_v5_8();
159
}
160
```
161

162
**Usage Example:**
163

164
```java
165
import org.springframework.security.crypto.password.Argon2PasswordEncoder;
166

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

172
// Custom parameters
173
Argon2PasswordEncoder customEncoder = new Argon2PasswordEncoder(16, 32, 1, 4096, 3);
174
```
175

176
### SCrypt Password Encoder
177

178
SCrypt hashing function implementation with configurable cost parameters.
179

180
```java { .api }
181
/**
182
 * Implementation of PasswordEncoder that uses the SCrypt hashing function
183
 */
184
class SCryptPasswordEncoder implements PasswordEncoder {
185
    /**
186
     * Constructs an SCryptPasswordEncoder with the specified parameters
187
     * @param cpuCost CPU cost parameter
188
     * @param memoryCost memory cost parameter
189
     * @param parallelization parallelization parameter
190
     * @param keyLength derived key length
191
     * @param saltLength salt length
192
     */
193
    SCryptPasswordEncoder(int cpuCost, int memoryCost, int parallelization, int keyLength, int saltLength);
194
    
195
    /**
196
     * Get defaults for Spring Security v4.1 (legacy)
197
     * @return SCryptPasswordEncoder with v4.1 defaults
198
     */
199
    static SCryptPasswordEncoder defaultsForSpringSecurity_v4_1();
200
    
201
    /**
202
     * Get current defaults for Spring Security v5.8
203
     * @return SCryptPasswordEncoder with v5.8 defaults
204
     */
205
    static SCryptPasswordEncoder defaultsForSpringSecurity_v5_8();
206
}
207
```
208

209
### PBKDF2 Password Encoder
210

211
PBKDF2 password encoder implementation with configurable algorithm and iterations.
212

213
```java { .api }
214
/**
215
 * A PasswordEncoder implementation that uses PBKDF2 with a configurable number of iterations
216
 */
217
class Pbkdf2PasswordEncoder implements PasswordEncoder {
218
    /**
219
     * Constructs a PBKDF2 password encoder with default settings
220
     */
221
    Pbkdf2PasswordEncoder();
222
    
223
    /**
224
     * Constructs a PBKDF2 password encoder with the specified secret
225
     * @param secret the secret key used for encoding
226
     */
227
    Pbkdf2PasswordEncoder(CharSequence secret);
228
    
229
    /**
230
     * Constructs a PBKDF2 password encoder with full configuration
231
     * @param secret the secret key used for encoding
232
     * @param saltLength the salt length in bytes
233
     * @param iterations the number of iterations
234
     * @param algorithm the SecretKeyFactory algorithm to use
235
     */
236
    Pbkdf2PasswordEncoder(CharSequence secret, int saltLength, int iterations, SecretKeyFactoryAlgorithm algorithm);
237
    
238
    /**
239
     * Get defaults for Spring Security v5.5
240
     * @return Pbkdf2PasswordEncoder with v5.5 defaults
241
     */
242
    static Pbkdf2PasswordEncoder defaultsForSpringSecurity_v5_5();
243
    
244
    /**
245
     * Get current defaults for Spring Security v5.8
246
     * @return Pbkdf2PasswordEncoder with v5.8 defaults
247
     */
248
    static Pbkdf2PasswordEncoder defaultsForSpringSecurity_v5_8();
249
    
250
    enum SecretKeyFactoryAlgorithm {
251
        PBKDF2WithHmacSHA1("PBKDF2WithHmacSHA1"),
252
        PBKDF2WithHmacSHA256("PBKDF2WithHmacSHA256"),
253
        PBKDF2WithHmacSHA512("PBKDF2WithHmacSHA512");
254
        
255
        private final String algorithm;
256
        
257
        SecretKeyFactoryAlgorithm(String algorithm) {
258
            this.algorithm = algorithm;
259
        }
260
        
261
        public String getAlgorithm() {
262
            return this.algorithm;
263
        }
264
    }
265
}
266
```
267

268
### Delegating Password Encoder
269

270
Delegates to different PasswordEncoders based on algorithm prefixes.
271

272
```java { .api }
273
/**
274
 * A password encoder that delegates to another PasswordEncoder based upon a prefixed identifier
275
 */
276
class DelegatingPasswordEncoder implements PasswordEncoder {
277
    /**
278
     * Creates a new instance
279
     * @param idForEncode the id used to lookup which PasswordEncoder should be used to encode passwords
280
     * @param idToPasswordEncoder a Map of id to PasswordEncoder used to determine which PasswordEncoder should be used for the id
281
     */
282
    DelegatingPasswordEncoder(String idForEncode, Map<String, PasswordEncoder> idToPasswordEncoder);
283
}
284
```
285

286
### Other Password Encoders
287

288
Additional password encoder implementations for specific use cases.
289

290
```java { .api }
291
/**
292
 * MessageDigest-based password encoder
293
 */
294
class MessageDigestPasswordEncoder implements PasswordEncoder {
295
    MessageDigestPasswordEncoder(String algorithm);
296
}
297

298
/**
299
 * LDAP SHA password encoder
300
 */
301
class LdapShaPasswordEncoder implements PasswordEncoder {
302
    LdapShaPasswordEncoder();
303
}
304

305
/**
306
 * MD4 password encoder
307
 */
308
class Md4PasswordEncoder implements PasswordEncoder {
309
    Md4PasswordEncoder();
310
}
311

312
/**
313
 * No-operation password encoder (for testing only)
314
 */
315
class NoOpPasswordEncoder implements PasswordEncoder {
316
    static NoOpPasswordEncoder getInstance();
317
}
318

319
/**
320
 * Standard password encoder using SHA-1 (deprecated)
321
 */
322
class StandardPasswordEncoder implements PasswordEncoder {
323
    StandardPasswordEncoder();
324
    StandardPasswordEncoder(CharSequence secret);
325
}
326
```
327

328
### Password Encoder Factories
329

330
Factory for creating commonly used password encoder configurations.
331

332
```java { .api }
333
/**
334
 * Used for creating PasswordEncoder instances
335
 */
336
class PasswordEncoderFactories {
337
    /**
338
     * Creates a DelegatingPasswordEncoder with default mappings
339
     * @return the delegating password encoder
340
     */
341
    static PasswordEncoder createDelegatingPasswordEncoder();
342
}
343
```
344

345
**Usage Example:**
346

347
```java
348
import org.springframework.security.crypto.factory.PasswordEncoderFactories;
349
import org.springframework.security.crypto.password.PasswordEncoder;
350

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

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

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