Add PBKDF2 Hashing support by randilt · Pull Request #596 · ballerina-platform/module-ballerina-crypto

randilt · 2025-03-18T16:08:51Z

Purpose

Resolves: #43926

This PR introduces two new APIs to the Ballerina crypto module for password hashing and verification using PBKDF2.

Newly Added APIs

crypto:hashPbkdf2() - Generates a PBKDF2 hash of a given password with optional parameters for iterations and hash algorithm.
crypto:verifyPbkdf2() - Verifies whether a given password matches a PBKDF2 hashed password.

Examples

1. Hashing a Password using PBKDF2

import ballerina/crypto;

string password = "mySecurePassword123";
string|crypto:Error hash = crypto:hashPbkdf2(password);

Parameters:

password - The password string to be hashed.
iterations (optional) - The number of iterations (default: 10,000).
algorithm (optional) - HMAC algorithm (SHA1, SHA256, SHA512, default: SHA256).
Returns - A PBKDF2 hashed password string or an error if hashing fails.

2. Verifying a PBKDF2 Hashed Password

import ballerina/crypto;

string password = "mySecurePassword123";
string hashedPassword = "$pbkdf2-sha256$i=10000$salt$hash";
boolean|crypto:Error matches = crypto:verifyPbkdf2(password, hashedPassword);

Parameters:

password - The password string to verify.
hashedPassword - The PBKDF2 hashed password to compare against.
Returns - A boolean indicating whether the password matches or an error if verification fails.

Checklist

…n2 class

codecov · 2025-03-18T16:12:09Z

Codecov Report

Attention: Patch coverage is 68.70748% with 46 lines in your changes missing coverage. Please review.

Project coverage is 82.22%. Comparing base (59b8e05) to head (3a5bac0).
Report is 28 commits behind head on master.

Files with missing lines	Patch %	Lines
...o/ballerina/stdlib/crypto/nativeimpl/Password.java	68.80%	37 Missing and 2 partials ⚠️
...java/io/ballerina/stdlib/crypto/PasswordUtils.java	61.11%	6 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master     #596      +/-   ##
============================================
- Coverage     83.47%   82.22%   -1.26%     
- Complexity      226      239      +13     
============================================
  Files            30       29       -1     
  Lines          1283     1367      +84     
  Branches        180      190      +10     
============================================
+ Hits           1071     1124      +53     
- Misses          169      197      +28     
- Partials         43       46       +3

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

…to module

…cification

ballerina/hash.bal

Co-authored-by: DimuthuMadushan <35717653+DimuthuMadushan@users.noreply.github.com>

daneshk · 2025-03-31T15:12:03Z

native/src/main/java/io/ballerina/stdlib/crypto/PasswordUtils.java

