Skip to content

passlib.apps - Helpers for various applications

This module contains a number of preconfigured CryptContext instances that are provided by Passlib for easily handling the hash formats used by various applications.

Usage Example

The CryptContext class itself has a large number of features, but to give an example of how to quickly use the instances in this module:

Each of the objects in this module can be imported directly:

# as an example, this imports the custom_app_context object,
# a helper to let new applications *quickly* add password hashing.
from passlib.apps import custom_app_context

Hashing a password is simple (and salt generation is handled automatically):

hash = custom_app_context.hash("toomanysecrets")
print(hash)
# > $5$rounds=84740$fYChCy.52EzebF51$9bnJrmTf2FESI93hgIBFF4qAfysQcKoB0veiI0ZeYU4

Verifying a password against an existing hash is just as quick:

print(custom_app_context.verify("toomanysocks", hash))
# > False
print(custom_app_context.verify("toomanysecrets", hash))
# > True

Tip

See the CryptContext Tutorial and CryptContext Reference for more information about the CryptContext class.

Django

The following objects provide pre-configured CryptContext instances for handling Django password hashes, as used by Django's django.contrib.auth module. They recognize all the builtin Django hashes supported by the particular Django version.

Note

These objects may not match the hashes in your database if a third-party library has been used to patch Django to support alternate hash formats. This includes the django-bcrypt plugin, or Passlib's builtin passlib.ext.django. As well, Django 1.4 introduced a very configurable "hashers" framework, and individual deployments may support additional hashes and/or have other defaults.

django10_context

The object replicates the password hashing policy for Django 1.0-1.3. It supports all the Django 1.0 hashes, and defaults to django_salted_sha1.

Warning

Added in 1.6.

django14_context

The object replicates the stock password hashing policy for Django 1.4. It supports all the Django 1.0 & 1.4 hashes, and defaults to django_pbkdf2_sha256. It treats all Django 1.0 hashes as deprecated.

Warning

Added in 1.6.

django16_context

The object replicates the stock password hashing policy for Django 1.6. It supports all the Django 1.0-1.6 hashes, and defaults to django_pbkdf2_sha256. It treats all Django 1.0 hashes as deprecated.

Warning

Added in 1.6.2.

django_context

This alias will always point to the latest preconfigured Django context supported by Passlib, and as such should support all historical hashes built into Django.

Warning

Changed in 1.6.2: This now points to django16_context.

LDAP

Passlib provides two contexts related to ldap hashes:

ldap_context

This object provides a pre-configured CryptContext instance for handling LDAPv2 password hashes. It recognizes all the standard ldap hashes.

It defaults to using the {SSHA} password hash. For times when there should be another default, using code such as the following:

from passlib.apps import ldap_context

ldap_context = ldap_context.replace(default="ldap_salted_md5")

# the new context object will now default to {SMD5}:
print(ldap_context.hash("password"))
# > '{SMD5}T9f89F591P3fFh1jz/YtW4aWD5s='

ldap_nocrypt_context

This object recognizes all the standard ldap schemes that ldap_context does, except for the {CRYPT}-based schemes.

MySQL

This module provides two pre-configured CryptContext instances for handling MySQL user passwords:

mysql_context

This object should recognize the new mysql41 hashes, as well as any legacy mysql323 hashes.

It defaults to mysql41 when generating new hashes.

This should be used with MySQL version 4.1 and newer.

mysql3_context

This object is for use with older MySQL deploys which only recognize the mysql323 hash.

This should be used only with MySQL version 3.2.3 - 4.0.

PHPass

PHPass is a PHP password hashing library, and hashes derived from it are found in a number of PHP applications. It is found in a wide range of PHP applications, including Drupal and Wordpress.

phpass_context

This object follows the standard PHPass logic: it supports bcrypt, bsdi_crypt, and implements a custom scheme called the "phpass portable hash" phpass as a fallback.

BCrypt is used as the default if support is available, otherwise the Portable Hash will be used as the default.

Warning

Changed in 1.5: Now uses Portable Hash as fallback if BCrypt isn't available. Previously used BSDI-Crypt as fallback (per original PHPass implementation), but it was decided PHPass is in fact more secure.

phpbb3_context

This object supports phpbb3 password hashes, which use a variant of phpass.

PostgreSQL

postgres_context

This object should recognize password hashes stored in PostgreSQL's pg_shadow table, which are all assumed to follow the postgres_md5 format.

Note that the username must be provided whenever hashing or verifying a postgres hash:

from passlib.apps import postgres_context

# hashing a password...
hashed = postgres_context.hash("somepass", user="dbadmin")
print(hashed)
# > 'md578ed0f0ab2be0386645c1b74282917e7'

# verifying a password...
print(postgres_context.verify("somepass", hashed, user="dbadmin"))
# > True
print(postgres_context.verify("wrongpass", hashed, user="dbadmin"))
# > False

# forgetting the user will result in an error:
try:
    postgres_context.hash("somepass")
except TypeError as err:
    print(err)
# > user must be unicode or bytes, not None

Roundup

The Roundup Issue Tracker has long supported a series of different methods for encoding passwords. The following contexts are available for reading Roundup password hash fields:

roundup10_context

This object should recognize all password hashes used by Roundup 1.4.16 and earlier: ldap_hex_sha1 (the default), ldap_hex_md5, ldap_des_crypt, and roundup_plaintext.

roundup15_context

Roundup 1.4.17 adds support for ldap_pbkdf2_sha1 as its preferred hash format. This context supports all the roundup10_context hashes, but adds that hash as well (and uses it as the default).

roundup_context

This is an alias for the latest version-specific roundup context supported by passlib, currently the roundup15_context.

Custom Applications

custom_app_context

This CryptContext object is provided for new python applications to quickly and easily add password hashing support. It comes preconfigured with:

  • Support for sha256_crypt and sha512_crypt
  • Defaults to SHA256-Crypt under 32 bit systems, SHA512-Crypt under 64 bit systems.
  • Large number of rounds, for increased time-cost to hedge against attacks.

For applications which want to quickly add a password hash, all they need to do is import and use this object, per the usage example at the top of this page.

Tip

See the quickstart for additional details.