New Application Quickstart Guide¶

Need to quickly get password hash support added into your new application, but don’t have time to wade through pages of documentation, comparing and contrasting all the different schemes? Then read on...

Choosing a Hash¶

If you’d like to set up a configuration that’s right for your application, the first thing to do is choose a password hashing scheme. Passlib contains a large number of schemes, but most of them should only be used when a specific format is explicitly required.

The Options¶

There are currently four good choices [1] for secure hashing:

argon2

bcrypt

pbkdf2_sha256 / pbkdf2_sha512

sha256_crypt / sha512_crypt

All four hashes share the following properties:

No known vulnerabilities.

Based on documented & widely reviewed algorithms.

Public-domain or BSD-licensed reference implementations available.

variable rounds for configuring flexible cpu cost on a per-hash basis.

At least 96 bits of salt.

Basic algorithm has seen heavy scrutiny and use for at least 10 years (except for Argon2, born around 2013).

In use across a number of OSes and/or a wide variety of applications.

While Argon2 is much younger than the others, it has seen heavy scrutiny, and was purpose-designed for password hashing. In the near future, it stands likely to become the recommended standard.

Detailed Comparison of Choices¶

Argon2¶

argon2 is the newest of the four recommended hashes. It was selected as the winner of the 2013 Password Hashing Competition, and draws on the design and lessons from BCrypt, PBKDF2, and SCrypt. Despite being much newer than the others, it has seen heavy scrutiny. Since the Argon2 project had the foresight to provide not just a reference implementation, but a standard hash encoding format, these hashes should be reliably interoperatable across all implementations.

Issues: In it’s default configuration, Argon2 uses more memory than the other hashes. However, this is one of it’s hallmarks as a “memory hard” hashing algorithm, and contributes to it’s security. Furthermore the exact amount used is configurable. It’s only main drawback is that as of 2016-6-20 it’s only 3 years old. It’s seen only a few minor adjustments since 2013, but as it is just now gaining widespread use, the next few years are the period in which it will likely either prove itself, or be found wanting. It’s for this reason, any cryptographic algorithm less than a decade old is generally considered “young” :)

BCrypt¶

bcrypt is based on the well-tested Blowfish cipher. In use since 1999, it’s the default hash on all BSD variants. If you want your application’s hashes to be readable by the native BSD crypt() function, this is the hash to use. There is also an alternative LDAP-formatted version (ldap_bcrypt) available.

Issues: Neither the original Blowfish, nor the modified version which BCrypt uses, have been NIST approved; this matter of concern is what motivated the development of SHA512-Crypt. As well, its rounds parameter is logarithmically scaled, making it hard to fine-tune the amount of time taken to verify passwords; which can be an issue for applications that handle a large number of simultaneous logon attempts (e.g. web apps). Finally, BCrypt only hashes the first 72 characters of a password, and will silently truncate longer ones (Passlib’s non-standard bcrypt_sha256 works around this last issue).

PBKDF2¶

pbkdf2_sha512 is a custom hash format designed for Passlib. However, it directly uses the PBKDF2 key derivation function, which was standardized in 2000, and found across a wide variety of applications and platforms. Unlike the previous two hashes, PBKDF2 has a simple and portable design, which is resistant (but not immune) to collision and preimage attacks on the underlying message digest. There is also pbkdf2_sha256, which may be faster on 32 bit processors; as well as LDAP-formatted versions of these ( ldap_pbkdf2_sha512 and ldap_pbkdf2_sha256).

Issues: PBKDF2 has no major security or portability issues, and compares favorably against bcrypt. However, bcrypt has proven slightly more resistant to modern GPU-based cracking techniques.

SHA512-Crypt¶

sha512_crypt is based on the well-tested md5_crypt algorithm. In use since 2008, it’s the default hash on most Linux systems; its direct ancestor md5_crypt has been in use since 1994 on most Unix systems. If you want your application’s hashes to be readable by the native Linux crypt() function, this is the hash to use. There is also sha256_crypt, which may be faster on 32 bit processors; as well as LDAP-formatted versions of these ( ldap_sha512_crypt and ldap_sha256_crypt).

