Simple, secure web session handling for Python applications.
WARNING: This project is currently under active development and should not be used in production environments. API's may change without support for previous versions.
Straightforward to understand and implement.
Web framework/library independent;
Support for different storage back-ends;
Secure by default;
Pithos is ancient Greek for a large terracotta storage jar. While no terracotta has been used in this project, we do provide you with a large jar for cookie related storage ;-)
Pithos provides three concepts to handle sessions:
A session instance which acts like a Python dictionary and handles session state handling, serialization and encryption;
A storage back-end which knows how to store, retrieve and cleanup sessions;
A handler class which ties session instances and storage together and integrates this with the request and response handling of your web-application.
In addition helper functions are provided to handle login and logout of authenticated users.
Pithos is Python 2.7 and Python >= 3.4 compatible.
Install like this:
pip install pithos
Optionally install storage specific requirements:
pip install pithos[redis]
Usage of a web framework is not required. Pithos can be used in any Python code which provides generic web concepts such as HTTP requests and reponses with cookies.
Pithos provides ready to use integration with Flask. The Flask implementation can be used as a reference implementation for your own setup.
For Flask one can configure the Flask app like this:
from flask import Flask from pithos.flask import setup_pithos from pithos.filesystem import FilesystemStore app = Flask() pithos_store = FilesystemStore(root='/my/path/to/sessions') setup_pithos(app, pithos_store)
Pithos leverages the Flask
session interface, and can thus be used as a
regular Flask session:
from flask import session @app.route('/foo') def foo(): session['remember'] = 'me' return 'bar'
TODO: Implement and document Django integration
TODO: Implement and document Tornado integration. Probably needs a async storage backend.
TODO: Show plain WSGI integration
A session instance works similar to a regular Python dictionary, in fact it
Public attributes of sessions:
is_modified which indicates that the session has been modified. This is
automatically set to True when manipulating keys on the session directly but
should be manually set when modifying mutable data structures stored in the
session (such as dictionaries and lists).
The following public methods can be called on a session instance:
set_duration(ttl=<int>): all sessions expire after a default period set in
handler. Specific sessions may have a specific duration which can be set
using this method. This can be used to give privileged sessions a shorter
reset(): clear anything stored in the session and forget its ID and
encryption key. Most of the time you're better of using the
method of the session
handler because that also tries to resets the session
cookie in an HTTP response.
Pithos sessions must be persisted somewhere, because it does not support storage of session content in cookies. Pithos currently provides plain file-system storage, and Redis backed storage. File-system storage is easy on memory usage while the Redis storage has the advantage of automatically removing expired sessions and using a central storage usable by multiple hosts.
Pithos uses JSON to serialize sessions, and in addition to natively supported
data types also serializes
datetime instances to strings
(deserialization is not implemented).
pithos.authsession module contains a few helper functions to implement
authenticated sessions related functions, such as login and logout.
These function work with the concept of a user
checkvalue. This should be a
JSON serializable value which changes when sensitive aspects of a user are
changed, for example when its password or username changes. Whenever this
checkvalue changes, all sessions of that user will become invalid. A sensible
checkvalue could be constructed by calculating a digest over the users protected
password and username as stored in the user database, or it could be random
value stored with the user and which is updated every time the user updates its
The following functions are available:
Retrieve the user ID from the session, return None when no user is set. Do not
forget to run
check_session immediately after retrieving the user instance.
Return a dictonary with extra user details stored with the user ID in the current session. This could be used to store which authentication method has been used to login.
login(session, user_id, checkvalue, **kwargs)
Login a user identified with
user_id onto the session. Also stores the user
checkvalue and optionally additional user related data using keyword
arguments. The extra keyword arguments can later be retrieved using the
Destroys the current session and (optionally) sets an empty session cookie on the provided response.
keep_login(session, user_id, checkvalue)
Call this function when the users checkvalue deliberately changes, for example directly after the user successfully changes its password. This prevents the user from being logged out while all other sessions for this user become invalid.
check_session(session, checkvalue, response=None)
Checks if the users checkvalue matches. When the check fails, the session is reset and the function returns False.
Random 128 bits session ID's;
Sessions are stored encrypted and can only be read when in possession of the clients session cookie. Pithos uses authenticated encryption using NaCl Secret-key authenticated encryption (crypto_secretbox) (Salsa20 stream cipher + Poly1305 MAC for authentication);
Guaranteed session (server side) expiry in addition to session cookie expiry;
Optionally fix session to initial client IP address;
Only stores (JSON) data in sessions (not code, such as possible with Pickle);
Pithos provides helper functions to bind an authenticated user to a session. These helper functions prevent session fixation, needless session creation and invalidating authenticated sessions for a specific user.
Ideas / plans
Extend documentation and test suite
Optionally run session engine as daemon to use it from non-Python environments, use ZeroMQ and provide a Python client?;
Implement SQLAlchemy, Django ORM, and memcached backends;
Django, Tornado, bottle, webpy integration;
Provide example for plain WSGI usage.