Release History

Upcoming in 1.7


The upcoming Passlib 1.7 will make a number of backwards incompatible changes:

  • It will require Python 2.6 / 3.2 or newer; dropping support for Python 2.5, 3.0, 3.1
  • The passlib.ext.django extension will require Django 1.6 or newer; dropping support for Django 1.5 and earlier.
  • New hashes generated by HtpasswdFile will use the strongest algorithm available on the host, rather than one that is guaranteed to be portable. Applications can explicitly set default_scheme="portable" to retain the old behavior (new in Passlib 1.6.3).

1.6.5 (2015-08-04)

Fixed some minor bugs in the test suite which were causing erroneous test failures (issue 57 and issue 58). The passlib library itself is unchanged.

1.6.4 (2015-07-25)

This release rolls up assorted bug & compatibility fixes since 1.6.2.


  • Correctly detect bcrypt 2.0. Previous releases were incorrectly detecting it as py-bcrypt, causing spurious errors (issue 56).
  • CryptContext now accepts scheme names as unicode (issue 54).
  • passlib.ext.django now works correctly with Django 1.7-1.8. Previous releases had various test failures (issue 52).
  • passlib.apache.HtpasswdFile now recognizes bcrypt, sha256_crypt, sha512_crypt hashes (issue 55).

BCrypt Changes

A few changes have been made to the bcrypt hash:

  • It now supports the $2b$ hash format.
  • It will now issue a PasslibSecurityWarning if the active backend is vulnerable to the wraparound bug, and automatically enable a workaround (py-bcrypt is known to be vulnerable as of v0.4).
  • It will throw a PasslibSecurityError if the active backend is vulnerable to the 8-bit bug (none of Passlib’s backends are known to be vulnerable as of 2015-07).
  • Updated documentation to indicate the cffi-based bcrypt library is now the recommended bcrypt backend.
  • Backend capability detection code refactored to rely on runtime detection rather than hardcoded information.

Other Changes

  • Source repo’s tox.ini updated. Now assumes python3 by default, and refactored test environments to more cleanly delineate the different setups being tested.
  • Passlib releases are now published as wheels instead of eggs.


Release 1.6.3 was skipped due to upload issues.

1.6.2 (2013-12-26)

Minor changes & compatibility fixes

  • Re-tuned the default_rounds values for all of the hashes.
  • Added the new bcrypt_sha256 hash, which wraps BCrypt using SHA256 in order to work around BCrypt’s password size limitations (issue 43).
  • passlib.hash.bcrypt: Added support for the bcrypt library as one of the possible bcrypt backends that will be used if available. (issue 49)
  • passlib.ext.django: Passlib’s Django extension (and it’s related hashes and unittests) have been updated to handle some minor API changes in Django 1.5-1.6. They should now be compatible with Django 1.2 and up. (issue 50)

1.6.1 (2012-08-02)

Minor bugfix release

  • bugfix: Various CryptContext methods would incorrectly raise TypeError if passed a unicode user category under Python 2. For consistency, unicode user category values are now encoded to utf-8 bytes under Python 2.

  • bugfix: Reworked internals of the CryptContext config compiler to fix a couple of border cases (issue 39):

    • It will now throw a ValueError if the default scheme is marked as deprecated.
    • If no default scheme is specified, it will use the first non-deprecated scheme.
    • Finally, it will now throw a ValueError if all schemes are marked as deprecated.
  • bugfix: FreeBSD 8.3 added native support for sha256_crypt – updated Passlib’s unittests and documentation accordingly (issue 35).

  • bugfix: Fixed bug which caused some passlib.apache unittests to fail if mtime resolution >= 1 second (issue 35).

  • bugfix: Fixed minor bug in passlib.registry, should now work correctly under Python 3.3.

  • Various documentation updates and corrections.

1.6 (2012-05-01)


Welcome to Passlib 1.6.

The main goal of this release was to clean up the codebase, tighten input validation, and simplify the publically exposed interfaces. This release also brings a number of other improvements: 10 or so new hash algorithms, additional security precautions for the existing algorithms, a number of speed improvements, and updated documentation.