Issues: Like md5_crypt, its algorithm composes the underlying message digest hash in a baroque and somewhat arbitrary set of combinations. So far this “kitchen sink” design has been successful in its primary purpose: to prevent any attempts to create an optimized version for use in a pre-computed or brute-force search. However, this design also hampers analysis of the algorithm for future flaws.

While this algorithm is still considered secure, it has fallen out of favor in comparison to bcrypt & pbkdf2, due to it’s non-standard construction.

Furthermore, when compared to Argon2 and BCrypt, SHA512-Crypt and PBKDF2 have proven more susceptible to cracking using modern GPU-based techniques.

sha512_crypt is probably the best choice for Google App Engine, as Google’s production servers appear to provide native support via crypt, which will be used by Passlib.

Note

References to this algorithm are frequently confused with a raw SHA-512 hash. While sha512_crypt uses the SHA-512 hash as a cryptographic primitive, the algorithm’s resulting password hash is far more secure.

Making a Decision¶

For new applications, this decision comes down to a couple of questions:

Does the hash need to be natively supported by your operating system’s crypt() api, in order to allow inter-operation with third-party applications on the host?
- If yes, the right choice is either bcrypt for BSD variants, or sha512_crypt for Linux; since these are natively supported.
- If no, continue...
Does your hosting provider allow you to install C extensions?
- If no, you probably want to use pbkdf2_sha256, as this currently has the fastest pure-python backend.
- If they allow C extensions, continue...
Do you want to use the latest & greatest, and don’t mind increased memory usage when hashing?
- argon2 is a next-generation hashing algorithm, attempting to become the new standard. It’s design has been being slightly tweaked since 2013, but will quite likely become the standard in the next few years. You’ll need to install the argon2_cffi support library.
- If you want something secure, but more battle tested, continue...
The top choices left are bcrypt and pbkdf2_sha256.

Both have advantages, and their respective rough edges; though currently the balance is in favor of bcrypt (pbkdf2 can be cracked somewhat more efficiently).
- If choosing bcrypt, we strongly recommend installing the bcrypt support library on non-BSD operating systems.
- If choosing pbkdf2, especially on python2 < 2.7.8 and python 3 < 3.4, you will probably want to install fastpbk2 support library.

Creating and Using a CryptContext¶

Once you’ve chosen what password hash(es) you want to use, the next step is to define a CryptContext object to manage your hashes and related policy configuration. Insert the following code into your application:

#
# import the CryptContext class, used to handle all hashing...
#
from passlib.context import CryptContext

#
# create a single global instance for your app...
#
pwd_context = CryptContext(
    # Replace this list with the hash(es) you wish to support.
    # this example sets pbkdf2_sha256 as the default,
    # with additional support for reading legacy des_crypt hashes.
    schemes=["pbkdf2_sha256", "des_crypt"],

    # Automatically mark all but first hasher in list as deprecated.
    # (this will be the default in Passlib 2.0)
    deprecated="auto",

    # Optionally, set the number of rounds that should be used.
    # Appropriate values may vary for different schemes,
    # and the amount of time you wish it to take.
    # Leaving this alone is usually safe, and will use passlib's defaults.
    ## pbkdf2_sha256__rounds = 29000,
    )

To start using your CryptContext, import the context you created wherever it’s needed:

>>> # import context from where you defined it...
>>> from myapp.model.security import pwd_context

>>> # hashing a password...
>>> hash = pwd_context.hash("somepass")
>>> hash
'$pbkdf2-sha256$29000$BSBkLEXIeS9FKMW4F.I85w$SJMzqVU7fw49NDOJZHt2o9vKIfDUVM4cKlAD4MxIgD0'

>>> # verifying a password...
>>> pwd_context.verify("somepass", hash)
True
>>> pwd_context.verify("wrongpass", hash)
False

There’s many more features packed into the context objects, read the walkthrough for more...