Update docs re #5's re-opening / #6

Author: danielrichman

docs/source/quickstart.rst

@@ -6,10 +6,17 @@ Using the flask decorator
 
 ::
 
+    import flask
     from flask import Flask
     from raven.flask_glue import AuthDecorator
 
+    # Werkzeug deduces the hostname from the 'Host' or
+    # 'X-Forwarded-Host' headers, so we need a whitelist
+    class R(flask.Request):
+        trusted_hosts = {'your-domain.com', 'www.your-domain.com'}
+
     app = Flask(__name__)
+    app.request_class = R
     app.secret_key = "a secret key"
     auth_decorator = AuthDecorator(desc="My website")
 
@@ -26,10 +33,17 @@ Requiring all flask requests be authenticated
 
 ::
 
+    import flask
     from flask import Flask
     from raven.flask_glue import AuthDecorator
 
+    # Werkzeug deduces the hostname from the 'Host' or
+    # 'X-Forwarded-Host' headers, so we need a whitelist
+    class R(flask.Request):
+        trusted_hosts = {'your-domain.com', 'www.your-domain.com'}
+
     app = Flask(__name__)
+    app.request_class = R
     app.secret_key = "a secret key"
     auth_decorator = AuthDecorator()
 
@@ -98,9 +112,8 @@ Integrating with existing authentication or session management
 
         # checking url, issue, iact and aauth is very important!
         # Werkzeug deduces the hostname from the 'Host' or
-        # 'X-Forwarded-Host' headers. A whitelist is safest, or you
-        # may like to pass a secret in `params`.
-        request.trusted_hosts = {'www.danielrichman.co.uk'}
+        # 'X-Forwarded-Host' headers, so we need a whitelist
+        request.trusted_hosts = {'www.your-domain.com', 'your-domain.com'}
         if r.url != request.base_url:
             print "Bad url"
             abort(400)

docs/source/security.rst

@@ -15,21 +15,26 @@ response:
   Not checking `url` will allow another evil website administrator to replay
   responses produced by Raven log-ins to her website to yours, thereby
   impersonating someone else.
+  (Using params as a token (below) doesn't help, since the attacker can
+  obtain a matching `(cookie, params)` pair from you first, and then ask
+  the victim to authenticate with `params` set to that value.)
 
   Some frameworks, notably Werkzeug, deduce the current hostname from
   the `Host` or `X-Forwarded-Host` headers (with the latter taking
-  precedence). If you are not checking the `Host` header / doing virtual
-  hosting *and* wiping the `X-Forwarded-Host` header in your web server,
-  you need to check the host against a whitelist in your application.
+  precedence).
+  
+  .. seealso::
+        `werkzeug#609 <https://github.com/mitsuhiko/werkzeug/issues/609>`_ and
+        `issue 5 <https://github.com/danielrichman/python-raven/issues/5>`_
 
-  This may be used to whitelist domains in Flask::
+  This technique may be used to whitelist domains in Flask::
 
       class R(flask.Request):
           trusted_hosts = {'www.danielrichman.co.uk'}
       app.request_class = R
 
-  You may forgo checking `url` *if* you instead use a token in `params`
-  as described below.
+  Alternatively, you could sanitise `Host` and `X-Forwarded-Host` in your
+  web-server.
 
 * check `issue` is within an acceptable range of *now*
 
@@ -45,25 +50,24 @@ response:
 Using params as a token
 -----------------------
 
-If checking `url` (above) is a pain, you could:
+You might like to set a random nonce in the Request's `params`, save
+a hashed (with secret salt) or signed copy in a cookie, and check that they
+match in the `Response`.
 
-* generate a random string just before you redirect to Raven
-* set a cookie on the client with that string
-* include that string as `params` in the :class:`ucam_webauth.Request`
-* check that they match in the :class:`ucam_webauth.Response`
+This is *not* a substitute for any of the checks above, but does make the
+`WLS-Response` values in your web server access logs useless.
 
-The principle is similar to that of an CSRF token for submitting forms.
-
-This is what :class:`ucam_webauth.flask_glue.AuthDecorator` does.
+:class:`ucam_webauth.flask_glue.AuthDecorator` does this.
 
 Signing keys
 ------------
 
 The keys used by Raven to sign responses are included with `python-raven`.
 I took care in retrieving them, however you should trust neither me nor the
 method by which you installed this package.
-**You should check that the copies of the certificates you have are
-correct / match the files at the links below**.
+*You should check that the copies of the certificates you have are
+correct / match the files at the links below* (and audit the code you've
+just installed, I guess).
 
 * ``pubkey2`` from `<https://raven.cam.ac.uk/project/keys/>`_
 * ``pubkey901`` from `<https://raven.cam.ac.uk/project/keys/demo_server/>`_

simple_demo/app.py

@@ -10,10 +10,16 @@
 import raven.demoserver
 import raven.flask_glue
 
+import flask
 from flask import Flask, request, render_template, redirect, \
                   url_for, abort, session, flash
+
+class Request(flask.Request):
+    trusted_hosts = {'localhost', '127.0.0.1'}
+
 app = Flask(__name__)
 
+app.request_class = Request
 app.config["SECRET_KEY"] = os.urandom(16)
 
 app.add_template_global(repr, name="repr")

ucam_webauth/flask_glue.py

@@ -281,17 +281,13 @@ def before_request(self):
         * checks if there is a response from the WLS
 
           * checks if the current URL matches that which the WLS said it
-            redirected to (the intention is to avoid an evil admin of another
-            site replaying successful authentications to us, but it isn't
-            perfect unless you're careful with your `Host` and
-            `X-Forwarded-Host` headers)
+            redirected to (avoid an evil admin of another site replaying
+            successful authentications)
           * checks if ``flask.session`` is empty - if so, then we deduce that
             the user has cookies disabled, and must abort immediately with
             403 Forbidden, or we will start a redirect loop
           * checks if `params` matches the token we set (and saved in
             ``flask.session``) when redirecting to Raven
-            (preventing replaying successful authentications from other
-            sites onto ours)
           * checks if the authentication method used is permitted by `aauth`
             and user-interaction respected `iact` - if not, abort with
             400 Bad Request