Add library to securely hash passwords (like bcrypt)

[IMS94]

Description:
Right now, when we want to handle passwords in a Ballerina service, there's no inbuilt option that uses salt/pepper. Hashing passwords using a pure hash function (like SHA512, SHA 256) is not recommended due to hashes of 2 users having the same password will look exactly the same and is a security risk.

Therefore, we need to implement an algorithm like bcrypt (https://www.baeldung.com/spring-security-registration-password-encoding-bcrypt#define-the-password-encoder) into the cryto module.

Describe your problem(s)
I was implementing a REST API to power a React.js based web app and when I wanted to handle user registrations, there was no option to securely hash user passwords.

Describe your solution(s)
Need to implement one or more secure password hashing algorithms (like bcrypt) into the crypto module.

[IMS94]

Related issue: #2441

[IMS94]

@daneshk can we address this?

[HamzaMateen]

Hello, I just wanted to ask if it is a beginner-friendly task to be done. I am pretty excited about such contributions but I just can't make my mind if am ready enough, could you please help me out like what amount of knowledge of Ballerina is just enough to get this working?

Thanks!

[keizer619]

👋 Welcome, @HamzaMateen ! 🚀

We're thrilled to have you join the Ballerina Lang community! Whether you're a seasoned developer or just starting your journey with Ballerina, we value your contributions and look forward to collaborating with you.
To help you get started, here are some essential resources:

1. Understanding Ballerina Platform:
   Learn what Ballerina is all about: Ballerina Platform
2. How to Contribute:
   Read our contributing guidelines to understand how you can contribute effectively: Contribution Guide
3. Contributing to the Ballerina library:
   If you're interested in contributing to our library, here are the guidelines: Library Contribution Guide
4. Learn Ballerina:
   If you're new to Ballerina or want to enhance your skills, our official website offers a wealth of learning resources: Learn Ballerina
5. Get Help and Connect:
   Join our Discord community to chat with fellow Ballerina enthusiasts and get assistance: Ballerina Discord

Remember, no contribution is too small, and your feedback is invaluable. Feel free to ask questions, propose ideas, or report issues. Together, we can make Ballerina even better!
Happy coding! 🎉

[Bhashinee]

Hello @HamzaMateen,
Pleased to see your interest in this issue.

This issue proposes the addition of a fresh API within the Ballerina Crypto package for password hashing using BCrypt. So you need to come up with a new API design(you need to state what is the API function name that you are going to introduce, what are the input parameters, and what would be the returning data type) that helps to support the above-mentioned requirement.

It would be easier for you to use a Java Bcrypt library to implement this by calling its functions in the Ballerina code. You can refer to how to call Java functions using Ballerina here.

[HamzaMateen]

This is wonderful!
I will come up with a proposal as soon as possible.

[HamzaMateen]

Okay so I tried building the ballerina-distribution, which I was able to build successfully but I encountered the following error during the execution phase after running the command:

> ./gradlew clean build -x test

Starting a Gradle Daemon (subsequent builds will be faster)

> Task :config:checkstyle:downloadMultipleFiles UP-TO-DATE
Download https://raw.githubusercontent.com/wso2/code-quality-tools/v1.4/checkstyle/jdk-17/checkstyle.xml
Download https://raw.githubusercontent.com/wso2/code-quality-tools/v1.4/checkstyle/jdk-17/suppressions.xml

> Task :ballerina:unpackBallerinaJre
Download https://github.com/ballerina-platform/ballerina-custom-jre/releases/download/2.0.0/ballerina-jre-linux-64-2.0.0.zip
Download https://github.com/ballerina-platform/ballerina-custom-jre/releases/download/2.0.0/ballerina-jre-win-64-2.0.0.zip
Download https://github.com/ballerina-platform/ballerina-custom-jre/releases/download/2.0.0/ballerina-jre-macos-64-2.0.0.zip
Download https://github.com/ballerina-platform/ballerina-custom-jre/releases/download/2.0.0/ballerina-jre-macos-arm-64-2.0.0.zip

> Task :ballerina:unpackBallerinaJre UP-TO-DATE

> Task :ballerina:downloadBalCommand
Download https://github.com/ballerina-platform/ballerina-update-tool/releases/download/v1.4.0/ballerina-command-1.4.0.zip

> Task :ballerina:extractJreForLinux FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':ballerina:extractJreForLinux'.
> Cannot expand ZIP '/home/ycombinator/opensource/hacktoberfest/2023/ballerina-distribution/ballerina/downloads/ballerina-jre-artifacts-zip/ballerina-jre-linux-64-2.0.0.zip'.

* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Get more help at https://help.gradle.org.

Deprecated Gradle features were used in this build, making it incompatible with Gradle 9.0.

You can use '--warning-mode all' to show the individual deprecation warnings and determine if they come from your own scripts or plugins.

For more on this, please refer to https://docs.gradle.org/8.2.1/userguide/command_line_interface.html#sec:command_line_warnings in the Gradle documentation.

BUILD FAILED in 30s
39 actionable tasks: 30 executed, 6 from cache, 3 up-to-date

I am unsure but how I should upgrade the gradle version.

PS. I have read up on Java and the Ballerina Interop mechanism and am ready to start creating my API for BCrypt, but this project build is slowing me down. Your help will be appreciated! Thanks

[Bhashinee]

Hello @HamzaMateen

You can start this by building the crypto module rather than building the entire ballerina distribution. To test the solution you can simply add a test case in the test folder and run the build command(./gradlew clean build) which will build the module with the changes and run the tests.

[Marcono1234]

For any future reader: When using Bouncy Castle's BCrypt#generate you should add a trailing null byte, otherwise passwords where one is the repetition of the other (e.g. "abc" and "abcabc") will have the same hash. See bcgit/bc-java#393.

Or depending on the use case, you could use org.bouncycastle.crypto.generators.OpenBSDBCrypt instead, which handles this automatically, encodes the salt in the result and also provides convenience methods for comparing password hashes.

(Or use the bcrypt implementation from another library.)

[Riyan-Mo]

Can I please work on this issue?

[keizer619]

Hi @Riyan-Mo

I have assigned the issue to you.
To help you get started, here are some essential resources:

1. Understanding Ballerina Platform:
   Learn what Ballerina is all about Ballerina Platform
2. How to Contribute:
   Read our contributing guidelines to understand how you can contribute effectively: Contribution Guide
3. Contributing to the Ballerina Library:
   If you're interested in contributing to our library, here are the guidelines: Library Contribution Guide
4. Learn Ballerina:
   If you're new to Ballerina or want to enhance your skills, our official website offers a wealth of learning resources: Learn Ballerina
5. Get Help and Connect:
   Ask technical questions on Stack Overflow with Ballerina tag and join our Discord community Ballerina Discord

[Riyan-Mo]

@keizer619 Thank you for assigning me this issue. I will gladly use the resources.

[keizer619]

@Riyan-Mo Are you still working on this? If not we can open this for others

[Riyan-Mo]

@keizer619 Please unassign me and open this issue to others.

[randilt]

Hi,
I would like to work on this issue.

[daneshk]

@randilt Could you update the proposed new API here please. We need to keep update the issue with the new API design.

[randilt]

@randilt Could you update the proposed new API here please. We need to keep update the issue with the new API design.

Password Hashing API for Ballerina Crypto Module

New password hashing API in the crypto module will provide functions to hash passwords securely using BCrypt and Argon2id algorithms.

BCrypt

Implements the BCrypt password hashing algorithm based on the Blowfish cipher.

public isolated function hashBcrypt(string password, int workFactor = 12) returns string|Error

Parameters:

• password: The plain text password to hash
• workFactor: Computational complexity factor (4-31, default: 12)

public isolated function verifyBcrypt(string password, string hashedPassword) returns boolean|Error

Example:

string password = "your-password";
// Hash with default work factor (12)
string hashedPassword1 = check crypto:hashBcrypt(password);
// Hash with custom work factor
string hashedPassword2 = check crypto:hashBcrypt(password, 14);
boolean isValid = check crypto:verifyBcrypt(password, hashedPassword1);

Argon2

Implements the Argon2id variant of the Argon2 password hashing algorithm, optimized for both high memory usage and GPU resistance.

public isolated function hashArgon2(string password, int iterations = 3, 
    int memory = 65536, int parallelism = 4) returns string|Error

Parameters:

• password: The plain text password to hash
• iterations: Number of iterations (default: 3)
• memory: Memory usage in KB (minimum: 8192, default: 65536)
• parallelism: Degree of parallelism (default: 4)

Output hash length is fixed at 256 bits for optimal security and performance.

public isolated function verifyArgon2(string password, string hashedPassword) returns boolean|Error

Example:

string password = "your-password";
// Hash with default parameters
string hashedPassword1 = check crypto:hashArgon2(password);
// Hash with custom parameters
string hashedPassword2 = check crypto:hashArgon2(password, 4, 131072, 8);
boolean isValid = check crypto:verifyArgon2(password, hashedPassword1);