PHPass-compatibility library. Useful for comparing hashes generated by PHPass (e.g. WordPress, phpBB3, etc).
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Benjamin Shelton 258aaec795 Clarified timing attack comments. 2 months ago
LICENSE Added NCSA license. 2 months ago Clarified timing attack comments. 2 months ago
go.mod Function/namespace renames. 2 months ago
password.go Flipped "portable" semantics. 2 months ago
password_public_test.go Function/namespace renames. 2 months ago
password_test.go Function/namespace renames. 2 months ago

PHPass-compatiblity library (for Golang)

This is a compatibility library that provides a partial implementation of the PHPass API alongside an ability to compare hashes generated for downstream consumers including WordPress and phpBB3.

This library does not provide a public API for generating these same hashes.

PHPass exposes methods for generating bcrypt-backed hashes via the portability flag in the PasswordHash() constructor, but software like WordPress disable this feature for compatibility with older versions of PHP. When enabled, portable hashes force the use of MD5 internally via multiple iterations (512, depending on PHP version) which, while stronger than a plainly salted and MD5-hashed password, is of dubious utility given the present alternatives (bcrypt, scrypt, and now argon2) that seek to mitigate certain classes of attack. There is some question whether multiple rounds of MD5 are secure.

At present, this library only supports portable hashes since they're currently the most common use case of PHPass as most other PHP frameworks target modern APIs provided by the PHP runtime.

Be aware that the original PHPass implementation's password comparison method (PasswordHash::CheckPassword) is susceptible to timing attacks when fed hashes that may not match the expected length. That deficiency is corrected in this library, but this implementation should not be relied upon for security. It should only be used for interoperability. In all likelihood the authors only do a direct comparison under the principle that hashes fed into the CheckPassword method will be of identical lengths. Perhaps there's some truth in this, and it's unlikely end users will upgrade their password hashing at any point during an application's life cycle, but typically it's a better option to safely compare hashes regardless of what your own expectations are for whatever input you're given versus what you have stored. Paranoia? Sure. I'll take it.


Usage of this library is highlighted in the public unit tests, but as a brief overview, it is currently possible to use WordPress-compatible (and others) portable hashes via:

hashed := "$P$B./2E./2EZ46b/9PwepKVX68nmPjwy0"
comparer := &phpass.PHPass{}
if comp.CheckPassword("this is a test", hashed) {
    // Do something if the password matches the hash...

Eventually, non-portable hashes will be supported, and it will be possible to toggle them via the NewPHPass constructor:

hashed := "...some hash..."
comparer := phpass.NewPHPass(true)
if comp.CheckPassword("this is a test", hashed) {
    // Do something if the password matches the hash...

It is advisable that this library be used only temporarily. Upon authenticating users, you should consider one of the following options (in order of ideal to least ideal):

  • Force users to change their passwords, particularly if using PHPass-compatible portable hashes, upon successful authentication.
  • Dynamically upgrade to a new hash after successful authentication using the user's existing password instead.
  • Some combination of the above but through hashing the original portable hash with a newer algorithm (e.g. argon2) and using this library to generate the intermediate PHPass-compatible hash.


The original PHPass implementation was placed into the public domain. This library is covered under the NCSA license (see LICENSE). Core components of the code, where possible, are based on a nearly 1-to-1 translation of the original sources written by Solar Designer .