Skip to content

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:

  1. 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:
  2. Navigate to Manage > Userstores, select the secondary JDBC userstore you have created.

  3. Navigate to the User tab of the userstore and expand the Show more section.
  4. 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.

  5. 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
Top