PBKDF2 hashing¶
Password-Based Key Derivation Function 2 (PBKDF2) hashing algorithm is a modern hashing algorithm recommended by NIST. We can use the PBKDF2 hashing method to securely store user passwords in user stores. This method reduces the risk of brute-force attacks due to insecure passwords.
This guide walks you through the steps of configuring PBKDF2 as the hashing algorithm of a JDBC userstore.
Note
Currently, PBKDF2 supports only JDBC userstores of WSO2 Identity Server.
Configure PBKDF2 hashing¶
This section guides you on how to configure PBKDF2 hashing on primary and secondary JDBC userstores.
PBKDF2 for primary JDBC userstores¶
PBKDF2 is supported by primary JDBC userstores, but PBKDF2 should be enabled before the initial server startup by adding the following to the deployment.toml
file.
[user_store]
type = "database_unique_id"
password_digest="PBKDF2"
PBKDF2 for secondary JDBC userstores¶
To configure PBKDF2 hashing on a JDBC user store:
-
Login to the Identity Server management console (
https://<IS_HOST>:<PORT>/console
) and create a JDBC user store.Existing userstores
- You may also use an existing user store which does not have any users in it. If you already have users in the userstore, once the hashing algorithm is configured these users will not be able to get authenticated.
- Such cases will impact with bad user experience as the users will not get authenticated even when they try to login using the correct credentials. Admins may use the following approaches to reset the user passwords after configuring the PBKDF2 hashing algorithm on an existing userstore:
- Ask users to reset their own passwords.
- Trigger password reset for all accounts of the userstore using admin initiated password reset.
-
Navigate to Manage > Userstores, select the secondary JDBC userstore you have created.
- Navigate to the User tab of the userstore and expand the Show more section.
-
Edit the following properties with the values given:
Property Value Description Password Hashing Algorithm PBKDF2
Name of the hashing algorithm supported by the userstore. UserStore Hashing Configurations {pbkdf2.iteration.count:10000, pbkdf2.dkLength:256, pbkdf2.prf:PBKDF2WithHmacSHA256}
Additional parameters required for password hashing algorithm. This should be given in JSON format. Learn more about these configurations. -
Click Update to save the configurations.
Successful updation of these configurations will convert the password hashing algorithm of the userstore to PBKDF2.
PBKDF2 parameters¶
When configuring the PBKDF2 hashing algorithm the following parameters must be specified in the configurations:
Parameter | Parameter name | Recommended Value | Description |
---|---|---|---|
pbkdf2.iteration.count |
Iteration count | 10000 |
Number of times hashing is performed. |
pbkdf2.dkLength |
Derived Key Length | 256 |
Bit length of the generated hash value. |
pbkdf2.prf |
Pseudo-Random Function | PBKDF2WithHmacSHA256 |
The key component of the PBKDF2 hashing algorithm in which the actual hashing part is done. |
Info
NIST recommends PBKDF2WithHmacSHA256
as the pseudo-random function (prf) value, but the prf can also be changed. Some examples of possible prf values are as follows:
PBKDF2WithHmacSHA512
PBKDF2WithHmacSHA256
PBKDF2WithHmacSHA1