Metadata-Version: 1.1
Name: flask-cookie-decode
Version: 0.3.0
Summary: Tools for debugging and working with the built-in Flask session cookie
Home-page: https://github.com/wgwz/flask-cookie-decode
Author: Kyle Lawlor
Author-email: klawlor419@gmail.com
License: MIT license
Description: flask-cookie-decode
        ###################
        
        .. image:: https://travis-ci.com/wgwz/flask-cookie-decode.svg?branch=master
            :target: https://travis-ci.com/wgwz/flask-cookie-decode
        
        .. contents::
        
        .. section-numbering::
        
        Purpose
        =======
        
        Adds a ``cookie`` command to the built-in Flask CLI which will provide various
        tools for debugging the secure session cookie that Flask uses by default.
        
        Current available commands
        --------------------------
        
        1. `flask cookie decode`: decodes and verifies the signature of the session cookie
        
        Background
        ==========
        
        By default the Flask session uses a signed cookie to store its data. The Flask
        application signs the cookie using its ``SECRET_KEY``. This provides the Flask
        application a way to detect any tampering to the session data. If the application
        is indeed using a secret key and secure hashing algorithm, the session signature
        will be unique to application. 
        
        For more on the topic of the Flask session see these references:
        
        * `How Secure Is The Flask User Session?`_
        * `Quickstart for Flask Sessions`_
        * `API Docs for Flask Sessions`_
        
        .. _`How Secure Is The Flask User Session?`: https://blog.miguelgrinberg.com/post/how-secure-is-the-flask-user-session
        .. _`Quickstart for Flask Sessions`: http://flask.pocoo.org/docs/1.0/quickstart/#sessions
        .. _`API Docs for Flask Sessions`: http://flask.pocoo.org/docs/1.0/api/#sessions
        
        Disclaimer: Keep your SECRET_KEY, secret!
        -----------------------------------------
        
        If you expose this key your application becomes vulnerable to session replay
        attacks. `Here is an example`_ where an application exposed the ``SECRET_KEY``
        during 404 errors. The example also illustrates how session replay works.
        
        By default Flask does not expose the ``SECRET_KEY`` anywhere. It is up to you
        the developer to keep it that way!
        
        .. _`Here is an example`: https://terryvogelsang.tech/MITRECTF2018-my-flask-app/
        
        Usage
        =====
        
        Installation
        ------------
        
        .. code-block:: bash
        
            $ pip install flask-cookie-decode
        
        Extracting the cookie using browser tools
        -----------------------------------------
        
        .. image:: https://raw.githubusercontent.com/wgwz/flask-cookie-decode/master/docs/cookie.png
            :alt: Finding the cookie in browser tools
            :width: 100%
            :align: center
        
        Example Flask app
        -----------------
        
        See `examples/app.py <https://github.com/wgwz/flask-cookie-decode/blob/master/examples/app.py>`_:
        
        .. code-block:: python 
        
            from flask import Flask, jsonify, session, request
            from flask_cookie_decode import CookieDecode
        
            app = Flask(__name__)
            app.config.update({'SECRET_KEY': 'jlghasdghasdhgahsdg'})
            cookie = CookieDecode()
            cookie.init_app(app)
        
            @app.route('/')
            def index():
                a = request.args.get('a')
                session['a'] = a
                return jsonify(dict(session))
        
        Examples using the CLI:
        -----------------------
        
        1. A cookie with a valid signature:
        
        .. code-block:: bash
        
            $ export FLASK_APP=app.py
            $ flask cookie decode eyJhIjoiYXNkYXNkamtqYXNkIn0.XCkk1Q.tTPu2Zhvn9KxgkP35ERAgyd8MzA
            TrustedCookie(contents={'a': 'asdasdjkjasd'}, expiration='2019-01-30T20:04:37')
        
        2. A cookie with an invalid signature:
        
        .. code-block:: bash
        
            $ export FLASK_APP=app.py
            $ flask cookie decode eyJhIjoiYXNkYXNkamtqYXNkIn0.XCkk1Q.tTPu2Zhvn9KxgkP35ERAgyd8MzA
            UntrustedCookie(contents={'a': 'asdasdjkjasd'}, expiration='2019-01-30T20:04:37')
        
        3. An expired cookie:
        
        .. code-block:: bash
        
            $ export FLASK_APP=app.py
            $ flask cookie decode eyJhIjoiYXNkYXNkamtqYXNkIn0.XCkk1Q.tTPu2Zhvn9KxgkP35ERAgyd8MzA
            ExpiredCookie(contents={'a': 'asdasdjkjasd'}, expiration='2019-01-30T20:04:37')
        
        Documentation
        =============
        
        `Docs <https://flask-cookie-decode.readthedocs.io/en/latest/>`_
        
        License
        =======
        
        `MIT <https://github.com/wgwz/flask-cookie-decode/blob/master/LICENSE>`_.
        
        
        =======
        History
        =======
        
        .. towncrier release notes start
        
        Flask_Cookie_Decode 0.3.0 (2019-01-05)
        ======================================
        
        Bugfixes
        --------
        
        - In all previous releases the CLI with the ``--timestamp`` CLI flag was actually
          returning the timestamp when the cookie was signed. *Not* the timestamp when the
          cookie expires, as it should have been doing. 
        
          In all previous releases there was no error handling for expired cookies. This
          release now returns a ``ExpiredCookie`` when it is detected. (#1)
        
        
        Improved Documentation
        ----------------------
        
        - Updates the documentation to include some more details about the way the 
          Flask session works, and things you should be looking out for from a security
          perspective. The documentation also reflects the latest in terms of the way
          the CLI works. (#1)
        
        
        0.1.0 (2018-12-29)
        ==================
        
        * First release on PyPI.
        
Keywords: flask_cookie_decode
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
