Example Usages
--------------

Setting up sentry to authenticate users usually requires you to create at
least two objects: a Hasher object, and an Auth object.

For this example, let's say that you store your user and password
information in an SQL database.  The passwords are stored as salted SHA1
hashes.  First, let's create the Hasher object that knows how to generate
and validate salted SHA1 hashes::

    from sentry.hashers import SaltedHasher, SHA1Hasher

    h = SaltedHasher(SHA1Hasher())

We can now generate passwords with this hasher object::

    >>> h.hsh('My Pa$$word', 'mysAltvALue')
    'mysAltvALue:7ff8f766e5aa2bd583f6400a18ceae9c3b8c5d78'

And we can also check that 'My Pa$$word' matches the given hash::

    >>> h('mysAltvALue:7ff8f766e5aa2bd583f6400a18ceae9c3b8c5d78', 'My Pa$$word')
    True

Great!  Now, let's hook it up to the database.  For this we can use the
:class:`sentry.auth.db.SingleTableAuth` class::

    from sentry.auth.db import SingleTableAuth

    a = SingleTableAuth('sqlite:///users.db', 'users', 'name', 'password', h)

Let's break that down a bit.

    'sqlite:///users.db':
        this is the path to our SQLite database that contains all of our
        user information

    'users':
        this is the name of the table in the database that contains the
        username / password information

    'name':
        this is the name of the column in the table that stores the
        username

    'password':
        this is the name of the column in the table that stores the
        password

    h:
        this is our Hasher object that we constructed above

You can create this database yourself to try it out using the sqlite3
commandl-ine, or your favourite database management tool::

    sqlite3 users.db
    SQLite version 3.5.9
    Enter ".help" for instructions
    sqlite> create table users ('name' varchar(255), 'password' varchar(255));
    sqlite> insert into users ('name', 'password') values ('John Doe', 'mysAltvALue:7ff8f766e5aa2bd583f6400a18ceae9c3b8c5d78');
    sqlite> .quit

Then try out your new Auth object::

    >>> a.authenticate('John Doe', 'My Pa$$word')
    True
    >>> a.authenticate('John Doe', 'bad password')
    False