Metadata-Version: 2.2
Name: tokenlib
Version: 2.0.0
Summary: Generic library for managing signed authentication tokens.
Home-page: https://github.com/mozilla-services/tokenlib
Author: Mozilla Services
Author-email: services-dev@mozilla.org
License: MPLv2.0
Keywords: authentication token
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: summary

========
tokenlib
========

This is generic support library for doing token-based authentication.  You
might use it to build a login system using bearer tokens, two-legged oauth, or
MAC Access authentication.

Given a server-side master secret, you can serialize a dict of data into
an opaque, unforgeable authentication token::

   >>> token = tokenlib.make_token({"userid": 42}, secret="I_LIKE_UNICORNS")
   >>> print token
   eyJzYWx0IjogImY0NTU5NCIsICJleHBpcmVzIjogMTMyOTg3NTI2Ny4xNDQ5MzUsICJ1c2VyaWQiOiA0Mn0miXCe4NQQtXTE8NXSGcsL6dzSuQ==

Later, you can use the same secret to verify the token and extract the
embedded data::

    >>> data = tokenlib.parse_token(token, secret="I_LIKE_UNICORNS")
    >>> print data
    {u'userid': 42, u'expires': 1329875384.073159, u'salt': u'1c033f'}

Notice that the data includes an expiry time.  If you try to parse an expired
token, it will fail::

    >>> # Use now=XXX to simulate a time in the future.
    >>> tokenlib.parse_token(token, secret="I_LIKE_UNICORNS", now=9999999999)
    Traceback (most recent call last):
    ...
    ValueError: token has expired

Likewise, it will fail if the token was constructed with a non-matching secret
key::

    >>> tokenlib.parse_token(token, secret="I_HATE_UNICORNS")
    Traceback (most recent call last):
    ...
    ValueError: token has invalid signature

Each token also has an associated "token secret".  This is a secret key that
can be shared with the consumer of the token to enable authentication schemes
such as MAC Access Authentication of Two-Legged OAuth::

    >>> key = tokenlib.get_token_secret(token, secret="I_LIKE_UNICORNS")
    >>> print key
    EZslG8yEYTGyDvBjRnxGipL5Kd8=

For applications that are using the same settings over and over again, you
will probably want to create a TokenManager object rather than using the
module-level convenience functions::

    >>> manager = tokenlib.TokenManager(secret="I_LIKE_UNICORNS")
    >>> data = manager.parse_token(token)
    >>> print data
    {u'userid': 42, u'expires': 1329875384.073159, u'salt': u'1c033f'}

This will let you customize e.g. the token expiry timeout or hash module
without repeating the settings in each call.


2.0.0 - 2017-12-20
==================

 * Py27, Py35 compliant


0.3.1 - 2014-01-08
==================

* Make tokenlib.DEFAULT_HASHMOD a string.
* Fix sporadically-failing test.


0.3.0 - 2014-01-08
==================

* clarified licensing info
* switched to sha256 as default hashing algorithm
* renamed `get_token_secret` to `get_derived_secret` to clarify its
  purpose; the previous name remains but is deprecated.
* added custom ValueError subclasses for more fine-grained error reporting.


0.2.0 - 2012-11-27
==================

* support for python3 via source-level compatibility


0.1.0 - 2012-03-14
==================

 * Initial release.
