Password management in Django¶

Using bcrypt with Django¶

Bcrypt is a popular password storage algorithm that’s specifically designed for long-term password storage. It’s not the default used by Django since it requires the use of third-party libraries, but since many people may want to use it Django supports bcrypt with minimal effort.

To use Bcrypt as your default storage algorithm, do the following:

1. Install the py-bcrypt library (probably by running sudo pip install py-bcrypt, or downloading the library and installing it with python setup.py install).

2. Modify PASSWORD_HASHERS to list BCryptPasswordHasher first. That is, in your settings file, you’d put:

   PASSWORD_HASHERS = (
       'django.contrib.auth.hashers.BCryptPasswordHasher',
       'django.contrib.auth.hashers.PBKDF2PasswordHasher',
       'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
       'django.contrib.auth.hashers.SHA1PasswordHasher',
       'django.contrib.auth.hashers.MD5PasswordHasher',
       'django.contrib.auth.hashers.CryptPasswordHasher',
   )
   

   (You need to keep the other entries in this list, or else Django won’t be able to upgrade passwords; see below).

That’s it – now your Django install will use Bcrypt as the default storage algorithm.

Increasing the work factor¶

The PBKDF2 and bcrypt algorithms use a number of iterations or rounds of hashing. This deliberately slows down attackers, making attacks against hashed passwords harder. However, as computing power increases, the number of iterations needs to be increased. We’ve chosen a reasonable default (and will increase it with each release of Django), but you may wish to tune it up or down, depending on your security needs and available processing power. To do so, you’ll subclass the appropriate algorithm and override the iterations parameters. For example, to increase the number of iterations used by the default PBKDF2 algorithm:

1. Create a subclass of django.contrib.auth.hashers.PBKDF2PasswordHasher:

   from django.contrib.auth.hashers import PBKDF2PasswordHasher
   
   class MyPBKDF2PasswordHasher(PBKDF2PasswordHasher):
       """
       A subclass of PBKDF2PasswordHasher that uses 100 times more iterations.
       """
       iterations = PBKDF2PasswordHasher.iterations * 100
   

   Save this somewhere in your project. For example, you might put this in a file like myproject/hashers.py.

2. Add your new hasher as the first entry in PASSWORD_HASHERS:

   PASSWORD_HASHERS = (
       'myproject.hashers.MyPBKDF2PasswordHasher',
       'django.contrib.auth.hashers.PBKDF2PasswordHasher',
       'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
       'django.contrib.auth.hashers.BCryptPasswordHasher',
       'django.contrib.auth.hashers.SHA1PasswordHasher',
       'django.contrib.auth.hashers.MD5PasswordHasher',
       'django.contrib.auth.hashers.CryptPasswordHasher',
   )
   

That’s it – now your Django install will use more iterations when it stores passwords using PBKDF2.

Password upgrading¶

When users log in, if their passwords are stored with anything other than the preferred algorithm, Django will automatically upgrade the algorithm to the preferred one. This means that old installs of Django will get automatically more secure as users log in, and it also means that you can switch to new (and better) storage algorithms as they get invented.

However, Django can only upgrade passwords that use algorithms mentioned in PASSWORD_HASHERS, so as you upgrade to new systems you should make sure never to remove entries from this list. If you do, users using un- mentioned algorithms won’t be able to upgrade.