Skip to content

Definition Of PasswordEncoder#

PasswordEncoder Interface#

  • If you look into the PasswordEncoder in Spring Security, you will see it is an interface that contains these abstract methods as below.
PasswordEncoder.java
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
/*
 * Copyright 2011-2016 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.password;

/**
 * Service interface for encoding passwords.
 *
 * The preferred implementation is {@code BCryptPasswordEncoder}.
 *
 * @author Keith Donald
 */
public interface PasswordEncoder {

    /**
     * Encode the raw password. Generally, a good encoding algorithm applies a SHA-1 or
     * greater hash combined with an 8-byte or greater randomly generated salt.
     */
    String encode(CharSequence rawPassword);

    /**
     * Verify the encoded password obtained from storage matches the submitted raw
     * password after it too is encoded. Returns true if the passwords match, false if
     * they do not. The stored password itself is never decoded.
     * @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,
     * else false. The default implementation always returns false.
     * @param encodedPassword the encoded password to check
     * @return true if the encoded password should be encoded again for better security,
     * else false.
     */
    default boolean upgradeEncoding(String encodedPassword) {
        return false;
    }

}
  • So in the first method encode which accepts a password from the user, the name encode doesn't mean this apply only for encoding, but not for encryption or hash. The name encode means converting from one from to another form and thereby using encoding algorithms or encryption or hash. So which this method, classes that implement it should accept a raw password which is coming from the framework and they have to encode it as a part of requirement.
  • The method encode will be called by Spring Security framework as soon as it receives a raw password from the use and it will try to generate a hash by taking the original raw password.
  • Then we Spring Security framework got the hash password then it will leverages matches method. So the matches method is the place where our spring security first try to call the encode method by passing the rawPassword to get the hash value and at the same time, it also accept another parameter which is encodedPassword , which is already saved inside the database. So It will take both the has values and try to compare and return a boolean (true/false). Then based on this method, the framework will decide whether it should authenticate the user or not.
  • Lastly, we have method upgradeEncoding, the purpose of this method is used to make your hashing algorithm or encoding or encryption algorithm to be more complex for the user to decode it. So if the return value is true, it means spring security will try to do encoding on the top of existing encoding. That means you will be doing that encoding, encryption or hashing two times, which give you more security. Using this method can slow down your process.

Default Implementations Of PasswordEncoder#

See Also#

References#