Page MenuHomeClusterLabs Projects
Diviner Tech Docs PhabricatorPasswordHasher

abstract class PhabricatorPasswordHasher
Phorge Technical Documentation ()

Provides a mechanism for hashing passwords, like "iterated md5", "bcrypt", "scrypt", etc.

Hashers define suitability and strength, and the system automatically chooses the strongest available hasher and can prompt users to upgrade as soon as a stronger hasher is available.

Tasks

Implementing a Hasher

  • abstract public function getHumanReadableName() — Return a human-readable description of this hasher, like "Iterated MD5".
  • abstract public function getHashName() — Return a short, unique, key identifying this hasher, like "md5" or "bcrypt". This identifier should not be translated.
  • abstract public function getHashLength() — Return the maximum byte length of hashes produced by this hasher. This is used to prevent storage overflows.
  • abstract public function canHashPasswords() — Return `true` to indicate that any required extensions or dependencies are available, and this hasher is able to perform hashing.
  • abstract public function getInstallInstructions() — Return a human-readable string describing why this hasher is unable to operate. For example, "To use bcrypt, upgrade to PHP 5.5.0 or newer.".
  • abstract public function getStrength() — Return an indicator of this hasher's strength. When choosing to hash new passwords, the strongest available hasher which is usable for new passwords will be used, and the presence of a stronger hasher will prompt users to update their hashes.
  • abstract public function getHumanReadableStrength() — Return a short human-readable indicator of this hasher's strength, like "Weak", "Okay", or "Good".
  • abstract protected function getPasswordHash($envelope) — Produce a password hash.
  • protected function verifyPassword($password, $hash) — Verify that a password matches a hash.
  • protected function canUpgradeInternalHash($hash) — Check if an existing hash created by this algorithm is upgradeable.

Using Hashers

  • final public function getPasswordHashForStorage($envelope) — Get the hash of a password for storage.
  • private static function parseHashFromStorage($hash) — Parse a storage hash into its components, like the hash type and hash data.
  • public static function getAllHashers() — Get all available password hashers. This may include hashers which can not actually be used (for example, a required extension is missing).
  • public static function getAllUsableHashers() — Get all usable password hashers. This may include hashers which are not desirable or advisable.
  • public static function getBestHasher() — Get the best (strongest) available hasher.
  • public static function getHasherForHash($hash) — Get the hasher for a given stored hash.
  • public static function canUpgradeHash($hash) — Test if a password is using an weaker hash than the strongest available hash. This can be used to prompt users to upgrade, or automatically upgrade on login.
  • public static function generateNewPasswordHash($password) — Generate a new hash for a password, using the best available hasher.
  • public static function comparePassword($password, $hash) — Compare a password to a stored hash.

Other Methods

  • public static function getCurrentAlgorithmName($hash) — Get the human-readable algorithm name for a given hash.
  • public static function getBestAlgorithmName() — Get the human-readable algorithm name for the best available hash.

Methods

abstract public function getHumanReadableName()

Return a human-readable description of this hasher, like "Iterated MD5".

Return
stringHuman readable hash name.

abstract public function getHashName()

Return a short, unique, key identifying this hasher, like "md5" or "bcrypt". This identifier should not be translated.

Return
stringShort, unique hash name.

abstract public function getHashLength()

Return the maximum byte length of hashes produced by this hasher. This is used to prevent storage overflows.

Return
intMaximum number of bytes in hashes this class produces.

abstract public function canHashPasswords()

Return true to indicate that any required extensions or dependencies are available, and this hasher is able to perform hashing.

Return
boolTrue if this hasher can execute.

abstract public function getInstallInstructions()

Return a human-readable string describing why this hasher is unable to operate. For example, "To use bcrypt, upgrade to PHP 5.5.0 or newer.".

Return
stringHuman-readable description of how to enable this hasher.

abstract public function getStrength()

