repoze.browserid 0.1

repoze.browserid WSGI middleware tags browsers with an identifier cookie for use in sessioning and otherbrowser-identity-sensitive systems.

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.1 (2008-06-27)

First release.