### Create CompressedPBKDF2Function from hash Source: https://github.com/password4j/password4j/wiki/CompressedPBKDF2 Creates a singleton CompressedPBKDF2Function instance from an existing compressed hash, since all parameters are stored in the hash string. ```java String hashed = "$3$42949672960256$YWJj$/WTQfTTc8Hg8GlplP0LthpgdElUG+I3MyuvK8MI4MnQ="; CompressedPBKDF2Function pbkdf2 = CompressedPBKDF2Function.getInstanceFromHash(hashed); ``` -------------------------------- ### Get Compressed PBKDF2 instance from properties file Source: https://github.com/password4j/password4j/wiki/CompressedPBKDF2 Retrieves a singleton CompressedPBKDF2Function using parameters defined in the psw4j.properties file. Requires that the properties file is configured. ```java PBKDF2Function pbkdf2 = AlgorithmFinder.getCompressedPBKDF2Instance(); ``` -------------------------------- ### Define Compressed PBKDF2 parameters with PBKDF2Function.getInstance Source: https://github.com/password4j/password4j/wiki/CompressedPBKDF2 Creates a singleton CompressedPBKDF2Function using HMAC SHA-256, 100000 iterations, and 1024-byte hash length. Requires prior definition of PBKDF2 parameters. ```java PBKDF2Function pbkdf2 = CompressedPBKDF2Function.getInstance(Hmac.SHA256, 100000, 1024); ``` -------------------------------- ### Benchmark Argon2 with SystemChecker Source: https://github.com/password4j/password4j/wiki/Recommended-settings Use SystemChecker.benchmarkForArgon2 to determine the number of iterations needed to keep hashing time under a specified maximum (e.g., 500 ms). The example uses 4MB memory, 2 threads, and 128-byte output; the result provides the prototype's iterations and the real elapsed time. ```java long maxMilliseconds = 500; int memory = 4096; int threads = 2; int outputLength = 128; Argon2 type = Argon2.ID; BenchmarkResult result = SystemChecker.benchmarkForArgon2(n, memory, threads, outputLength, type); int iterations = result.getPrototype().getIterations(); // 219 long realElapsed = result.getElapsed() // 468 ``` -------------------------------- ### Benchmark PBKDF2 with SystemChecker Source: https://github.com/password4j/password4j/wiki/Recommended-settings Use SystemChecker.benchmarkPBKDF2(n, Hmac.SHA512, 512) to determine the number of iterations that keep hashing under a target time. In the example, with n=100 ms, the result is 48750 iterations and an elapsed time of 89 ms. ```java long n = 100; BenchmarkResult result = SystemChecker.benchmarkPBKDF2(n, Hmac.SHA512, 512); int numberOfIterations = result.getPrototype().getIterations(); // 48750 long realElapsed = result.getElapsed() // 89 ``` -------------------------------- ### Get ScryptFunction from properties file Source: https://github.com/password4j/password4j/wiki/Scrypt Retrieves a ScryptFunction singleton instance using parameters defined in the psw4j.properties file. ```java ScryptFunction scrypt = AlgorithmFinder.getScryptInstance(); ``` -------------------------------- ### Hash object example Source: https://github.com/password4j/password4j/wiki/Usage-of-Password4j Shows the typical usage of the hash verb, which always returns a Hash object. The Hash object contains the computed hash, salt, pepper, and the hashing function used. ```java Hash hash = Password.hash(plainTextPassword)... ``` -------------------------------- ### Check hash with Compressed PBKDF2 Source: https://github.com/password4j/password4j/wiki/CompressedPBKDF2 Verifies a user-provided password against a stored hash and salt using withCompressedPBKDF2(). Returns a boolean indicating verification success. ```java String hashFromDB = getHashFromDatabase(user); String saltFromDB = getSaltFromDatabase(user); boolean verified = Password.check(userProvidedPassword, hashFromDB).addSalt(saltFromDB).withCompressedPBKDF2(); ``` -------------------------------- ### Get PBKDF2Function from properties file Source: https://github.com/password4j/password4j/wiki/PBKDF2 Retrieves a PBKDF2 function instance using parameters defined in the psw4j.properties file. This is an alternative to specifying parameters programmatically. ```java PBKDF2Function pbkdf2 = AlgorithmFinder.getPBKDF2Instance(); ``` -------------------------------- ### Get SecureRandom instance Source: https://github.com/password4j/password4j/wiki/Properties Use this to obtain the SecureRandom instance configured by the global.random.strong property. If that property is true, it uses SecureRandom.getInstanceStrong(), which may block if the JVM's entropy source is not non-blocking. ```java Random random = AlgorithmFinder.getSecureRandom(); ``` -------------------------------- ### Create Argon2Function from hash Source: https://github.com/password4j/password4j/wiki/Argon2 Creates an Argon2Function singleton instance from an existing hash string, since all required parameters are stored in the hash. The example uses an Argon2id hash with version 19, memory 1024, iterations 3, parallelism 12. ```java String hashed = "$argon2id$v=19$m=1024,t=3,p=12$MzMzMzMzMzM$DXUE5N4lm4plldg9nGMq+tYsbGhko8HWpPaADujpgFQ"; Argon2Function argon2 = Argon2Function.getInstanceFromHash(hashed); ``` -------------------------------- ### Create Argon2Function with explicit parameters Source: https://github.com/password4j/password4j/wiki/Argon2 Creates a singleton Argon2Function instance with specified memory, iterations, parallelism, output length, type, and version. The example uses 1024 KiB memory, 3 iterations, 2 threads, 32-byte key, Argon2d type, and version 19. ```java Argon2Function argon2 = Argon2Function.getInstance(1024, 3, 2, 32, Argon2.d, 19); ``` -------------------------------- ### Get BcryptFunction from properties file Source: https://github.com/password4j/password4j/wiki/BCrypt Retrieves a BcryptFunction instance using parameters defined in the psw4j.properties file. Use this when you have configured bcrypt settings externally. ```java BcryptFunction bcrypt = AlgorithmFinder.getBcryptInstance(); ``` -------------------------------- ### Get Argon2Function from properties file Source: https://github.com/password4j/password4j/wiki/Argon2 Retrieves an Argon2Function instance using parameters defined in the psw4j.properties file. This is an alternative to specifying parameters directly. ```java Argon2Function argon2 = AlgorithmFinder.getArgon2Instance(); ``` -------------------------------- ### Hash password with Compressed PBKDF2 Source: https://github.com/password4j/password4j/wiki/CompressedPBKDF2 Hashes a plain text password using the withCompressedPBKDF2() method. The result is a compressed hash string containing algorithm, salt, and hash in base64. ```java Hash hash = Password.hash(plainTextPassword).withCompressedPBKDF2(); hash.getResult(); // $3$42949672960256$YWJj$/WTQfTTc8Hg8GlplP0LthpgdElUG+I3MyuvK8MI4MnQ= ``` -------------------------------- ### HashUpdate object example Source: https://github.com/password4j/password4j/wiki/Usage-of-Password4j Shows the typical usage of the update verb, which always returns a HashUpdate object. The HashUpdate object contains a boolean indicating if the check passed and a Hash object with the refreshed hash (null if check failed). ```java HashUpdate update = Password.check(hash, plainTextPassword)...andUpdate()... ``` -------------------------------- ### Update hash with Compressed PBKDF2 Source: https://github.com/password4j/password4j/wiki/CompressedPBKDF2 Updates a stored hash with a new random salt using a CompressedPBKDF2Function derived from the existing hash. Stores new hash and salt if verification succeeds. ```java String hashFromDB = getHashFromDatabase(user); String saltFromDB = getSaltFromDatabase(user); CompressedPBKDF2Function myPbkdf2 = PBKDF2Function.getInstanceFromHash(hashFromDB); HashUpdate update = Password.check(userProvidedPassword, hashFromDB).addSalt(saltFromDB) .andUpdate() .addNewRandomSalt().with(myPbkdf2); if(update.isVerified()) { Hash newHash = update.getHash(); storeNewHash(user, newHash.getHash()); storeNewSalt(user, newHash.getSalt()); } ``` -------------------------------- ### Get pepper value Source: https://github.com/password4j/password4j/wiki/Properties Use this to read the global pepper value configured by the global.pepper property. The pepper should never be stored in the database, or at least not in the same hashes' database. ```java String pepper = PepperGenerator.get(); ``` -------------------------------- ### Run Java with custom configuration path Source: https://github.com/password4j/password4j/blob/master/README.md Specify a custom path for the configuration file using the system property -Dpsw4j.configuration. ```shell script java -Dpsw4j.configuration=/my/path/to/some.properties ... ``` -------------------------------- ### Use pepper with Password.hash and Password.check Source: https://github.com/password4j/password4j/blob/master/README.md Shows how to add a pepper when hashing and verifying passwords with scrypt. ```java // Hash Password.hash("password").addPepper().withScrypt(); // Verify Password.check("password", "hash").addPepper().withScrypt(); ``` -------------------------------- ### Gradle dependency for Password4j Source: https://github.com/password4j/password4j/wiki/Setting-up-Password4j Add these lines to your build.gradle module dependencies to include Password4j 1.7.2 from Maven Central. ```groovy repositories { mavenCentral() } dependencies { implementation 'com.password4j:password4j:1.7.2' } ``` -------------------------------- ### Run Java with custom psw4j.properties path Source: https://github.com/password4j/password4j/wiki/Properties Use the system property -Dpsw4j.configuration to specify a custom location for the psw4j.properties file when it is not in the resources folder. ```bash java -Dpsw4j.configuration=path/to/my/file.properties myApp.jar ``` -------------------------------- ### Use SecureRandom.getInstanceStrong for salts and peppers Source: https://github.com/password4j/password4j/blob/master/README.md Enables strong random generation. Ensure JVM supports it and points to non-blocking entropy to avoid performance drops. ```properties global.random.strong=true ``` -------------------------------- ### Scala SBT dependency for Password4j Source: https://github.com/password4j/password4j/wiki/Setting-up-Password4j Add this line to the managed dependencies of your build.sbt to use Password4j 1.7.2. ```shell script libraryDependencies += "com.password4j" % "password4j" % "1.7.2" ``` -------------------------------- ### List supported PBKDF2 algorithms Source: https://github.com/password4j/password4j/wiki/Recommended-settings Use AlgorithmFinder.getAllPBKDF2Variants() to check which PBKDF2 algorithms your JVM supports. The output shows the available variants, e.g., PBKDF2WithHmacSHA1 through PBKDF2WithHmacSHA512. ```java AlgorithmFinder.getAllPBKDF2Variants().forEach(System.out::println); // PBKDF2WithHmacSHA1 // PBKDF2WithHmacSHA224 // PBKDF2WithHmacSHA256 // PBKDF2WithHmacSHA384 // PBKDF2WithHmacSHA512 ``` -------------------------------- ### AlgorithmFinder.getPBKDF2Instance() Source: https://github.com/password4j/password4j/wiki/PBKDF2 Retrieves a PBKDF2Function instance based on parameters defined in the psw4j.properties file. This method is used when configuration is externalized. ```APIDOC ## AlgorithmFinder.getPBKDF2Instance() ### Description Retrieves a PBKDF2Function instance based on parameters defined in the psw4j.properties file. This method is used when configuration is externalized. ### Method `getPBKDF2Instance` ### Parameters None ### Return Value - **PBKDF2Function** - A PBKDF2Function instance configured from properties. ### Example ```java PBKDF2Function pbkdf2 = AlgorithmFinder.getPBKDF2Instance(); ``` ``` -------------------------------- ### Benchmark scrypt resources with SystemChecker.findResourcesForScrypt Source: https://github.com/password4j/password4j/wiki/Recommended-settings Use after determining the work factor to find the optimal resources (block size) for scrypt. The result's prototype gives the resources; the elapsed time is in milliseconds. ```java long n = 300; BenchmarkResult result = SystemChecker.findResourcesForScrypt(n, 32768, 1); int resources = result.getPrototype().getResources(); // 9 long realElapsed = result.getElapsed() // 240 ``` -------------------------------- ### ScryptFunction.getInstance(int, int, int, int) Source: https://github.com/password4j/password4j/wiki/Scrypt Creates a singleton ScryptFunction instance with explicit work factor, resources, parallelisation, and derived key length parameters. This method allows direct configuration of all scrypt parameters. ```APIDOC ## ScryptFunction.getInstance(int, int, int, int) ### Description Creates a singleton ScryptFunction instance with explicit work factor, resources, parallelisation, and derived key length parameters. This method allows direct configuration of all scrypt parameters. ### Method ScryptFunction.getInstance(int, int, int, int) ### Parameters - **workFactor** (int) - Required - Defines the CPU/memory cost. Must be a power of 2. - **resources** (int) - Required - Defines the size of memory blocks. - **parallelisation** (int) - Required - Defines the cost of parallelisation for an attacker. - **derivedKeyLength** (int) - Required - Defines the desired length of the final derived key. ### Request Example ```java ScryptFunction scrypt = ScryptFunction.getInstance(16384, 8, 2, 128); ``` ``` -------------------------------- ### Basic configuration for supported CHFs Source: https://github.com/password4j/password4j/blob/master/README.md Defines parameters for Argon2, bcrypt, scrypt, PBKDF2, and legacy MessageDigest. Not for production use; benchmark in your target environment. ```properties ### 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 ``` -------------------------------- ### ScryptFunction.getInstance(int, int, int) Source: https://github.com/password4j/password4j/wiki/Scrypt Creates a singleton ScryptFunction instance with explicit work factor, resources, and parallelisation parameters, using the default derived key length. This method allows direct configuration of scrypt parameters without specifying output length. ```APIDOC ## ScryptFunction.getInstance(int, int, int) ### Description Creates a singleton ScryptFunction instance with explicit work factor, resources, and parallelisation parameters, using the default derived key length. This method allows direct configuration of scrypt parameters without specifying output length. ### Method ScryptFunction.getInstance(int, int, int) ### Parameters - **workFactor** (int) - Required - Defines the CPU/memory cost. Must be a power of 2. - **resources** (int) - Required - Defines the size of memory blocks. - **parallelisation** (int) - Required - Defines the cost of parallelisation for an attacker. ``` -------------------------------- ### Use custom HashingFunction Source: https://github.com/password4j/password4j/wiki/Developer-Guide Once you have created your implementation class, you can use it with Password.hash().addSalt().addPepper().with(). ```java MyFunction myFunction = new MyFunction(); Password.hash(plainTextPassword).addSalt(salt).addPepper(pepper).with(myFunction); ``` -------------------------------- ### AlgorithmFinder.getScryptInstance() Source: https://github.com/password4j/password4j/wiki/Scrypt Retrieves a ScryptFunction singleton instance using parameters defined in the psw4j.properties file. This method allows configuration of scrypt parameters through a properties file. ```APIDOC ## AlgorithmFinder.getScryptInstance() ### Description Retrieves a ScryptFunction singleton instance using parameters defined in the psw4j.properties file. This method allows configuration of scrypt parameters through a properties file. ### Method AlgorithmFinder.getScryptInstance() ### Request Example ```java ScryptFunction scrypt = AlgorithmFinder.getScryptInstance(); ``` ``` -------------------------------- ### AlgorithmFinder.getBcryptInstance() Source: https://github.com/password4j/password4j/wiki/BCrypt Retrieves a BcryptFunction singleton instance using parameters defined in the psw4j.properties file. This is used to obtain a configured bcrypt function. ```APIDOC ## AlgorithmFinder.getBcryptInstance() ### Description Retrieves a BcryptFunction singleton instance using parameters defined in the psw4j.properties file. This is used to obtain a configured bcrypt function. ### Method `getBcryptInstance` ### Parameters None ### Return Value - **BcryptFunction** - A singleton instance of BcryptFunction ### Request Example ```java BcryptFunction bcrypt = AlgorithmFinder.getBcryptInstance(); ``` ``` -------------------------------- ### BCryptFunction.getInstance(int) Source: https://github.com/password4j/password4j/wiki/BCrypt Creates a singleton BcryptFunction instance with a specified cost factor, using the default bcrypt version. This is used to configure the bcrypt hashing algorithm parameters. ```APIDOC ## BCryptFunction.getInstance(int) ### Description Creates a singleton BcryptFunction instance with a specified cost factor, using the default bcrypt version. This is used to configure the bcrypt hashing algorithm parameters. ### Method `getInstance` ### Parameters - **int** (int) - Required - The cost factor (number of rounds as exponent of base 2) ### Return Value - **BcryptFunction** - A singleton instance of BcryptFunction ``` -------------------------------- ### Implement HashingFunction interface Source: https://github.com/password4j/password4j/wiki/Developer-Guide Use this approach if you need to handle the pepper differently. Remember to set the pepper in the Hash object. ```java public class MyFunction implements HashingFunction { @Override public Hash hash(CharSequence plainTextPassword) { // hash plainTextPassword without salt ... return new Hash(this, hashAsString, hashAsBytes, null); } @Override public Hash hash(CharSequence plainTextPassword, String salt) { // hash plainTextPassword with a salt ... return new Hash(this, hashAsString, hashAsBytes, salt); } @Override public Hash hash(CharSequence plainTextPassword, String salt, CharSequence pepper) { // hash plainTextPassword with a salt and pepper ... Hash result = new Hash(this, hashAsString, hashAsBytes, salt); hash.setPepper(pepper); return result; } @Override public boolean check(CharSequence plainTextPassword, String hashed) { // verify the plainTextPassword and the hash ... return true / false; } @Override public boolean check(CharSequence plainTextPassword, String hashed, String salt) { // verify the plainTextPassword and the hash with salt ... return true / false; } @Override public boolean check(CharSequence plainTextPassword, String hashed, String salt, CharSequence pepper) { // verify the plainTextPassword and the hash with salt and pepper ... return true / false; } } ``` -------------------------------- ### Maven dependency for Password4j Source: https://github.com/password4j/password4j/wiki/Setting-up-Password4j Add this dependency to your Maven project's pom.xml to use Password4j version 1.7.2. Requires Java 8 or higher and Android API level 26 or higher. ```xml com.password4j password4j 1.7.2 ``` -------------------------------- ### Create ScryptFunction from hash Source: https://github.com/password4j/password4j/wiki/Scrypt Creates a ScryptFunction singleton instance from an existing scrypt hash, extracting all required parameters from the hash itself. ```java String hashed = "$s0$e0801$c2FsdA==$dFcxr0SE8yOWiWntoomu7gBbWQOsVh5kpayhIXl793NO+f1YQi4uIhg7ysup7Ie6DIO3oueI8Dzg2gZGNDPNpg=="; ScryptFunction scrypt = ScryptFunction.getInstanceFromHash(hashed); ``` -------------------------------- ### BCryptFunction.getInstance(Bcrypt, int) Source: https://github.com/password4j/password4j/wiki/BCrypt Creates a singleton BcryptFunction instance with a specified bcrypt version and cost factor. This is used to configure the bcrypt hashing algorithm parameters. ```APIDOC ## BCryptFunction.getInstance(Bcrypt, int) ### Description Creates a singleton BcryptFunction instance with a specified bcrypt version and cost factor. This is used to configure the bcrypt hashing algorithm parameters. ### Method `getInstance` ### Parameters - **Bcrypt** (Bcrypt) - Required - The bcrypt version (e.g., Bcrypt.Y) - **int** (int) - Required - The cost factor (number of rounds as exponent of base 2) ### Return Value - **BcryptFunction** - A singleton instance of BcryptFunction ### Request Example ```java BcryptFunction bcrypt = BcryptFunction.getInstance(Bcrypt.Y, 11); ``` ``` -------------------------------- ### Extend AbstractHashingFunction Source: https://github.com/password4j/password4j/wiki/Developer-Guide Recommended approach: extend AbstractHashingFunction and implement the abstract methods. The pepper is already prepended to plainTextPassword, so you don't need to manage it. ```java public class MyFunction extends AbstractHashingFunction { @Override public Hash hash(CharSequence plainTextPassword) { // hash plainTextPassword without salt ... return new Hash(this, hashAsString, hashAsBytes, null); } @Override public Hash hash(CharSequence plainTextPassword, String salt) { // hash plainTextPassword with a salt ... return new Hash(this, hashAsString, hashAsBytes, salt); } @Override public boolean check(CharSequence plainTextPassword, String hashed) { // verify the plainTextPassword and the hash ... return true / false; } } ``` -------------------------------- ### PBKDF2Function.getInstance(String, int, int) Source: https://github.com/password4j/password4j/wiki/PBKDF2 Creates a singleton custom PBKDF2 function using a string HMAC algorithm. This method allows specifying an HMAC function not listed in the Hmac enum. ```APIDOC ## PBKDF2Function.getInstance(String, int, int) ### Description Creates a singleton custom PBKDF2 function using a string HMAC algorithm. This method allows specifying an HMAC function not listed in the Hmac enum. ### Method `getInstance` ### Parameters - **algorithm** (String) - Required - The HMAC algorithm as a string. - **iterations** (int) - Required - The number of iterations. - **length** (int) - Required - The desired output length in bytes. ### Return Value - **PBKDF2Function** - A singleton instance of PBKDF2Function. ### Example ```java PBKDF2Function pbkdf2 = PBKDF2Function.getInstance("HmacSHA256", 100000, 1024); ``` ``` -------------------------------- ### Benchmark scrypt work factor with SystemChecker.findWorkFactorForScrypt Source: https://github.com/password4j/password4j/wiki/Recommended-settings Use when your application requires a specific hashing time (n milliseconds) and you need to determine the scrypt work factor. The result's prototype gives the work factor; the elapsed time is in milliseconds. ```java long n = 300; BenchmarkResult result = SystemChecker.findWorkFactorForScrypt(n, 8, 1); int workFactor = result.getPrototype().getWorkFactor(); // 32768 long realElapsed = result.getElapsed() // 218 ``` -------------------------------- ### ScryptFunction.getInstanceFromHash(String) Source: https://github.com/password4j/password4j/wiki/Scrypt Creates a ScryptFunction singleton instance from an existing hash, since all the parameters required are stored into it. This method allows recovery of scrypt parameters from a previously generated hash. ```APIDOC ## ScryptFunction.getInstanceFromHash(String) ### Description Creates a ScryptFunction singleton instance from an existing hash, since all the parameters required are stored into it. This method allows recovery of scrypt parameters from a previously generated hash. ### Method ScryptFunction.getInstanceFromHash(String) ### Parameters - **hash** (String) - Required - The hash string containing the scrypt parameters. ### Request Example ```java String hashed = "$s0$e0801$c2FsdA==$dFcxr0SE8yOWiWntoomu7gBbWQOsVh5kpayhIXl793NO+f1YQi4uIhg7ysup7Ie6DIO3oueI8Dzg2gZGNDPNpg=="; ScryptFunction scrypt = ScryptFunction.getInstanceFromHash(hashed); ``` ``` -------------------------------- ### AlgorithmFinder.getArgon2Instance() Source: https://github.com/password4j/password4j/wiki/Argon2 Retrieves an Argon2Function singleton instance configured from parameters defined in the `psw4j.properties` file. This is used when Argon2 parameters are set via configuration properties. ```APIDOC ## AlgorithmFinder.getArgon2Instance() ### Description Retrieves an Argon2Function singleton instance configured from parameters defined in the `psw4j.properties` file. This is used when Argon2 parameters are set via configuration properties. ### Method `getArgon2Instance` ### Parameters None. ### Request Example ```java Argon2Function argon2 = AlgorithmFinder.getArgon2Instance(); ``` ``` -------------------------------- ### Benchmark bcrypt rounds with SystemChecker.benchmarkBcrypt Source: https://github.com/password4j/password4j/wiki/Recommended-settings Use when your application requires a specific hashing time (n milliseconds) and you need to determine the bcrypt logarithmic rounds. The result's prototype gives the rounds; the elapsed time is in milliseconds. ```java long n = 300; BenchmarkResult result = SystemChecker.benchmarkBcrypt(n); int rounds = result.getPrototype().getLogarithmicRounds(); // 12 long realElapsed = result.getElapsed() // 247 ``` -------------------------------- ### Argon2Function.getInstanceFromHash(String) Source: https://github.com/password4j/password4j/wiki/Argon2 Creates an Argon2Function singleton instance by extracting all required parameters from an existing Argon2 hash string. This is useful for verifying or reusing the same parameters as the original hash. ```APIDOC ## Argon2Function.getInstanceFromHash(String) ### Description Creates an Argon2Function singleton instance by extracting all required parameters from an existing Argon2 hash string. This is useful for verifying or reusing the same parameters as the original hash. ### Method `getInstanceFromHash` ### Parameters - **hash** (String) - Required - The Argon2 hash string containing the parameters (e.g., `$argon2id$v=19$m=1024,t=3,p=12$...`). ### Request Example ```java String hashed = "$argon2id$v=19$m=1024,t=3,p=12$MzMzMzMzMzM$DXUE5N4lm4plldg9nGMq+tYsbGhko8HWpPaADujpgFQ"; Argon2Function argon2 = Argon2Function.getInstanceFromHash(hashed); ``` ``` -------------------------------- ### Create BcryptFunction from an existing hash Source: https://github.com/password4j/password4j/wiki/BCrypt Creates a BcryptFunction singleton instance from a bcrypt hash string, extracting all required parameters (version and cost factor) from the hash itself. ```java String hashed = "$2y$06$9JujYcoWPmifvFA3RUP90e5rSEHAb5Ye6iv3.G9ikiHNv5cxjNEse"; BcryptFunction bcrypt = BcryptFunction.getInstanceFromHash(hashed); ``` -------------------------------- ### Verify Scrypt hash with default parameters Source: https://github.com/password4j/password4j/wiki/Scrypt Checks a user-provided password against a hash retrieved from the database. The salt is encoded within the hash, and parameters are taken from the psw4j.properties file. ```java String hashFromDB = getHashFromDatabase(user); boolean verified = Password.check(userProvidedPassword, hashFromDB).withScrypt(); ``` -------------------------------- ### Add pepper from properties file to PBKDF2 hash Source: https://github.com/password4j/password4j/wiki/PBKDF2 Uses addPepper() to read the pepper from the psw4j.properties file at the property global.pepper. ```java Hash hash = Password.hash(plainTextPassword).addPepper().withPBKDF2(); ``` -------------------------------- ### Check password with dot-notation Source: https://github.com/password4j/password4j/wiki/Statements Build a check statement using Password.check(hash, password) and chain optional salt/pepper and checking function calls. Choose none or one of the salt/pepper options and one of the withXXX() or with(function) options. Replace withXXX() with withPBKDF2(), withCompressedPBKDF2(), withBCrypt(), withSCrypt(), withArgon2(), or legacy withMessageDigest(). ```java boolean verified = Password.check(hash, password) // choose none or one of the following to: .addSalt(customSalt) // add a user-defined salt .addRandomSalt(length) // a random salt with a user-defined length .addRandomSalt() // a random salt of 64 bytes // choose none or one of the following to: .addPepper(customPepper) // add a user-defined pepper .addPepper() // add the pepper defined in psw4j.properties file // choose one of the following to: .withXXX() // check with a function defined in the psw4j.properties file .with(function); // check with a user-defined function ``` -------------------------------- ### Verify password with bcrypt using default parameters Source: https://github.com/password4j/password4j/wiki/BCrypt Checks a user-provided password against a hash retrieved from the database. Uses default parameters from psw4j.properties. The salt is encoded within the hash. ```java String hashFromDB = getHashFromDatabase(user); boolean verified = Password.check(userProvidedPassword, hashFromDB).withBcrypt(); ``` -------------------------------- ### Check PBKDF2 hash with default parameters Source: https://github.com/password4j/password4j/wiki/PBKDF2 Verifies a user-provided password against a stored hash and salt using the PBKDF2 function with parameters from the psw4j.properties file. ```java String hashFromDB = getHashFromDatabase(user); String saltFromDB = getSaltFromDatabase(user); boolean verified = Password.check(userProvidedPassword, hashFromDB).addSalt(saltFromDB).withPBKDF2(); ``` -------------------------------- ### BCryptFunction.getInstanceFromHash(String) Source: https://github.com/password4j/password4j/wiki/BCrypt Creates a BcryptFunction singleton instance from an existing bcrypt hash, extracting the version and cost factor from the hash. This is used to configure a bcrypt function based on a previously generated hash. ```APIDOC ## BCryptFunction.getInstanceFromHash(String) ### Description Creates a BcryptFunction singleton instance from an existing bcrypt hash, extracting the version and cost factor from the hash. This is used to configure a bcrypt function based on a previously generated hash. ### Method `getInstanceFromHash` ### Parameters - **String** (String) - Required - The bcrypt hash string ### Return Value - **BcryptFunction** - A singleton instance of BcryptFunction ### Request Example ```java String hashed = "$2y$06$9JujYcoWPmifvFA3RUP90e5rSEHAb5Ye6iv3.G9ikiHNv5cxjNEse"; BcryptFunction bcrypt = BcryptFunction.getInstanceFromHash(hashed); ``` ``` -------------------------------- ### Hash password with PBKDF2 using custom parameters Source: https://github.com/password4j/password4j/wiki/PBKDF2 Creates a PBKDF2Function with custom algorithm, iterations, and key length, then hashes with it. ```java PBKDF2Function myPbkdf2 = PBKDF2Function.getInstance("HAVAL", 2000, 128); Password.hash(plainTextPassword).with(myPbkdf2); ``` -------------------------------- ### Hash password with dot-notation Source: https://github.com/password4j/password4j/wiki/Statements Build a hash statement using Password.hash(password) and chain optional salt/pepper and hashing function calls. Choose none or one of the salt/pepper options and one of the withXXX() or with(function) options. Replace withXXX() with withPBKDF2(), withCompressedPBKDF2(), withBCrypt(), withSCrypt(), withArgon2(), or legacy withMessageDigest(). ```java Hash hash = Password.hash(password) // choose none or one of the following to: .addSalt(customSalt) // add a user-defined salt .addRandomSalt(length) // a random salt with a user-defined length .addRandomSalt() // a random salt of 64 bytes // choose none or one of the following to: .addPepper(customPepper) // add a user-defined pepper .addPepper() // add the pepper defined in psw4j.properties file // choose one of the following to: .withXXX() // hash with a function defined in the psw4j.properties file (replace XXX with the name of the function) .with(function); // hash with a user-defined function ``` -------------------------------- ### Hash password with scrypt using default parameters Source: https://github.com/password4j/password4j/wiki/Scrypt Uses parameters from psw4j.properties (like AlgorithmFinder.getScryptInstance()). The result is a Hash object; getResult() returns the hash string. ```java Hash hash = Password.hash(plainTextPassword).withScrypt(); hash.getResult(); // $s0$e0801$c2FsdA==$dFcxr0SE8yOWiWntoomu7gBbWQOsVh5kpayhIXl793NO+f1YQi4uIhg7ysup7Ie6DIO3oueI8Dzg2gZGNDPNpg== ``` -------------------------------- ### Create ScryptFunction with custom parameters Source: https://github.com/password4j/password4j/wiki/Scrypt Creates a singleton ScryptFunction instance with a work factor of 16384 (2^14), 8-byte memory blocks, parallelisation cost of 2, and a derived key length of 128 bytes. ```java ScryptFunction scrypt = ScryptFunction.getInstance(16384, 8, 2, 128); ``` -------------------------------- ### PBKDF2Function.getInstance(Hmac, int, int) Source: https://github.com/password4j/password4j/wiki/PBKDF2 Creates a singleton custom PBKDF2 function using an Hmac enum value. This method is used when the HMAC algorithm is supported by the Hmac enum. ```APIDOC ## PBKDF2Function.getInstance(Hmac, int, int) ### Description Creates a singleton custom PBKDF2 function using an Hmac enum value. This method is used when the HMAC algorithm is supported by the Hmac enum. ### Method `getInstance` ### Parameters - **algorithm** (Hmac) - Required - The HMAC algorithm from the Hmac enum. - **iterations** (int) - Required - The number of iterations. - **length** (int) - Required - The desired output length in bytes. ### Return Value - **PBKDF2Function** - A singleton instance of PBKDF2Function. ### Example ```java PBKDF2Function pbkdf2 = PBKDF2Function.getInstance(Hmac.SHA256, 100000, 1024); ``` ``` -------------------------------- ### Hash password with scrypt and pepper from properties Source: https://github.com/password4j/password4j/wiki/Scrypt Uses addPepper() to load the pepper from the global.pepper property in psw4j.properties. The pepper is always prepended. ```java Hash hash = Password.hash(plainTextPassword).addPepper().withScrypt(); ``` -------------------------------- ### Hash password with scrypt and default random salt Source: https://github.com/password4j/password4j/wiki/Scrypt Uses addRandomSalt() with no arguments to generate a random salt of 64 bytes. ```java Hash hash = Password.hash(plainTextPassword).addRandomSalt().withScrypt(); ``` -------------------------------- ### Hash password with pepper from properties file Source: https://github.com/password4j/password4j/wiki/Argon2 Uses addPepper() to read the pepper from the global.pepper property in psw4j.properties. ```java Hash hash = Password.hash(plainTextPassword).addPepper().withArgon2(); ``` -------------------------------- ### Password.check().andUpdate() Source: https://github.com/password4j/password4j/wiki/Statements Builds an update statement to verify a hash against a user password and hash the same password with a different configuration if the check passes. Supports adding new salt, pepper, and choosing the checking and hashing functions. ```APIDOC ## Password.check().andUpdate() ### Description Builds an update statement to verify a hash against a user password and hash the same password with a different configuration if the check passes. Supports adding new salt, pepper, and choosing the checking and hashing functions. ### Method check().andUpdate() ### Endpoint Password.check(hash, password).andUpdate() ### Parameters #### Path Parameters - **hash** (String) - Required - The hash to verify. - **password** (String) - Required - The user password to check. #### Optional Chaining Methods - **addNewSalt(customSalt)** - Adds a user-defined salt. - **addNewRandomSalt(length)** - Adds a random salt with a user-defined length. - **addNewRandomSalt()** - Adds a random salt of 64 bytes. If none chosen, the old salt is preserved. - **addNewPepper(customPepper)** - Adds a user-defined pepper. - **addNewPepper()** - Adds the pepper defined in psw4j.properties file. If none chosen, the old pepper is preserved. - **withXXX(function)** - Checks with a function defined in the psw4j.properties file and hashes with a user-defined function. - **with(oldF, newF)** - Checks with a user-defined function and hashes with a different user-defined function. ### Response #### Success Response Returns a HashUpdate object containing the updated hash. ### Request Example ```java HashUpdate update = Password.check(hash, password) .addNewSalt(customSalt) .addNewRandomSalt(length) .addNewRandomSalt() .addNewPepper(customPepper) .addNewPepper() .withXXX(function) .with(oldF, newF); ``` ``` -------------------------------- ### Define shared pepper Source: https://github.com/password4j/password4j/blob/master/README.md Sets a global pepper value in the configuration file. ```properties global.pepper=AlicePepper ``` -------------------------------- ### Verify Argon2 hash with default parameters Source: https://github.com/password4j/password4j/wiki/Argon2 Checks a user-provided password against a hash retrieved from a database using Argon2. The salt is encoded within the hash, and parameters are taken from the psw4j.properties file. ```java String hashFromDB = getHashFromDatabase(user); boolean verified = Password.check(userProvidedPassword, hashFromDB).withArgon2(); ``` -------------------------------- ### Switch from Scrypt to Argon2 during hash update Source: https://github.com/password4j/password4j/wiki/Scrypt Migrates hashes from Scrypt to Argon2 by providing both the old and new functions to the update. Uses AlgorithmFinder to retrieve the current Scrypt and Argon2 functions. ```java ScryptFunction oldFunction = AlgorithmFinder.getScryptFunction(); Argon2Function newFunction = AlgorithmFinder.getArgon2Function(); HashUpdate update = Password.check(userProvidedPassword, hashFromDB) .andUpdate() .addNewRandomSalt().with(oldFunction, newFunction); ``` -------------------------------- ### Password.check() Source: https://github.com/password4j/password4j/wiki/Statements Builds a check statement to verify a hash against a user password with any of the algorithms included in Password4j. Supports adding salt, pepper, and choosing the checking function. ```APIDOC ## Password.check() ### Description Builds a check statement to verify a hash against a user password with any of the algorithms included in Password4j. Supports adding salt, pepper, and choosing the checking function. ### Method check() ### Endpoint Password.check(hash, password) ### Parameters #### Path Parameters - **hash** (String) - Required - The hash to verify. - **password** (String) - Required - The user password to check. #### Optional Chaining Methods - **addSalt(customSalt)** - Adds a user-defined salt. - **addRandomSalt(length)** - Adds a random salt with a user-defined length. - **addRandomSalt()** - Adds a random salt of 64 bytes. - **addPepper(customPepper)** - Adds a user-defined pepper. - **addPepper()** - Adds the pepper defined in psw4j.properties file. - **withXXX()** - Checks with a function defined in the psw4j.properties file (replace XXX with the name of the function). - **with(function)** - Checks with a user-defined function. ### Response #### Success Response Returns a boolean indicating whether the hash matches the password. ### Request Example ```java boolean verified = Password.check(hash, password) .addSalt(customSalt) .addRandomSalt(length) .addRandomSalt() .addPepper(customPepper) .addPepper() .withXXX() .with(function); ``` ``` -------------------------------- ### Migrate from BCrypt to Argon2 with HashUpdate Source: https://github.com/password4j/password4j/wiki/BCrypt Switches a stored hash from an old BCrypt function to a new Argon2 function during login. Uses the andUpdate() flow with both old and new functions to generate a new hash with a new random salt, allowing migration to a more secure algorithm. ```java BcryptFunction oldFunction = BCryptFunction.getInstance(Bcrypt.A, 10); Argon2Function newFunction = AlgorithmFinder.getArgon2Function(); HashUpdate update = Password.check(userProvidedPassword, hashFromDB) .andUpdate() .addNewRandomSalt().with(oldFunction, newFunction); ``` -------------------------------- ### Hash password with bcrypt and pepper from properties Source: https://github.com/password4j/password4j/wiki/BCrypt Uses the pepper defined in the psw4j.properties file under the property global.pepper. The pepper is always prepended. ```java Hash hash = Password.hash(plainTextPassword).addPepper().withBCrypt(); ``` -------------------------------- ### Update hash with dot-notation Source: https://github.com/password4j/password4j/wiki/Statements Build an update statement using Password.check(hash, password) followed by .andUpdate() to re-hash the password with a new configuration if the check passes. Chain optional new salt/pepper and hashing function calls. Replace withXXX(function) with withPBKDF2(function), withCompressedPBKDF2(function), withBCrypt(function), withSCrypt(function), withArgon2(function), or legacy withMessageDigest(function). ```java HashUpdate update = Password.check(hash, password) ... // same as check() .andUpdate() // choose none or one of the following to: .addNewSalt(customSalt) // add a user-defined salt .addNewRandomSalt(length) // a random salt with a user-defined length .addNewRandomSalt() // a random salt of 64 bytes // if none has been chosen then the old salt is preserved // choose none or one of the following to: .addNewPepper(customPepper) // add a user-defined pepper .addNewPepper() // add the pepper defined in psw4j.properties file // if none has been chosen then the old pepper is preserved // choose one of the following to: .withXXX(function) // check with a function defined in the psw4j.properties file and hash with a user-defined function .with(oldF, newF); // check with a user-defined function and hash with a different user-defined function ``` -------------------------------- ### Password.hash() Source: https://github.com/password4j/password4j/wiki/Statements Builds a hash statement to produce a hash with any of the algorithms included in Password4j. Supports adding salt, pepper, and choosing the hashing function. ```APIDOC ## Password.hash() ### Description Builds a hash statement to produce a hash with any of the algorithms included in Password4j. Supports adding salt, pepper, and choosing the hashing function. ### Method hash() ### Endpoint Password.hash(password) ### Parameters #### Path Parameters - **password** (String) - Required - The password to hash. #### Optional Chaining Methods - **addSalt(customSalt)** - Adds a user-defined salt. - **addRandomSalt(length)** - Adds a random salt with a user-defined length. - **addRandomSalt()** - Adds a random salt of 64 bytes. - **addPepper(customPepper)** - Adds a user-defined pepper. - **addPepper()** - Adds the pepper defined in psw4j.properties file. - **withXXX()** - Hashes with a function defined in the psw4j.properties file (replace XXX with the name of the function). - **with(function)** - Hashes with a user-defined function. ### Response #### Success Response Returns a Hash object containing the generated hash. ### Request Example ```java Hash hash = Password.hash(password) .addSalt(customSalt) .addRandomSalt(length) .addRandomSalt() .addPepper(customPepper) .addPepper() .withXXX() .with(function); ``` ``` -------------------------------- ### Hash password with PBKDF2 using default parameters Source: https://github.com/password4j/password4j/wiki/PBKDF2 Uses parameters from psw4j.properties (like AlgorithmFinder.getPBKDF2Instance()). Returns a Hash object; getResult() gives the base64-encoded hash. ```java Hash hash = Password.hash(plainTextPassword).withPBKDF2(); hash.getResult(); // /WTQfTTc8Hg8GlplP0LthpgdElUG+I3MyuvK8MI4MnQ= ``` -------------------------------- ### Hash password with bcrypt using default parameters Source: https://github.com/password4j/password4j/wiki/BCrypt Uses the default bcrypt parameters from the psw4j.properties file. The result is a Hash object; getResult() returns the bcrypt hash string. ```java Hash hash = Password.hash(plainTextPassword).withBcrypt(); hash.getResult(); // $2b$10$LgfYWkbzEvQ4JakH7rOvHe0y8pHKF9OaFgwUZ2q7W2FFZmZzJYlfS ``` -------------------------------- ### Create BcryptFunction with custom version and cost factor Source: https://github.com/password4j/password4j/wiki/BCrypt Creates a singleton BcryptFunction instance using version 'y' and cost factor 11 (2^11 = 2048 rounds). Use this when you need to specify bcrypt parameters programmatically. ```java BcryptFunction bcrypt = BcryptFunction.getInstance(Bcrypt.Y, 11); ```