Deprecated APIs

In order to improve the publically exposed interface, some of the more cumbersome and less-used functions in Passlib have been deprecated / renamed. This should not affect 99% of applications. That said, all the deprecated interfaces are still present, and will continue to be supported for at least one more major release. To help with migration, all deprecated functions should issue an informative DeprecationWarning when they are invoked, detailing their suggested replacement. The following interfaces have changed:

  • The semi-internal CryptPolicy class has been deprecated in its entirety. All functionality has been rolled into the parent CryptContext class (see below for more).
  • The interface of the passlib.apache classes has been improved: some confusing methods and options have been renamed, some new constructors and other functions have been added.
  • The (undocumented) passlib.win32 module has been deprecated, all of its functionality is now offered through the lmhash and nthash algorithms.

New Hashes

The release adds support for a number of hash algorithms:

cisco_pix, cisco_type7
Two hash formats frequently found on various Cisco devices (for Cisco Type 5 hashes, see md5_crypt ).
django_pbkdf2_sha256, django_pbkdf2_sha1, django_bcrypt
All three of the new hash schemes introduced in Django 1.4.
lmhash, nthash
Microsoft’s legacy “Lan Manager” hash, and the replacement NT password hash. (the old nthash algorithm in Passlib 1.5 has been renamed to bsd_nthash , to reflect its lineage).
msdcc, msdcc2
Microsoft Windows’ Domain Cached Credentials, versions 1 and 2. These algorithms also go by the names “DCC”, “MSCache”, and “MSCash”.
mssql2000, mssql2005
Hash algorithms used by MS SQL Server 2000 and later.
A hash format added specifically for storing the complex digest information needed to authenticate a user via the SCRAM protocol (RFC 5802). It can also be used in the same way as any other password hash in Passlib.

Existing Hashes

Additionally, the following new features have been added to the existing hashes:

Password Size Limit

All hashes in Passlib will now throw PasswordSizeError if handed a password that’s larger than 4096 characters.

This limit should be larger than any reasonable password size, and prevents various things including DOS abuses, and exploitation of OSes with a buggy crypt() implementation. See PasswordSizeError for how to change this limit.

Constant Time Comparison

All hash comparisons in Passlib now use the “constant time” [1] comparison function consteq(), instead of ==.

This change is motivated a well-known hmac timing attack which exploits short-circuit string comparisons. While this attack is not currently feasible against most password hashes, some of the weaker unsalted hashes supported by Passlib may be vulnerable; and this change has been made preventatively to all of them.

[1]“constant time” is a misnomer, it actually takes THETA(len(righthand_value)) time.
Strict Parameters

Previous releases of Passlib would silently correct any invalid values (such as rounds parameters that were out of range). This is was deemed undesirable, as it leaves developers unaware they are requesting an incorrect (and potentially insecure) value.

Starting with this release, providing invalid values to PasswordHash.encrypt will result in a ValueError. However, most hashes now accept an optional relaxed=True keyword, which causes Passlib to try and correct invalid values, and if successful, issue a PasslibHashWarning instead. These warnings can then be filtered if desired.


The BCrypt hash now supports the crypt_blowfish project’s $2y$ hash prefix.

On an unrelated note, Passlib now offers an (experimental) pure-python implementation of BCrypt. Unfortunately, it’s still WAY too slow to be suitable for production use; and is disabled by default. If you really need it, see the BCrypt documentation for how to enable it.

BSDi-Crypt will now issue a PasslibSecurityWarning if an application requests an even number of rounds, due to a known weakness in DES. Existing hashes with an even number of rounds will now be flagged by CryptContext.needs_update().
The LDAP salted digests now support salts of any size from 4-16 bytes, though they still default to 4 (issue 30).
md5_crypt, sha256_crypt, sha512_crypt
The builtin implementation of these hashes has been sped up by about 25%, using an additional pre-computation step.

