In order to use pwhash you first have to install it, you can do that with pip:
$ pip install pwhash
The next step is to generate the necessary configuration, which depends on your application and the machine it is deployed on, so it has to be created for every deployment. How exactly we can create a new configuration on every deployment conveniently will be covered later, for now let us just create the configuration on the current machine, to do this simply run:
$ pwhash-config create
This will ask you some questions, unless you have a good reason to, you should go with the defaults whenever those are provided. Once you are finished you will find a pwhash.json file, containing the configuration, in your current working directory. The next step you have to take is compiling this application configuration into the deployment configuration:
$ pwhash-config compile pwhash.json
This creates another file pwhashc.json, which is the deployment configuration. The deployment configuration has to be re-created for every machine on which your application is deployed. It contains information derived from the information about your application as well as machine specific information determined during compilation. This allows pwhash to adopt algorithmic cost to the machine you are deploying on, making it as difficult as difficult as possible for an attacker to get the hashed passwords.
Using that configuration we can now use it to create a PasswordHasher:
from pwhash import PasswordHasher
pwhasher = PasswordHasher.from_config_file("pwhashc.json")
You can use the pwhasher object to hash, verify and upgrade (we will learn later what that is) passwords. You can create a hash using create():
hash = pwhasher.create(u"password")
In order to verify a password against that hash use:
pwhasher.verify_and_upgrade(u"password", hash)
This will return a tuple (is_correct_password, upgraded_hash), is_correct_password is True if u"password" is actually the correct password and False otherwise. upgraded_hash will be None or a new more secure hash you should replace the old one with.
pwhash will upgrade a hash and provide you with an upgraded_hash if a new more secure hashing function is available or if the parameters for the hash function changed, which happens if you upgrade machines and re-compile the configuration.