Password4j is a Java user-friendly cryptographic library for hashing and checking passwords with different Key derivation functions (KDFs) and Cryptographic hash functions (CHFs).
Algorithms can be configured programmatically or through a property file in your classpath see Configuration section.
The configurations are mostly dependent on your environment. Password4j delivers a tool that can create a set of optimal parameters based on the system performance and the desired maximum computational time see Performance section.
The library fully supports Argon2, BCrypt, SCrypt and PBKDF2 and can produce and handle cryptographic salt and pepper.
Documentation
The full documentation can be found here. For a quick start you can follow the instuctions in the README.md.
The javadoc can be found here.
Installation
Password4j runs on Java 8 or higher versions by any vendor. It is supported by Android API 21+ as well.
The artifacts are deployed to Maven Central.
Maven
Add the dependency of the latest version to your pom.xml:
<dependency>
<groupId>com.password4j</groupId>
<artifactId>password4j</artifactId>
<version>1.5.2</version>
</dependency>
Gradle
Add to your build.gradle module dependencies:
repositories {
mavenCentral()
}
dependencies {
implementation 'com.password4j:password4j:1.5.2'
}
Scala SBT
Add to the managed dependencies of your build.sbt the latest version:
libraryDependencies += "com.password4j" % "password4j" % "1.5.2"
Usage
Password4j provides three main features: password hashing, hash checking and hash updating.
Hash the password
Here it is the easiest way to hash a password with a CHF (BCrypt in this case)
Hash hash = Password.hash(password).withBCrypt();
Salt and pepper may be optionally added to the builder (PBKDF2 in this case):
// PBKDF2 with salt 12 bytes long (randomly generated).
Hash hash = Password.hash(password).addRandomSalt(12).withPBKDF2();
// PBKDF2 with a chosen salt.
Hash hash = Password.hash(password).addSalt(salt).withPBKDF2();
// PBKDF2 with chosen salt and pepper.
Hash hash = Password.hash(password).addSalt(salt).addPepper(pepper).withPBKDF2();
// Custom PBKDF2 (PBKDF2 with HMAC-SHA512, 64000 iterations and 512bit length).
Hash hash = Password.hash(password).with(PBKDF2Function.getInstance(Hmac.SHA512, 64000, 512));
The same structure can be adopted for the other CHFs, not just for PBKDF2.
Verify the hash
With the same ease you can verify the hash:
boolean verified = Password.check(password, hash).withBCrypt();
Salt and pepper may be optionally added to the builder (PBKDF2 in this case):
// Verify with PBKDF2.
boolean verification = Password.check(password, hash).withPBKDF2();
// Verify with PBKDF2 and manually provided salt.
boolean verification = Password.check(password, hash).addSalt(salt).withPBKDF2();
// Verify with PBKDF2 and manually provided salt and pepper.
boolean verification = Password.check(password, hash).addSalt(salt).addPepper(pepper).withPBKDF2();
The same structure can be adopted for the other algorithms, not just for PBKDF2. Take in account that Argon2, BCrypt and SCrypt store the salt inside the hash, so the addSalt() method is not needed.
// Verify with Argon2, reads the salt from the given hash.
boolean verification = Password.check(password, hash).withArgon2();
Some algorithms encode into the hash the parameters that were used to compute that hash, notably BCrypt, SCrypt, and Argon2. When checking a hash, you can use the parameters from the hash rather than Password4j's configured defaults.
// Verify with Argon2, reads the salt and parameters from the given hash.
boolean verification = Password.check(password, hash)..with(Argon2Function.getInstanceFromHash(hash)));
Update the hash
When a configuration is not considered anymore secure you can refresh the hash with a more modern algorithm like this:
// Reads the latest configurations in your psw4j.properties
HashUpdate update = Password.check(password, hash).update().withBCrypt();
if(update.isVerified())
{
Hash newHash = update.getHash();
}
Or if you want to switch from a CHF to another one:
PBKDF2Function pbkdf2 = AlgorithmFinder.getPBKDF2Instance();
HashUpdate update = Password.check(password, hash).update().withSCrypt(pbkdf2);
if(update.isVerified())
{
Hash newHash = update.getHash();
}
Unsecure Algorithms
Many systems may still use unsecure algorithms for storing the passwords, like MD5 or SHA-256. You can easily migrate to stronger algorithms with Password4j
MessageDigestFunction md = MessageDigestFunction.getInstance("SHA-256");
HashUpdate update = Password.check(password, hash).update().withSCrypt(md);
if(update.isVerified())
{
Hash newHash = update.getHash();
}
List of supported algorithms
| Key derivation Functions | Since | Notes |
|---|---|---|
| PBKDF2 | 1.0.0 | Depending on the Security Services your JVM provides |
| BCrypt | 1.0.0 | |
| SCrypt | 1.0.0 | |
| Argon2 | 1.5.0 |
| Cryptographic Hash Functions | Since | Notes |
|---|---|---|
| MD Family | 1.4.0 | |
| SHA1 Family | 1.4.0 | |
| SHA2 Family | 1.4.0 | |
| SHA3 FAmily | 1.4.0 | Depending on the Security Providers your JVM provides |
Security of Strings
Strings are immutable objects and once stored in memory you cannot erase them until Garbage Collection. It is always recommended to use char[] instead of String for storing passwords(where possible - If we're talking of a web application, most web containers will pass the password into the HttpServletRequest object in plaintext as String).
An attacker that is able to dump the memory could read the password before you use it as input for Password4j; even if it is read after its usage, it is not guaranteed when the garbage collection occurs: that means that the password may be stored in memory indefinitely and its value cannot be erased.
For this reason Password4j provides a SecureString class that alleviates this problem. The provided char[] is wrapped around SecureString and it is never converted into a String during the process.
You can erase the underlying char[] with clear() method.
SecureString secure = new SecureString(new char[]{...});
Password.hash(secure).withBCrypt();
Password.check(secure, hash).withBCrypt();
secure.clear();
// At this point the underlying char[] = {\0, \0, \0, ...}
In addition to this, you may want to clean the original char[]. With the following code even the source is zeroed:
char[] password = {...}
SecureString secure = new SecureString(password, true);
// At this point password = {\0, \0, \0, ...}
The pepper can be expressed as SecureString as well.
Using SecureString or char[] does not completely defend you from attacks: the Garbage Collector constantly copies objects from the from space to the to space and ereasing the original char[] does not erase its copies; moreover it is never guaranteed that clear() is applied before the garbage collection. For these reasons the usage of SecureString or char[] just reduces the window of opportunities for an attacker.
Configuration
Password4j makes available a portable way to configure the library.
With the property file psw4j.properties put in your classpath, you can define the parameters of all the supported CHFs or just the CHF(s) you need. Alternatively you can specify a custom path with the system property -Dpsw4j.configuration
java -Dpsw4j.configuration=/my/path/to/some.properties ...
Here's a basic configuration (please do not use it in production, but instead start a benchmark session in your target environmentsee Performance section)
### Argon2
hash.argon2.memory=4096
hash.argon2.iterations=20
hash.argon2.length=128
hash.argon2.parallelism=4
hash.argon2.type=id
### BCrypt
hash.bcrypt.minor=b
# logarithmic cost (cost = 2^12)
hash.bcrypt.rounds=12
### SCrypt
# N
hash.scrypt.workfactor=16384
# r
hash.scrypt.resources=16
# p
hash.scrypt.parallelization=1
# length
hash.scrypt.derivedKeyLength=64
### PBKDF2
# with HMAC-SHA256
hash.pbkdf2.algorithm=SHA256
# 64000 iterations
hash.pbkdf2.iterations=64000
# derived key of 256bit
hash.pbkdf2.length=256
### Legacy MessageDisgest
# algorithm
hash.md.algorithm=SHA-512
# append/prepend salt
hash.md.salt.option=append
Additionally you can define here your shared pepper
global.pepper=AlicePepper
and use it like this
// Hash
Password.hash("password").addPepper().withSCrypt();
// Verify
Password.check("password", "hash").addPepper().withSCrypt();
SecureRandom may be instantiated and used through SecureRandom.getInstanceStrong() to generate salts and peppers.
global.random.strong=true
but make sure that your JVM supports it and it points to a non-blocking source of entropy, otherwise you may experience huge performance dropssee SecureRandom.
Performance
This tool must be used in the target system because performances may vary on different environments.
Password4j is delivered with a tool that helps the developers to choose the right parameters for a specific CHF.
The class SystemChecker can be used to find these optimal values.
In the wiki you can find how to configure PBKDF2, bcrypt, scrypt and Argon2 depending on your responsiveness requirements.
Contributing
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
Versioning
We use SemVer for versioning.
For the versions available, see the releases on this repository.
Authors
- David Bertoldi - Main Maintainer - firaja
See also the list of contributors who participated in this project.
License
This project is licensed under the Apache License 2.0 License - see the LICENSE file for details
Changelog
See the CHANGELOG.md file for a more detailed description of each release.
12.9k Jan 3, 2023
1.6k Dec 29, 2022
1 Apr 1, 2022
2k Dec 30, 2022
4 Dec 6, 2022
135 Dec 29, 2022
6 Nov 21, 2022
3 Mar 9, 2022
106 Dec 30, 2022
206 Oct 5, 2022
11 Oct 12, 2022
29 Nov 3, 2022
33 Jan 3, 2022
2 Dec 8, 2021
1 Jan 4, 2022
2 Apr 26, 2022
1 Oct 9, 2022
14.6k Jan 5, 2023