Commits

Kelvin Wong  committed bbd0671 Draft

Add version bump and addtl info for subclassing hasher

  • Participants
  • Parent commits 4744125

Comments (0)

Files changed (1)

 .. warning::
 
    This is alpha software under active development and as such it is not suitable for production use. It was tested only
-   on **Python 2.6/2.7 on a 32-bit Mac**. It probably will not run on Python
+   on **Python 2.6/2.7 on a 32-bit Mac and 64-bit CentOS 6**.
+   It probably will not run on Python
    2.5 since *Py-Scrypt* doesn't run on interpreters earlier than 
    Python 2.6.
 
 
 2. Decompress it and make it your working directory::
 
-       $ tar zxvf django-scrypt-0.2.2.tar.gz
-       $ cd django-scrypt-0.2.2
+       $ tar zxvf django-scrypt-0.2.3.tar.gz
+       $ cd django-scrypt-0.2.3
 
 3. Install it into your ``site-packages`` directory (if you install to the
    system's ``site-packages`` you will probably need to be root or you will
 Keep in mind that the development tip will always be the least stable and the
 least tested version of the software. Please excuse the mess.
 
+Usage
+=====
+
 Basic Usage
-===========
+-----------
 
 .. warning::
 
    You need to keep the other hasher entries in this list or else *Django*
    won't be able to upgrade the passwords!
 
+Advanced Usage
+--------------
+
+If you use this software in a resource constrained environment or if you want a higher degree of protection, you can create custom ``ScryptPasswordHashers`` by subclassing the provided ``ScryptPasswordHasher``. Subclassing will allow you to tune the *Scrypt* parameters to meet your needs.
+
+The first thing to do is create a new custom hasher. Let's assume that you create a new file named ``my_hashers.py`` and you put it into your application root (``my_app``). In that file you can subclass the default hasher::
+
+   from django_scrypt.hashers import ScryptPasswordHasher
+
+   class BigMemNScryptHasher(ScryptPasswordHasher):
+       """This hasher is tuned to use lots of memory
+       (128 * 2 ** 15 * 8) == 33554432 or ~32mb
+       """
+       algorithm = "bigN"
+       N = 15
+
+You can change any (or all) of the class variables ``N``, ``r``, or ``p``. The ``algorithm`` class variable **must** also be changed to a short unique string since it is used to identify and upgrade the hashing scheme in the stored password hash.
+
+To use ``BigMemNScryptHasher`` as your default password storage algorithm make the following changes. In your application's ``settings.py`` file, modify the ``PASSWORD_HASHERS`` tuple (or add it if it
+is missing) to include ``BigMemNScryptHasher`` as the first hasher in the
+tuple. It needs to be at the very top::
+
+    PASSWORD_HASHERS = (
+      'my_app.my_hashers.BigMemNScryptHasher',
+      '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',
+    )
+
+If you want to change the parameters again in the future, simply repeat the process with another subclass and another unique ``algorithm`` class variable. Add it to the top of the tuple and your users will have their password hashes migrated to the new scheme as they log in.
+
 Scrypt Parameters
 -----------------