The unix_fallback handler has been deprecated, and will be removed in Passlib 1.8. Applications should use the stricter-but-equivalent unix_disabled handler instead.

This most likely only affects internal Passlib code.


The CryptContext class has had a thorough internal overhaul. While the primary interface has not changed at all, the internals are much stricter about input validation, common methods have shorter code-paths, and the construction and introspection of CryptContext objects has been greatly simplified. Changes include:

  • All new (and hopefully clearer) tutorial and reference documentation.

  • The CryptPolicy class and the CryptContext.policy attribute have been deprecated.

    This was a semi-internal class, which most applications were not involved with at all, but to be conservative about breaking things, the existing CryptPolicy interface will remain in-place and supported until Passlib 1.8.

    All of the functionality of this class has been rolled into CryptContext itself, so there’s one less class to remember. Many of the methods provided by CryptPolicy are now CryptContext methods, most with the same name and call syntax. Information on migrating existing code can be found in the deprecation warnings issued by the class itself, and in the CryptPolicy documentation.

  • Two new class constructors have been added (CryptContext.from_path() and CryptContext.from_string()) to aid in loading CryptContext objects directly from a configuration file.

  • The deprecated keyword can now be set to the special string "auto"; which will automatically deprecate all schemes except for the default one.

  • The min_verify_time keyword has been deprecated, will be ignored in release 1.7, and will be removed in release 1.8. It was never very useful, and now complicates the internal code needlessly.

  • All string parsing now uses stdlib’s SafeConfigParser.

    Previous releases used the original ConfigParser interpolation; which was deprecated in Passlib 1.5, and has now been removed. This should only affect strings which contained raw % characters, they will now need to be escaped via %%.

Other Modules

  • The api for the passlib.apache module has been updated to add more flexibility, and to fix some ambiguous method and keyword names. The old interface is still supported, but deprecated, and will be removed in Passlib 1.8.
  • Added the django14_context preset to the the passlib.apps module. this preconfigured CryptContext object should support all the hashes found in a typical Django 1.4 deployment.
  • new: Added passlib.ext.django, a Django plugin which can be used to override Django’s password hashing framework with a custom Passlib policy (an undocumented beta version of this was present in the 1.5 release).
  • new: The passlib.utils.saslprep() function may be useful for applications which need to normalize the unicode representation of passwords before they are hashed.


  • Handle platform-specific error strings that may be returned by the crypt() methods of some OSes.
  • Fixed rare 'NoneType' object has no attribute 'decode' error that sometimes occurred on platforms with a deviant implementation of crypt().

Internal Changes

The following changes should not affect most end users, and have been documented just to keep track of them:

  • Passlib is now source-compatible with Python 2.5+ and Python 3.x. It no longer requires the use of the 2to3 command to translate it for Python 3.

  • The unittest suite has been rewritten. It handles a number of additional border cases, enforcing uniform behavior across all hashes, and even features the addition of some simplistic fuzz testing. It will take a bit longer to run though. While not perfect, statement coverage is at about 95%. Additionally, the hash test suite has been enhanced with many more test vectors across the board, including 8-bit test vectors.

  • The internal framework used to construct the hash classes (passlib.utils.handlers) was rewritten drastically. The new version provides stricter input checking, reduction in boilerplate code. These changes should not affect any publically exposed routines.

    • GenericHandler‘s strict keyword was removed, strict=True is now the class’s default behavior: all values must be specified, and be within the correct bounds. The new keywords use_defaults and relaxed can be used to disable these two requirements.
    • Most of the private methods of GenericHandler were renamed to begin with an underscore, to clarify their status; and turned into instance methods, to simplify the internals. (for example, norm_salt was renamed to _norm_salt).
    • StaticHandler now derives from GenericHandler, and requires _calc_checksum() be implemented instead of encrypt(). The old style is supported but deprecated, and support will be removed in Passlib 1.8.
    • Calls to HasManyBackends.set_backend() should now use the string "any" instead of the value None. None was deprecated in release 1.5, and is no longer supported.
  • passlib.utils.h64 has been replaced by an instance of the new Base64Engine class. This instance is imported under the same name, and has (mostly) the same interface; but should be faster, more flexible, and better unit-tested.
  • deprecated some unused support functions within passlib.utils, they will be removed in release 1.7.

