Flask-Digest 0.3.0
A RESTful authentication service for Flask applications
License: MIT
Keywords: digest,authentication,flask

#############################
Flask Digest |license| |pypi|
#############################

.. |license| image:: https://img.shields.io/pypi/l/Flask-Digest.svg?style=flat-square
   :target: https://github.com/vctandrade/flask-digest/blob/master/LICENSE.txt

.. |pypi| image:: https://img.shields.io/pypi/v/Flask-Digest.svg?style=flat-square
   :target: https://pypi.python.org/pypi/Flask-Digest

Flask Digest provides a RESTful way of authenticating users using a Flask
application. To achieve that, it uses the Digest Access Authentication protocol
and most optional features described in `RFC 2617`_.

In a simplified manner, Flask Digest allows you to make your resources available
only to those registered in your system, while taking care of security issues by
following well known protocols.

.. _RFC 2617: https://www.ietf.org/rfc/rfc2617.txt

Quick start
===========

First of all, installation is as simple as:

.. code-block:: console

   $ pip install flask-digest

After doing that, it's important to note this module is
implementation-independent of how the user database is handled and accessed. So
the first thing you need to do is set that up, including methods for registering
users and accessing their passwords.

Then, you need to create a ``Stomach`` object and inform it of how to use the
database you created. The only thing left now is to decide which resources
should be protected and mark them accordingly.

All the steps regarding the ``Stomach`` object are done with the use of three
decorator methods, similar to the ones used by Flask. Those are exemplified
bellow, where ``realm`` is a string of your choosing, used to describe and
identify your server in a unique fashion:

.. code-block:: python

   from flask import Flask
   from flask_digest import Stomach

   app = Flask(__name__)
   stomach = Stomach('realm')

   db = dict()

   @stomach.register
   def add_user(username, password):
       db[username] = password

   @stomach.access
   def get_user(username):
       return db.get(username, None)

   @app.route('/')
   @stomach.protect
   def main():
       return '<h1> resource <h1>'

   add_user('admin', '12345')
   app.run()

Keep in mind that the ``protect`` decorator MUST be located between the chosen
method and Flask's ``route`` decorator.

Also, the method for registering new users is expected to receive a username as
first parameter and a password as second. If you need to, other parameters are
allowed as well.

As for the database access method, it should only have the username as required
parameter, while returning the stored password or ``None`` if the username was
not registered. For more advanced uses, notice that the ``request`` object is
visible from this method, when called internally.

Accessing
=========

Okay, now you know how to protect your resources. But how do you access them,
with all this security casing? Depending on the context of your application,
it can be quite simple. For example, most browsers already support this kind of
authentication protocol out of the box!

If you're thinking of accessing your stuff through another python script, you're
also in luck! There's a module called **Requests**, which seamlessly supports
Digest and will do all the work for you. I *strongly* recommend
`checking it out`_.

.. _checking it out: https://requests.readthedocs.io/en/latest/

On the other hand, if it's written in another language there's no easy solution
I can offer. Either you look for another module with that functionality or
create one yourself. In any case, make sure to tell me how it went, so I can
share your experience here.

Bellow, there's a small list of possible response codes you can get when making
a request to a protected resource and their causes. If the code you got is not
in this list, it probably wasn't generated by Flask Digest.

Responses
=========

**401 Unauthorized**
  When the user provides an invalid combination of username/password, uses a
  ``nonce`` created for another IP or provides a wrong ``nc``, the server will
  deny access to the resource.

  However, if the user does not provide an ``Authorization`` header or uses a
  stale ``nonce``, the server will include a ``WWW-Authenticate`` header, with
  everything he needs to provide his credentials.

**400 BadRequest**
  If the user's ``Authorization`` header is missing a field, does not use the
  requested ``qop`` value or provides the wrong ``uri``, the server will deny
  access to the resource.

Features
========

This implementation of the Digest Authentication scheme uses the **Quality of
Protection (qop)** optional feature. More specifically, it forces you to use the
``auth`` variation of it, since it makes the protocol much more secure. Also, it
discards the ``nonce`` tokens after half an hour and makes sure they are only
used from the IP for whom they were created.

Besides authenticating users, Flask Digest also makes it possible for the client
to authenticate the server. This is done by using the ``Authentication-Info``
header, as it contains a hash that could only be produced if one knew the
client's credentials. This header is included on every successful response.

Regarding user database security, the ``register`` decorator does not allow you
to store passwords in plain text, offering instead a digest of the user's
credentials to the underlying method when it is called.

All of this together results in your application being protected against the
following attacks:

* **Replay**: the request is intercepted and reproduced in the future
* **Reflection**: attacker repasses the server's challenge to the user
* **Cryptanalysis**

  * **Chosen plaintext**: malicious server chooses the ``nonce``
  * **Precomputed dictionary**: precomputed version of the above
  * **Batch brute force**: chosen plain text on multiple users at once

**Man-in-the-middle attacks**, i.e. intercept and modify requests, are also
prevented regarding the request URIs, but until ``auth-int`` is implemented
entity bodies CAN be modified. So ``POST`` and ``PUT`` methods are still
vulnerable.

Recommendations
===============

Even thought Flask Digest doesn't allow you to store plain text passwords, it's
still a good idea to encrypt the file in some way. Also, if maintaining multiple
realms, make sure their names differ, so that a security breach in one doesn't
affect the other.

To avoid **online dictionary attacks**, i.e. a brute force attack using a list
of common passwords, do not permit your users to choose easy passwords. And to
avoid **spoofing** do not trust any server that doesn't use Quality of
Protection and have the clients also authenticates the server.

Changelog
=========

To check out the complete changelog, click `here`_.

.. _here: https://github.com/vctandrade/flask-digest/releases

What the future holds
=====================

* Logging of possible attacks
* Implementation of ``auth-int``
* Per user/resource authentication
* Support Werkzeug's ``views`` and ``blueprints``