Django_pph can be installed in both, new servers and existing servers. Here, we describe how to setup the hasher for either case.

To install and run django_pph in a new server you must do three basic steps:

1. Edit the settings.py file inside your configuration script
2. Run the server
3. Create a secret and add administrative accounts.

The upcoming subsections will describe these steps in depth.

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 taylor the hasher to our needs.

After the settings file is properly configured, we are able to use the server right away. In order to start the server we run the following administrator command:

$ ./manage.py runserver

Once the server is running, we need to create the secret for the polypasswordhasher store. We create a secret and unlock the store for the first time by issuing the following command:

$ ./manage.py initialize_pph_context

Now we have a secret and the context is initialized. We can proceed to the last step.

Warning, using this command with an already running application could overwrite the secret and yield an inconsistent store

Lastly, we want to create a number of threshold accounts higher than the threshold we configured in step one. We must issue the following commands for each user:

$ ./manage.py createsuperuser [username]
$ ./manage.py promote_user [username]

The first command creates an account and second command makes the account count towards the threshold. This should be repeated threshold-number of times. Notice that you could create non-superuser accounts with another command (e.g. the administrator console) and then promote them in the same way.

Congratulations! Now we have a django_pph enabled application from scratch.

In case we already have a server running our Django application, we must first migrate all of the information using south. In order to do this we must first install south:

$ pip install south

After a successful installation of south, we must add the following line to the settings.py file:

INSTALLED_APPS = (
    'django.contrib.auth',
    ...
    'django_pph',
    'south',
)

SOUTH_MIGRATION_MODULES = {
    'auth' : 'django_pph.migrations'
}

This instructs south to search for the migration procedures for the authentication backend in the django_pph folder and installs both: django_pph and south to our server's applications. Remember that you must also add the config settings displayed in the previous section in order to have django_pph working.

Finally, in order to run the migration, we issue the following command

$ ./manage.py migrate auth

This will run our south migration script and leave the database in a consistent state. Threshold accounts in here are selected as the administrative accounts.

WARNING, consider backing up your database before running the migration script

Congratulations! Now you have a complete setup of django_pph in your application.

In this section you can find extensions to the bare-bones installation of django_pph as well as description of some administration commands that make it useful for maintaining your system.

The django_pph application uses the default django logger in order to notify the administrator of certain errors and break-in attempts. One feature of this is the ability to plug the logger messages of certain level (e.g. error) to an e-mail handler. By doing this, we are able to be notified when events such as a possible database-leak has ocurred.

In this section we will provide an example configuration of the django_pph logger that notifies administrators of break-in scenarios by sending an email. The following code snipped is to be modified in the original settings.py and inside the logger variable:

    'handlers': {
        'file': {
            'level': 'DEBUG',
            'class': 'logging.FileHandler',
            'filename': '/path/to/log.log',
            'formatter':'verbose',
        },
        'mail_admins': {
             'level': 'ERROR',
             'class': 'django.utils.log.AdminEmailHandler'
    },
    'loggers': {
        'django.security.PPH': {
            'handlers': ['mail_admins'],
            'level': 'DEBUG',
            'propagate': True,
        },
    },

Also, you might want to set the following variable:

SERVER_EMAIL = '[application]@[domain].com'

So you know where it comes from.

Some versions of Django require that you unset the DEBUG variable in order to work.

Django_pph comes with three management commands. Two of them, promote_ and demote_user, provide the ability to manage which accounts count towards the threshold to unlock a store. The third one, initialize_pph_context, should be only called when the application is first launched.

The following sections contain a detailed description of the management commands.

./manage.py demote_user [username]

This command removes a user from the accounts that count towards the threshold in the secret-recombination phase. In case a user becomes inactive or shouldn't be trusted, we advise to run this command right away.

In contrast to promote_user, this command needs an unlocked store in order to demote a user.

$ ./manage.py initialize_pph_context

This command is only meant to be ran during the first run of the django_pph application. When using migrations, this command is already run by the migration script and it is, therefore, unnecessary to run it afterwards.

Be careful when running this command, since it might yield the authentication database useless. Remember always to have backups of your database.