1.5.3 (2011-10-08)

Bugfix release – fixes BCrypt padding/verification issue (issue 25)

This release fixes a single issue with Passlib’s BCrypt support: Many BCrypt hashes generated by Passlib (<= 1.5.2) will not successfully verify under some of the other BCrypt implementations, such as OpenBSD’s /etc/master.passwd.

In detail:

BCrypt hashes contain 4 “padding” bits in the encoded salt, and Passlib (<= 1.5.2) generated salts in a manner which frequently set some of the padding bits to 1. While Passlib ignores these bits, many BCrypt implementations perform password verification in a way which rejects all passwords if any of the padding bits are set. Thus Passlib’s BCrypt salt generation needed to be fixed to ensure compatibility, and a route provided to correct existing hashes already out in the wild issue 25.

Changes in this release:

  • BCrypt hashes generated by Passlib now have all padding bits cleared.
  • Passlib will continue to accept BCrypt hashes that have padding bits set, but when it encounters them, it will issue a UserWarning recommending that the hash should be fixed (see below).
  • Applications which use CryptContext.verify_and_update() will have any such hashes automatically re-encoded the next time the user logs in.

To fix existing hashes:

If you have BCrypt hashes which might have their padding bits set, you can import passlib.hash.bcrypt, and call clean_hash = bcrypt.normhash(hash). This function will clear the padding bits of any BCrypt hashes, and should leave all other strings alone.

1.5.2 (2011-09-19)

Minor bugfix release – mainly Django-related fixes


  • bugfix: django_des_crypt now accepts all hash64 characters in its salts; previously it accepted only lower-case hexadecimal characters (issue 22).
  • Additional unittests added for all standard Django hashes.
  • django_des_crypt now rejects hashes where salt and checksum containing mismatched salt characters.


1.5.1 (2011-08-17)

Minor bugfix release – now compatible with Google App Engine.

  • bugfix: make passlib.hash.__loader__ attribute writable - needed by Google App Engine (GAE) issue 19.
  • bugfix: provide fallback for loading passlib/default.cfg if pkg_resources is not present, such as for GAE issue 19.
  • bugfix: fixed error thrown by CryptContext.verify when issuing min_verify_time warning issue 17.
  • removed min_verify_time setting from custom_app_context, min_verify_time is too host & load dependant to be hardcoded issue 17.
  • under GAE, disable all unittests which require writing to filesystem.
  • more unittest coverage for passlib.apps and passlib.hosts.
  • improved version datestamps in build script.

1.5 (2011-07-11)

“20% more unicode than the leading breakfast cereal”

The main new feature in this release is that Passlib now supports Python 3 (via the 2to3 tool). Everything has been recoded to have better separation between unicode and bytes, and to use unicode internally where possible. When run under Python 2, Passlib 1.5 attempts to provide the same behavior as Passlib 1.4; but when run under Python 3, most functions will return unicode instead of ascii bytes.

Besides this major change, there have been some other additions:


  • added support for Cryptacular’s PBKDF2 format.
  • added support for the FSHP family of hashes.
  • added support for using BCryptor as BCrypt backend.
  • added support for all of Django’s hash formats.


  • interpolation deprecation:

    CryptPolicy.from_path() and CryptPolicy.from_string() now use SafeConfigParser instead of ConfigParser. This may cause some existing config files containing unescaped % to result in errors; Passlib 1.5 will demote these to warnings, but any extant config files should be updated, as the errors will be fatal in Passlib 1.6.

  • added encoding keyword to CryptPolicy‘s .from_path(), .from_string(), and .to_string() methods.

  • both classes in passlib.apache now support specifying an encoding for the username/realm.


  • Password Hash API expanded to include explicit unicode vs bytes policy.
  • Added quickstart guide to documentation.
  • Various minor improvements.

