Password authentication for web and mobile apps (e-book)

Portable PHP password hashing framework

Please note that password hashing is often wrongly referred to as "password encryption". Hashing is a more appropriate term since encryption is something that is supposed to be easily reversible.

phpass (pronounced "pH pass") is a portable public domain password hashing framework for use in PHP applications.

phpass was released in 2005 when a typical web host ran PHP 4 and a typical web app used raw MD5. In 2007 and on major web apps moved to phpass, which was an important step forward (bringing web apps' password hashing on par with Unix systems'). phpass API might also have inspired the password_hash() / password_verify() API included in PHP 5.5+.

At this time, if your new project can afford to require PHP 5.5+, which it should, please use PHP's native password_hash() / password_verify() API instead of phpass. This new API also happens to support the CRYPT_BLOWFISH and CRYPT_EXT_DES hashes used by phpass, but unfortunately it does not support the phpass portable hashes (which are portable across all versions of PHP as long as you use phpass).

If you have to support versions of PHP older than 5.5, if you need to keep support for phpass portable hashes in new revisions of your existing project, or/and if you need to support those hashes migrated from other web apps, then phpass is still useful for you. This is why we continue to keep its maintenance on life support and have updated phpass for PHP 7+.

The preferred (most secure) hashing method supported by phpass is the OpenBSD-style Blowfish-based bcrypt, also supported with our public domain crypt_blowfish package (for C applications), and known in PHP as CRYPT_BLOWFISH, with a fallback to MD5-based salted and variable iteration count password hashes implemented in phpass itself (also referred to as portable hashes). (phpass versions up to 0.4 also included an intermediary fallback to BSDI-style extended DES-based hashes, known in PHP as CRYPT_EXT_DES, but this has since been dropped except for authenticating against pre-existing hashes of this type.)

To ensure that the fallbacks will never occur, PHP 5.3+ should be used.

Included in the package are a PHP source file implementing the PasswordHash PHP class, a tiny PHP application demonstrating the use of the PasswordHash class, and a C reimplementation of the portable hashes (used for testing correctness of the primary implementation only).

There's a lengthy article/tutorial on introducing password hashing with phpass into a PHP application, as well as on other aspects of managing users and passwords. This article along with sample programs referenced from it is also available for download below. Some of you might prefer this much shorter third-party article focusing solely on introducing phpass into a PHP application. Finally, also relevant is our presentation on the history of password security.

Download (release notes):

These and other related files are also available from the Openwall file archive. The source code of phpass can be browsed on GitHub or via CVSweb.

Follow this link for information on verifying the signatures.

We can help you integrate phpass into your applications, please check out our services.

Contributed resources:

phpass has been integrated into WordPress 2.5+ (more info), bbPress, Vanilla, PivotX 2.1.0+, Textpattern 4.4.0+, and concrete5 5.6.3+.

A cut-down version of phpass (supporting the portable hashes only) has been integrated into phpBB3 (although they have changed the hash type identifier string from "$P$" to "$H$", the hashes are otherwise compatible with those of genuine phpass).

Similarly, phpass forced to use the portable hashes only has been integrated into Joomla starting with versions 2.5.18 and 3.2.1.

A cut-down and reworked version of phpass (supporting the portable hashes only and requiring PHP 5+) has been integrated into development versions of Drupal leading to the Drupal 7 release, after a lengthy discussion and many proposed patches against various development versions of Drupal. There's a notion of upgraded hashes - these are phpass portable hashes of md5() hashes (which were used by older versions of Drupal), with the final hash encodings prefixed with a "U" (for "upgraded"). A more recent lengthy discussion has resulted in Drupal 7 switching from MD5 to SHA-512 for the underlying cryptographic primitive in phpass' "portable" hashes (making them less portable) while preserving "read-only" support for the MD5-based portable hashes. This change was made primarily for "political" reasons. Drupal 7's SHA-512 based phpass-like hash encoding strings use "$S$" as the hash type identifier.

There's also a module for Drupal 5 & 6 that makes the original phpass available with those versions of Drupal, including support for the more secure but not nearly as portable CRYPT_BLOWFISH and CRYPT_EXT_DES hashes.

TYPO3 CMS supports phpass portable hashes and was using them by default since version 4.5 and until the default was changed in version 8.

A revision of phpass modified to use SHA-1 in the portable hashes, with the "$Q$" prefix to distinguish those, has been integrated into Escher CMS 0.9.2. This is an example of a project breaking compatibility for no good reason. Please don't do things like that!

phpass is a registered project with Open Hub.

The development of phpass and efforts on getting it into Drupal are partially supported by CivicActions, a Drupal consulting company.

Quick Comment: