Source

django-scrypt / README.rst

Full commit

Django-Scrypt

Django-Scrypt is a Scrypt-enabled password hasher for Django 1.4

Warning

This is alpha software under active development. It was tested only on Python 2.7. It probably will not run on Python 2.5 since py-scrypt doesn't run on interpreters earlier than Python 2.6.

Installation

Note

You need to install Django 1.4 and py-scrypt prior to installing Django-Scrypt

Using source tarballs

  1. Download the source tarball for Django-Scrypt from Pypi

    http://pypi.python.org/pypi/django-scrypt/

  2. Decompress it and make it your working directory

    $ tar zxvf django-scrypt-0.1.1.tar.gz $ cd django-scrypt-0.1.1

3. Install it into your site-packages (if you install to the system's site packages you will probably need to be root or use sudo)

$ python setup.py install
  1. Test your installation

    $ python setup.py test

Using Pip and Pypi

  1. Use the pip command to install from Pypi

    $ pip install django-scrypt

If you are installing to the system-wide site-packages then you will probably need to be root or use sudo.

Basic Usage

Warning

This software depends on py-scrypt version 0.5.5 to reveal the Scrypt hashing function. Unfortunately, py-scrypt contains a bug that can result in incorrect hashing when run on 64-bit Linux systems. View the py-scrypt issue tracker for the latest information on this issue.

To use Scrypt as your default password storage algorithm in Django 1.4, install it and make the following changes. In your Django 1.4 application settings.py file, modify (or add) the PASSWORD_HASHERS tuple to include ScryptPasswordHasher as the first hasher in the tuple. It needs to be at the top.

For example:

PASSWORD_HASHERS = (
  'django_scrypt.hashers.ScryptPasswordHasher',
  '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',
)

Note: You need to keep the other hasher entries in this list, or else Django won't be able to upgrade the passwords!

You have now changed your app to use Scrypt as the default storage algorithm.

As users login to your system they will automatically upgrade to use Scrypt hashes.

Caveat

Django Password Field Character Length Limits

By default, Django limits password field lengths to 128 characters. Using the default settings in Django-Scrypt with the Django salting implementation should yield encoded hashes less than 128 characters; however, if you override the ScryptPasswordHasher class variables you can end up overflowing the field.

The solution is to increase the size of the password field (this example uses 256 characters but it can be larger). You can do this using the django shell from your project root:

$ cd ~/my_django_project_root_with_manage_py_file_in_it
$ python manage.py shell
Python 2.7.3 (default, May  4 2012, 11:07:18)
[GCC 4.0.1 (Apple Inc. build 5493)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
(InteractiveConsole)
>>> from django.contrib.auth import models
>>> pf = models.User._meta.get_field('password')
>>> pf
<django.db.models.fields.CharField: password>
>>> pf.max_length
128
>>> pf.max_length = max(pf.max_length, 256)
>>> pf.max_length
256
>>>

More Stuff?

There is a bit more to the software, but you will have to read the source to figure it out. :)

Bugs! Help!!

If you find bugs please report them to the BitBucket issue tracker or send me an email to code@kelvinwong.ca. Any serious security bugs should be reported via email.

https://bitbucket.org/kelvinwong_ca/django-scrypt/issues

Thank-you

Thank-you for taking the time to evaluate this software. I appreciate receiving feedback on your experiences with it and I welcome code contributions and development ideas.

http://www.kelvinwong.ca/coders

Thanks to Dr Colin Percival for his original Scrypt software, also to Magnus Hallin for the py-scrypt Python module.