-This is alpha software under active development. It was only tested
-on **Python 2.7**. It probably will not run on Python 2.5 since
-*py-scrypt* doesn't run on anything earlier than Python 2.6.
+ 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.
-To use Scrypt as your default storage algorithm in Django 1.4, do the
-Install the py-scrypt library version 0.5.5 or later (probably by running ``sudo pip install py-scrypt``, or downloading the library and installing it with ``python setup.py install``).
-**Py-Scrypt 0.5.5 contains a major bug on 64-bit Linux**
+ You need to install Django 1.4 and ``py-scrypt`` prior to installing
-Next, install Django-Scrypt::
+1. Download the source tarball for Django-Scrypt from Pypi::
+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
Then, run the test suite::
-In your Django 1.4 application *settings.py* file, modify (or add) the
-``PASSWORD_HASHERS`` tuple to include ``ScryptPasswordHasher`` first.
+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``.
+ 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
Note: You need to keep the other hasher entries in this list, or else Django
-won't be able to upgrade passwords!
+won't be able to upgrade 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
+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.
+ >>> from django.contrib.auth import models
+ >>> pf = models.User._meta.get_field('password')
+ <django.db.models.fields.CharField: password>
+ >>> pf.max_length = max(pf.max_length, 256)
There is a bit more to the software, but you will have to read the source to
If you find bugs please report them to the BitBucket issue tracker or send
me an email to email@example.com. Any serious security bugs should be
+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.
+Thanks to Dr Colin Percival for his original Scrypt software,
+also to Magnus Hallin for the py-scrypt Python module.