Return an indicator of this hasher's strength. When choosing to hash new passwords, the strongest available hasher which is usable for new passwords will be used, and the presence of a stronger hasher will prompt users to update their hashes.

Generally, this method should return a larger number than hashers it is preferable to, but a smaller number than hashers which are better than it is. This number does not need to correspond directly with the actual hash strength.

Return
floatStrength of this hasher.

abstract public function getHumanReadableStrength()

Return a short human-readable indicator of this hasher's strength, like "Weak", "Okay", or "Good".

This is only used to help administrators make decisions about configuration.

Return
stringShort human-readable description of hash strength.

abstract protected function getPasswordHash($envelope)

Produce a password hash.

Parameters
PhutilOpaqueEnvelope$envelopeText to be hashed.
Return
PhutilOpaqueEnvelopeHashed text.

protected function verifyPassword($password, $hash)

Verify that a password matches a hash.

The default implementation checks for equality; if a hasher embeds salt in hashes it should override this method and perform a salt-aware comparison.

Parameters
PhutilOpaqueEnvelope$passwordPassword to compare.
PhutilOpaqueEnvelope$hashBare password hash.
Return
boolTrue if the passwords match.

protected function canUpgradeInternalHash($hash)

Check if an existing hash created by this algorithm is upgradeable.

The default implementation returns false. However, hash algorithms which have (for example) an internal cost function may be able to upgrade an existing hash to a stronger one with a higher cost.

Parameters
PhutilOpaqueEnvelope$hashBare hash.
Return
boolTrue if the hash can be upgraded without changing the algorithm (for example, to a higher cost).

final public function getPasswordHashForStorage($envelope)

Get the hash of a password for storage.

Parameters
PhutilOpaqueEnvelope$envelopePassword text.
Return
PhutilOpaqueEnvelopeHashed text.

private static function parseHashFromStorage($hash)

Parse a storage hash into its components, like the hash type and hash data.

Parameters
PhutilOpaqueEnvelope$hash
Return
mapDictionary of information about the hash.

public static function getAllHashers()

Get all available password hashers. This may include hashers which can not actually be used (for example, a required extension is missing).

Return
list<PhabricatorPasswordHasher>Hasher objects.

public static function getAllUsableHashers()

Get all usable password hashers. This may include hashers which are not desirable or advisable.

Return
list<PhabricatorPasswordHasher>Hasher objects.

public static function getBestHasher()

Get the best (strongest) available hasher.

Return
PhabricatorPasswordHasherBest hasher.

public static function getHasherForHash($hash)

Get the hasher for a given stored hash.

Parameters
PhutilOpaqueEnvelope$hash
Return
PhabricatorPasswordHasherCorresponding hasher.

public static function canUpgradeHash($hash)

Test if a password is using an weaker hash than the strongest available hash. This can be used to prompt users to upgrade, or automatically upgrade on login.

Parameters
PhutilOpaqueEnvelope$hash
Return
boolTrue to indicate that rehashing this password will improve the hash strength.

public static function generateNewPasswordHash($password)

Generate a new hash for a password, using the best available hasher.

Parameters
PhutilOpaqueEnvelope$passwordPassword to hash.
Return
PhutilOpaqueEnvelopeHashed password, using best available hasher.

public static function comparePassword($password, $hash)

Compare a password to a stored hash.

Parameters
PhutilOpaqueEnvelope$passwordPassword to compare.
PhutilOpaqueEnvelope$hashStored password hash.
Return
boolTrue if the passwords match.

public static function getCurrentAlgorithmName($hash)

Get the human-readable algorithm name for a given hash.

Parameters
PhutilOpaqueEnvelope$hashStorage hash.
Return
stringHuman-readable algorithm name.

public static function getBestAlgorithmName()

Get the human-readable algorithm name for the best available hash.

Return
stringHuman-readable name for best hash.
Defined
src/infrastructure/util/password/PhabricatorPasswordHasher.php:14