Skip to content

Customization

Jump to bottom
Santiago Torres edited this page Jul 29, 2014 · 2 revisions

Customization

This document elaborates on some configuration parameters that can be set along with the basic configuration to modify the behaviour of Django_pph.A

### Modifying configuration parameters

After setting django pph, you can also modify some hasher-specific settings to meet your server's configuration. The following list displays the possible parameters.

  • THRESHOLD: sets the minimum number of threshold accounts to unlock the store. The default is 3.
  • PARTIALBYTES: sets the amount of bytes to leak from the hash in order to provide partial verification. The default value is 4.
  • SECRET_VERIFICATION_BYTES: this sets the number of bytes for the checksum to verify upon recombination. For this, the default value is 4.
  • SECRET_LENGTH: The length of the secret, this should match the length of the hash. The default value is 32.

To set any of these values, you should overwrite them in your settings.py inside the PPH_SETTINGS variable. The following code listing shows an example of this:

PPH_SETTINGS = (
    THRESHOLD = 2,
    PARTIAL_BYTES = 6,
)

Out of these fields, threshold and partial bytes are the ones that leave the most space for configuration. Secret length and secret verification bytes offer little space to play and we advise to leave them in their default setup. Having said this, we will describe threshold and partial_bytes next.

Setting the threshold

The threshold is a value that directly maps to the number of administrative users you want to consider in your server's configuration.

For the PolyPasswordHasher, there exists two types of hashes: threshold and thresholdless. Threshold accounts are the ones that are able to unlock the store after a reboot. Because of this, it is important to only allow this capability to active and trusted users/administrators.

If, for example, there are 5 administrators inside your server, a good idea is to set the threshold to 3 or 4, to ensure that after a reboot it is possible to unlock the store right away. You can look at the FAQ for more explanation about how to pick this value. Do not choose a threshold value higher than the number of trusted administrators of users or else it will be impossible to unlock the store.

Setting the number of partial bytes

Partial bytes provide partial verification. In essence, we leak a part of the hash to allow users to log-in when the store is locked. This is useful in case the threshold accounts take time to respond upon a server reboot. The higher this number is set, the more information about the original hash is leaked. However, if you set this value too low, it could be possible that someone can log-in with wrong credentials. A safe value for this is four to six bytes.

You can learn more about partial bytes in the FAQ.

### Configuring logger notifications via email

Django_pph is able to identify when a database leak has occurred. If there is a login that passed partial verification but doesn't pass the full verification, then there might have been a database compromise; this can be verified either before or after the store has been unlocked.

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 logger is to send messages of certain level (e.g. error) as an e-mail notification.

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',
        },
# we are adding a new handler here.
        'mail_admins': {
             'level': 'ERROR',
             'class': 'django.utils.log.AdminEmailHandler'
    },
    'loggers': {
        'django.security.PPH': {

# we are setting the new handler as default for the PPH logger
            'handlers': ['mail_admins'],
            'level': 'DEBUG',
            'propagate': True,
        },
    },

Finally, you might want to set the following variable:

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

This sets the form field of the email in the Django application, and it will allow you to know exactly which server detected a compromise.

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

After these settings have been properly set up, you should be able to get an email notifying of break in attempts.

Clone this wiki locally