final class BaseCrypt (View source)

Provides bcrypt-compatible password hashing without truncating newly hashed long passwords.

Existing native bcrypt hashes remain verifiable. New passwords exceeding bcrypt's 72-byte input limit are salted, domain-separated, and pre-hashed before bcrypt is applied.

Constants

private ALGO

private COST

private BCRYPT_MAX_PASSWORD_BYTES

private LONG_PASSWORD_DOMAIN

Methods

static string

Returns a random 22-character fragment compatible with bcrypt salt encoding.

string
static string
generateRandomPassword(int $length = 16)

Returns a lowercase hexadecimal password of the requested length, normalized to at least one character.

string
static string
encPassword(string $password, int|null $cost = null)

Hashes a password with bcrypt using the supplied cost or the framework compatibility default.

string
static bool
checkHash(string $hash, string $password)

Verifies current long-password hashes and existing native bcrypt hashes, including $2a$ values.

bool
static bool
needsRehash(string $hash)

Reports whether a hash must be upgraded to the current bcrypt algorithm and cost.

bool

Details

getSalt

static string getSalt()

Returns a random 22-character fragment compatible with bcrypt salt encoding.

Return Value

string

Exceptions

RandomException
RuntimeException

generateRandomPassword

static string generateRandomPassword(int $length = 16)

Returns a lowercase hexadecimal password of the requested length, normalized to at least one character.

The operation fails closed instead of substituting a weaker source when secure randomness is unavailable.

Parameters

int $length

Return Value

string

Exceptions

RandomException

encPassword

static string encPassword(string $password, int|null $cost = null)

Hashes a password with bcrypt using the supplied cost or the framework compatibility default.

Inputs longer than bcrypt's 72-byte limit, or containing a NUL byte, are first reduced to a salted, domain-separated SHA-384 value encoded as 64 ASCII characters. Short-password hashes retain the existing native bcrypt behavior and format.

Parameters

string $password
int|null $cost

Return Value

string

Exceptions

ValueError
RuntimeException

checkHash

static bool checkHash(string $hash, string $password)

Verifies current long-password hashes and existing native bcrypt hashes, including $2a$ values.

For passwords over 72 bytes, legacy direct bcrypt verification is attempted before the long-password representation so existing hashes remain valid.

Parameters

string $hash
string $password

Return Value

bool

needsRehash

static bool needsRehash(string $hash)

Reports whether a hash must be upgraded to the current bcrypt algorithm and cost.

Native bcrypt hashes do not encode whether their original input exceeded 72 bytes, so this method cannot identify legacy truncation and password reset remains the migration boundary for such hashes.

Parameters

string $hash

Return Value

bool