+     * @return formatted PBKDF2 salt string
+     */
+    public static String formatPBKDF2Salt(String algorithm, long iterations, String saltBase64) {
+        return String.format(Locale.ROOT, "$pbkdf2-%s$i=%d$%s",


Shall we make $pbkdf2-%s$i=%d$%s a constant?

daneshk · 2025-03-31T15:18:10Z

native/src/main/java/io/ballerina/stdlib/crypto/nativeimpl/Password.java

+    public static Object verifyPasswordPBKDF2(BString password, BString hashedPassword) {
+        try {
+            String hash = hashedPassword.getValue();
+            Pattern pattern = Pattern.compile("\\$pbkdf2-(\\w+)\\$i=(\\d+)\\$([A-Za-z0-9+/=]+)\\$([A-Za-z0-9+/=]+)");


Shall we make this a constant?

daneshk · 2025-03-31T15:19:22Z

@MohamedSabthar, can you review this please?

ballerina/hash.bal

MohamedSabthar · 2025-04-01T00:45:34Z

native/src/main/java/io/ballerina/stdlib/crypto/PasswordUtils.java

+     * @param algorithm the HMAC algorithm to validate
+     * @return null if valid, error if invalid
+     */
+    public static Object validatePBKDF2Algorithm(String algorithm) {


Suggested change

public static Object validatePBKDF2Algorithm(String algorithm) {

public static Object validatePbkdf2Algorithm(String algorithm) {

Rename validatePBKDF2Algorithm to validatePbkdf2Algorithm to align with camel case conventions, making it more readable and consistent with standard Java naming practices we follow.

Let's update other places.

ballerina/tests/hash_test.bal

native/src/main/java/io/ballerina/stdlib/crypto/nativeimpl/Password.java

docs/proposals/pbkdf2-hashing-apis.md

MohamedSabthar · 2025-04-01T01:18:13Z

native/src/main/java/io/ballerina/stdlib/crypto/PasswordUtils.java

+    /**
+     * Default number of iterations for PBKDF2.
+     */
+    public static final int DEFAULT_PBKDF2_ITERATIONS = 10000;


Is there a reason to maintain constants for default values here? Ideally, these values are already defined as defaultable parameters in the Ballerina code. Instead of maintaining them separately in both Java and Ballerina, we should consider reading and using the values directly from Ballerina to avoid duplication.

Yes, but I think keeping the default values on the Java side would also be good. in the future, if these functions are used internally within the library for testing or any other purposes, they would still work with those default values. Additionally, if for some reason the values don’t get passed from the Ballerina side, the default values would act as a safety net. Let me know if you think it's better to remove them @MohamedSabthar

Thanks for the clarification @randilt! I understand your point, but I still think it's better to avoid duplicating default values in both places. Having a single source of truth helps reduce the risk of inconsistencies and makes maintenance easier in the long run. If there's ever a case where defaults are needed in Java (e.g., for internal tests), we can consider injecting or reading them from the Ballerina side rather than hardcoding. So I'd still prefer removing them from Java for now.

native/src/main/java/io/ballerina/stdlib/crypto/nativeimpl/Password.java

…hPbkdf2 function

…consistency

…idation

…rpolation for improved readability

…rypt, Argon2, and PBKDF2

randilt · 2025-04-04T02:40:28Z

The suggested changes have been made, could you please check @daneshk @MohamedSabthar

ballerina/hash.bal

MohamedSabthar · 2025-04-04T07:27:55Z

docs/spec/spec.md

+Implements the PBKDF2 (Password-Based Key Derivation Function 2) algorithm for password hashing.
+
+```ballerina
+public isolated function hashPbkdf2(string password, int iterations = 10000, 


Let's update the spec and proposal with the enum change

Co-authored-by: MohamedSabthar <sabtharugc0@gmail.com>

MohamedSabthar · 2025-04-04T07:32:23Z

The suggested changes have been made, could you please check @daneshk @MohamedSabthar

Added few comments

randilt · 2025-04-04T16:58:04Z

Did the necessary changes please check @MohamedSabthar

MohamedSabthar · 2025-04-07T04:49:46Z

docs/spec/spec.md

-   * 2.5. [SHA512](#25-sha512)
-   * 2.6. [CRC32B](#26-crc32b)
-   * 2.7. [KECCAK256](#27-keccak256)
+   - 2.1. [MD5](#21-md5)


@randilt shall we update the code with previous formatting?
replace them with '*' instead of '-'.
We follow this same convention across all library modules.

MohamedSabthar · 2025-04-07T04:54:47Z

Did the necessary changes please check @MohamedSabthar

Hi @randilt, the PR looks good overall 🙌. I’ve added a minor comment.
Also, let’s address this one as well: #596 (comment)

Once those are fixed, we can go ahead and merge the PR.

…tils and Password classes

sonarqubecloud · 2025-04-11T14:31:04Z

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

randilt · 2025-04-11T14:33:52Z

@MohamedSabthar I applied the changes you suggested, please check and let me know if anything else needs to be changed or added.

MohamedSabthar

LGTM

MohamedSabthar · 2025-04-16T04:46:27Z

Thanks for your valuable contribution, @randilt!
If you're interested, you can find more 'good first issues' to contribute to here.
Looking forward to seeing more awesome contributions from you! ✨🧑‍💻🚀

randilt · 2025-04-16T09:43:15Z

Thanks for your valuable contribution, @randilt! If you're interested, you can find more 'good first issues' to contribute to here. Looking forward to seeing more awesome contributions from you! ✨🧑‍💻🚀

Appreciate it! Will definitely check them out and keep contributing.

randilt added 8 commits March 17, 2025 22:04

[Automated] Update the native jar versions

6240e8a

Move password hashing methods to Password class removing PasswordArgo…

f11b98a

…n2 class

Add PBKDF2 configuration and validation methods in PasswordUtils

d5744d5

Implement PBKDF2 hashing and verification methods in the crypto module

719fa07

Update PBKDF2 parameters and validation in tests and PasswordUtils

8dd8018

Remove generateSaltPbkdf2 function and related tests from hash module

6a83815

Add PBKDF2 password hashing and verification support to changelog

37188f0

Fix changelog, move the PBKDF2 support change to unreleased

3c667ff

randilt requested review from DimuthuMadushan, MohamedSabthar, ThisaruGuruge and shafreenAnfar as code owners March 18, 2025 16:08

randilt added 3 commits March 18, 2025 21:46

Add proposal for PBKDF2-based password hashing APIs in Ballerina cryp…

095e270

…to module

Add PBKDF2 password hashing and verification documentation to the spe…

af9ef35

…cification

Add PBKDF2 algorithm implementation to the specification

b0afd37

DimuthuMadushan reviewed Mar 19, 2025

View reviewed changes

ballerina/hash.bal Outdated Show resolved Hide resolved

Update ballerina/hash.bal

be53244

Co-authored-by: DimuthuMadushan <35717653+DimuthuMadushan@users.noreply.github.com>

randilt requested a review from DimuthuMadushan March 20, 2025 04:43

daneshk reviewed Mar 31, 2025

View reviewed changes