Metadata-Version: 1.0
Name: repoze.browserid
Version: 0.2
Summary: repoze.browserid WSGI middleware tags browsers with an identifier cookie for use in sessioning and otherbrowser-identity-sensitive systems.
Home-page: http://www.repoze.org
Author: Agendaless Consulting
Author-email: repoze-dev@lists.repoze.org
License: BSD-derived (http://www.repoze.org/LICENSE.txt)
Description: *************************
        repoze.browserid Overview
        *************************
        
        Browser id middleware for WSGI, loosely based on the Zope 2 concept
        of browser ids, which are cookies which represent a browser, for use
        by sessioning libraries.
        
        Browser Id
        ==========
        
        The concept of a browser id is simple: every request to an application
        which is fronted by the browser id middleware will include a browser
        id within the WSGI environment.  A browser id is an opaque string that
        is guaranteed to be unique within the set of all individual user
        agents which visit the application over the lifetime of that
        application.  This string is most useful as a key in a sessioning
        system.
        
        If a user agent contacts the application but does not supply a browser
        id, one will be manufactured for the current request, and a Set-Cookie
        header will be returned to the user agent, which it will (hopefully)
        return on subsequent requests.
        
        If the user agent does supply a cookie containing a browser id but the
        cookie value is tampered with by the user or by some middleman, it
        will be rejected, and a new browser id will be constructed for the
        current request.
        
        We set the browser id value as ``repoze.browserid`` in the WSGI environ
        before we call the downstream application.  It is a 40-character
        string.
        
        Uniqueness
        ==========
        
        The browser id machinery guarantees uniqueness of browser ids by
        composing the browser id out of three coponents: a random component, a
        time component, and a component representing the pid of the process
        serving the application.  The "true" randomness of the random
        component is guaranteed within a one-second window by specialized
        code, which, when coupled with the time component, guarantees good
        uniqueness of browser ids.
        
        Tamper Checking and Varying
        ===========================
        
        The cookie set by the browser id middleware is forgery-resistant.
        
        The cookie value of Set-Cookie headers created by the middleware is
        composed of three parts: the browser id (a unique 40-character
        string), a delimiter ("!"), and an HMAC of the browser id serialized
        as a 32-character string.
        
        When configuring the browserid middleware, you must supply a secret
        key.  The middleware uses the secret key and "vary" values to compose
        the "tamper key" when creating a browser id.  The tamper key is
        composed of the secret key concatenated with values provided in the
        environment.  Varying allows a configurer to vary the tamper key on,
        e.g. ``REMOTE_ADDR`` if he believes that the same browser id should
        always be sent from the same IP address, or ``HTTP_USER_AGENT`` if he
        believes it should always come from the same user agent, or some
        arbitrary combination thereof made out of environ keys.
        
        When the cookie is composed, An HMAC of the browser id is computed
        using the tamper key.  The HMAC is appended to the browser id after a
        delimiter character.  When a browser id is retrieved from a user
        agent, the HMAC portion is separated from the browser id and a new
        HMAC using the same secret key and vary values is computed.  If the
        cookie HMAC matches the computed HMAC, the cookie hasn't been tampered
        with, and the browser id portion of the cookie becomes the browser id
        for the current request.  If they differ, a new browser id is
        generated.
        
        Configuration
        =============
        
        Configuration via Python
        ------------------------
        
        Wire up the middleware in your application::
        
        from repoze.browserid.middleware import BrowserIdMiddleware
        middleware = BrowserIdMiddleware(app, secret_key='foo',
        cookie_name='repoze.browserid',
        cookie_path='/',
        cookie_domain=None,
        cookie_lifetime=None,
        cookie_secure=None,
        vary=())
        
        
        Configuration via Paste
        ------------------------
        
        Use the ``egg:repoze.browserid#browserid`` entry point in your Paste
        configuration, eg.::
        
        [filter:browserid]
        use = egg:repoze.browserid#browserid
        secret_key = foo
        
        [pipeline:main]
        pipeline = egg:Paste#cgitb
        browserid
        myapp
        
        
        Reporting Bugs / Development Versions
        =====================================
        
        Visit http://bugs.repoze.org to report bugs.  Visit
        http://svn.repoze.org to download development or tagged versions.
        
        
        0.2 (2010-01-14)
        ----------------
        
        - Removed 'ez_setup' furniture:  setuptools is ubiquitous enough now.
        
        - Silenced deprecation warning for import of 'sha' module under Python 2.6.
        
        - 100% test coverage.
        
        
        0.1 (2008-06-27)
        ----------------
        
        -  First release.
        
        
Keywords: application server wsgi middleware sessions browserid
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware
