at.favre.lib.crypto.bkdf

Interface PasswordHashUpgrader

All Known Implementing Classes:

PasswordHashUpgrader.Default

public interface PasswordHashUpgrader

Component responsible for upgrading the strength of BKDF password hashes.

Unfortunately it is not easily possible to upgrade the strength of a bcrypt hash WITHOUT the knowledge of the user password. There are usually 2 approaches:

• Recompute the hash when the user signs in next time
• Recompute all hashes offline at once

The disadvantage of the first approach is that the weak hashes remain in the DB until a user logs in again, which may be days, weeks or never.

This class introduces an easy way to to support the second approach by providing a defined protocol and data format for hash upgrading by chaining bcrypt hashes.

See - https://security.stackexchange.com/questions/15847/is-it-possible-to-increase-the-cost-of-bcrypt-or-pbkdf2-when-its-already-calcula - https://crypto.stackexchange.com/questions/3003/do-i-have-to-recompute-all-hashes-if-i-change-the-work-factor-in-bcrypt

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	PasswordHashUpgrader.Default Default implementation

Field Summary

Fields

Modifier and Type	Field and Description
static byte	COMPOUND_FORMAT_VERSION The current version identifier for the compound hash data format (see CompoundHashData)

Method Summary

Modifier and Type	Method and Description
boolean	isCompoundHashMessage(String bkdfPasswordHashFormat2) Efficently checks a base64 string if it is in compound hash data format.
CompoundHashData	upgradePasswordHashTo(int costFactor, String bkdfPasswordHashFormat2) Upgrades the given hash to the given new cost factor.
CompoundHashData	upgradePasswordHashWith(Version version, int costFactor, String bkdfPasswordHashFormat2) Upgrades the given hash with the given new hash config (ie.
boolean	verifyCompoundHash(char[] password, String bkdfPasswordHashFormat2) Verify a hash in compound format.

Field Detail

COMPOUND_FORMAT_VERSION

static final byte COMPOUND_FORMAT_VERSION

The current version identifier for the compound hash data format (see CompoundHashData)

See Also:

Constant Field Values

Method Detail

upgradePasswordHashWith

CompoundHashData upgradePasswordHashWith(Version version,
                                         int costFactor,
                                         String bkdfPasswordHashFormat2)

Upgrades the given hash with the given new hash config (ie. version and cost factor).

This will chain the current hash with given hash exactly as defined by the the input paramters. E.g. if the current hash is [(VERSION_1, 4)] and the the following will be passed: (VERSION_2, 10), the resulting hash config is [(VERSION_1, 4), (VERSION_2, 10)].

Parameters:

version - of the BKDF password hash to be used

costFactor - to be used on the current hash

bkdfPasswordHashFormat2 - the current hash. Can be in compound or normal password hash format

Returns:

upgraded hash data

upgradePasswordHashTo

CompoundHashData upgradePasswordHashTo(int costFactor,
                                       String bkdfPasswordHashFormat2)

Upgrades the given hash to the given new cost factor.

This will chain the current hash with possibly multiple hash configs to achieve the new final cost factor. E.g. if current cost-factor is 5 and new cost-factor should be 7, the following sequence of hashes will be applied: 5 + [5, 6]. Note that cost-factor is seen as 2^cost-factor therefore 5 equals 32 iterations and 7, 128 iterations.

Parameters:

costFactor - to be the new final cost factor

bkdfPasswordHashFormat2 - the current hash. Can be in compound or normal password hash format

Returns:

upgraded hash data

verifyCompoundHash

boolean verifyCompoundHash(char[] password,
                           String bkdfPasswordHashFormat2)

Verify a hash in compound format.

See also CompoundHashData and PasswordHashVerifier.verify(char[], HashData).

Parameters:

password - to verify against

bkdfPasswordHashFormat2 - containing the hash data

Returns:

true iff bcrypt hash in bkdfPasswordHashFormat2 can be computed with given user password

isCompoundHashMessage

boolean isCompoundHashMessage(String bkdfPasswordHashFormat2)

Efficently checks a base64 string if it is in compound hash data format.

See COMPOUND_FORMAT_VERSION and CompoundHashData

Parameters:

bkdfPasswordHashFormat2 - to possible be in compound hash format

Returns:

iff given data has the version identifier of a compound format