Internal Changes

  • Added more handler utility functions to reduce code duplication.
  • Expanded kdf helpers in passlib.utils.pbkdf2.
  • Removed deprecated parts of passlib.utils.handlers.
  • Various minor changes to passlib.utils.handlers.HasManyBackends; main change is that multi-backend handlers now raise MissingBackendError if no backends are available.
  • Builtin tests now use unittest2 if available.
  • Setup script no longer requires distribute or setuptools.
  • added (undocumented, experimental) Django app for overriding Django’s default hash format, see docs/lib/passlib.ext.django.rst for more.

1.4 (2011-05-04)

This release contains a large number of changes, both large and small. It adds a number of PBKDF2-based schemes, better support for LDAP-format hashes, improved documentation, and faster load times. In detail...


  • added LDAP {CRYPT} support for all hashes known to be supported by OS crypt()
  • added 3 custom PBKDF2 schemes for general use, as well as 3 LDAP-compatible versions.
  • added support for Dwayne Litzenberger’s PBKDF2 scheme.
  • added support for Grub2’s PBKDF2 hash scheme.
  • added support for Atlassian’s PBKDF2 password hash
  • added support for all hashes used by the Roundup Issue Tracker
  • bsdi_crypt, sha1_crypt now check for OS crypt() support
  • salt_size keyword added to encrypt() method of all the hashes which support variable-length salts.
  • security fix: disabled unix_fallback’s “wildcard password” support unless explicitly enabled by user.


  • host_context now dynamically detects which formats OS crypt() supports, instead of guessing based on sys.platform.
  • added predefined context for Roundup Issue Tracker database.
  • added CryptContext.verify_and_update() convenience method, to make it easier to perform both operations at once.
  • bugfix: fixed NameError in category+min_verify_time border case
  • apps & hosts modules now use new LazyCryptContext wrapper class - this should speed up initial import, and reduce memory by not loading unneeded hashes.


  • greatly expanded documentation on how to use CryptContexts.
  • roughly documented framework for writing & testing custom password handlers.
  • various minor improvements.


  • added generate_password() convenience method
  • refactored framework for building hash handlers, using new mixin-based system.
  • deprecated old handler framework - will remove in 1.5
  • deprecated list_to_bytes & bytes_to_list - not used, will remove in 1.5


  • password hash api - as part of cleaning up optional attributes specification, renamed a number of them to reduce ambiguity:

    • renamed {xxx}_salt_chars attributes -> xxx_salt_size
    • renamed salt_charset -> salt_chars
    • old attributes still present, but deprecated - will remove in 1.5
  • password hash api - tightened specifications for salt & rounds parameters, added support for hashes w/ no max salt size.

  • improved password hash api conformance tests

  • PyPy compatibility

1.3.1 (2011-03-28)

Minor bugfix release.

  • bugfix: replaced “sys.maxsize” reference that was failing under py25
  • bugfix: fixed default_rounds>max_rounds border case that could cause ValueError during CryptContext.encrypt()
  • minor documentation changes
  • added instructions for building html documentation from source

1.3 (2011-03-25)

First public release.

  • documentation completed
  • 99% unittest coverage
  • some refactoring and lots of bugfixes
  • added support for a number of additional password schemes: bigcrypt, crypt16, sun md5 crypt, nthash, lmhash, oracle10 & 11, phpass, sha1, generic hex digests, ldap digests.

1.2 (2011-01-06)


For this and all previous versions, Passlib did not exist independently, but as a subpackage of BPS, a private & unreleased toolkit library.

  • many bugfixes
  • global registry added
  • transitional release for applications using BPS library.
  • first truly functional release since splitting from BPS library (see below).

1.0 (2009-12-11)

  • CryptContext & CryptHandler framework
  • added support for: des-crypt, bcrypt (via py-bcrypt), postgres, mysql
  • added unit tests

0.5 (2008-05-10)

  • initial production version
  • consolidated from code scattered across multiple applications
  • MD5-Crypt, SHA256-Crypt, SHA512-Crypt support