Installing PolyPasswordHasher for Django

This page describes the basic setup and usage of the polypasswordhasher for Django (or Django_pph). The document is organized in two sections. The first section will describe how to configure a new or existing server to use with the polypasswordhasher, while the second will describe some management commands and extensions that can be applied to enhance the performance of the hasher in a server.

In order to use Django_pph, there needs to be an installation, configuration and initialization of the hasher. Afterwards, some commands are available to manage the way the hasher handles different user accounts depending on the level of trust and their privilege.

• Installation
  • Getting the sources
  • Configuring the settings file
  • Creating threshold accounts
    • Creating user accounts
    • Setting up the store
• Conclusion

# Installation

In order to use Django_pph, there are two steps. First, one must install the source files for the software and select PolyPasswordHasher in the Django settings file. After this is complete, then create accounts, if you have a new server, or migrate an existing password database and you are done!

The following steps will walk you through the process.

### Getting the sources

The sources require PyCrypto in order to work, you can get PyCrypto by running the following command:

$ pip install pycrypto

After successfully installing pycrypto, you can install the sources.

The sources can be downloaded here. After downloading, uncompress and copy the django_pph folder to the root of your application.

$ wget https://github.com/PolyPasswordHasher/PolyPasswordHasher-Django/archive/master.zip
...
$ unzip master.zip
...
$ cp -r PolyPasswordHasher-Django-master/django_pph/ my_django_project/

The django_pph folder should reside in the same location as the target application's "manage.py" script. This should look like the following:

$ cd my_django_project
$ ls -1
django_pph
my_django_project
manage.py
db.sqlite3

The db.sqlite3 may or may not appear, depending on your database backend.

Now, we move on to the configuration step.

### Configuring the settings file.

The settings file will contain the elements for every application that's installed. Django_pph specific settings are also set there.

First, we will describe the basic setup to have a vanilla django_pph application running. Afterwards, we will focus on setting polypasswordhasher-specific settings to tailor the hasher to our needs.

Basic setup.

In order to work, a Django PPH server must at least contain the following elements in the settings.py file:

# add django_pph to the INSTALLED APPS
INSTALLED_APPS = (
    'django.contrib.auth',
     ...
    'django_pph',
)

# set the django hasher as the default hasher, make it appear in the top
# of the list (if the list already exists...)
PASSWORD_HASHERS = (
    'django_pph.hashers.PolyPasswordHasher',
)


# We will add a custom cache object ('pph') to store the shares locally.
CACHES={
    'default': {
        'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
    },
    # this will store non-persistent information (you can use the memcache if
    # desired
    'pph': {
        'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache',
        'LOCATION': 'pph_cache',
        'TIMEOUT': None,
    },
    # for persistent storage, only non sensitive information will be stored here
    'share_cache': {
            'BACKEND': 'django.core.cache.backends.db.DatabaseCache',
            'LOCATION': 'share_cache',
    },
}

# this is a default logger configuration with a file handler, you can copy
# all of this over
LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'verbose': {
            'format': '%(levelname)s %(asctime)s %(module)s %(process)d %(thread)d %(message)s',
        },
        'simple': {
            'format': '%(levelname)s %(message)s',
        },
    },
    'handlers': {
        'file': {
            'level': 'DEBUG',
            'class': 'logging.FileHandler',
            # set this path to a location specific to your project
            'filename': '/path/to/log.log',
            'formatter':'verbose',
        },
    },
    'loggers': {
        'django.security.PPH': {
            'handlers': ['file'],
            'level': 'DEBUG',
            'propagate': True,
        },
    },
}

You can further modify these settings to get email notification when there are break-in alerts or to change some of the default hasher values. Read more about it here.

# Creating Threshold accounts

The last step to configure our application is to create a series of threshold accounts that can unlock the store after rebooting. In new servers, we need to create a secret and immediately create new accounts. In the case of existing servers, we can use an automated script to update the existing hashes to work with Django_pph.

If you are installing Django_pph in an already existing server, jump to the next section

### (For New Password Databases Only!) Creating user accounts

*** If you already have a database with users, you can skip this section ***

If you have a new password database, you need to create some users in order to be able to setup the store for the first time. Depending on the threshold value (the default is 3), you will need to create that number of accounts. Accounts can be created by issuing the following commands:

$ ./manage.py createsuperuser [username]

In case you don't want some users to become superusers, you can create the accounts using the admin portal by running the server:

$ ./manage.py runserver

And navigating to localhost:8000/admin. You need at least one superuser to be able to log-in here.

Now, we proceed into the store setup sections.

### Setting up the PolyPasswordHasher store

To set the store, we simply need to issue the following command:

*** WARNING: please consider backing up your database before continuing ***

$./manage.py createcachetable share_cache
$./manage.py setup_store username1 username2 ... usernameN

Here, you will issue a setup command that will initialize the secret and will setup the threshold accounts. The usernames provided will be those of the threshold accounts (usually active people you trust), the rest will be defaulted to non-threshold accounts.

# Conclusion.

After setup, you are able to log in for both types of accounts seamlessly while being protected by PolyPasswordHasher.

Now that you have a Django_pph-enabled application up and running, you can now take a look at the administration commands to understand how to manage accounts and leverage extra capabilities provided.

You might also want to take a look at the the frequently asked questions page.