couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rnew...@apache.org
Subject documentation commit: updated refs/heads/master to 13e9832
Date Sat, 08 Aug 2015 17:46:55 GMT
Repository: couchdb-documentation
Updated Branches:
  refs/heads/master 2008f90ef -> 13e98327e


Document CSRF protection

COUCHDB-2762


Project: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/commit/13e98327
Tree: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/tree/13e98327
Diff: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/diff/13e98327

Branch: refs/heads/master
Commit: 13e98327e9b85a9b48ceb657ea4cbde90b65a0bf
Parents: 2008f90
Author: Robert Newson <rnewson@apache.org>
Authored: Sat Aug 8 13:41:59 2015 +0100
Committer: Robert Newson <rnewson@apache.org>
Committed: Sat Aug 8 18:46:49 2015 +0100

----------------------------------------------------------------------
 src/config/http.rst | 79 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/13e98327/src/config/http.rst
----------------------------------------------------------------------
diff --git a/src/config/http.rst b/src/config/http.rst
index 90ce031..dabc267 100644
--- a/src/config/http.rst
+++ b/src/config/http.rst
@@ -507,6 +507,85 @@ Cross-Origin Resource Sharing
         - `COS tutorial <http://www.html5rocks.com/en/tutorials/cors/>`_
         - `XHR with CORS <http://hacks.mozilla.org/2009/07/cross-site-xmlhttprequest-with-cors/>`_
 
+Cross-site Request Forgery protection
+=====================================
+
+.. config:section:: csrf :: Cross-site Request Forgery
+
+    .. versionadded:: 2.0 added CSRF protection, see JIRA :issue:`2762`
+
+    `CSRF`, or "Cross-site Request Forgery" is a web-based exploit
+    where an attacker can cause a user agent to make an authenticated
+    form post or XHR request against a foreign site without their
+    consent. The attack works because a user agent will send any
+    cookies it has along with the request. The attacker does not see
+    the response, nor can they see the user agent's cookies. The
+    attacker hopes to gain indirectly, e.g, by posting to a password
+    reset form or cause damage by issuing a database delete request.
+
+    To prevent this, CouchDB can require a matching request header
+    before processing any request. The correct value of this header is
+    unknown to the attacker and so their attack fails.
+
+    To enable CSRF protection, add the custom request header
+    `X-CouchDB-CSRF` wih value `true` to any request. The response will
+    return a cookie named `CouchDB-CSRF`.
+
+    If CouchDB sees the `CouchDB-CSRF` cookie in a request it expects
+    the same value to be sent in the `X-CouchDB-CSRF` header. If the
+    header is missing or does not match the cookie, a `403 Forbidden`
+    response is generated. Additionally, CouchDB logs a warning, to
+    allow administrators to detect potential CSRF attacks in progress.
+
+    Careful clients can verify whether their requests were protected
+    from CSRF by examining the `X-CouchDB-CSRF-Valid` response
+    header. It should be present and its value should be `true`.
+
+    CSRF cookies expire after a configurable period of time but will
+    automatically be refreshed by CouchDB on subsequent requests. An
+    expired CSRF cookie is equivalent to not sending the cookie (and
+    thus the request will not be protected from CSRF).
+
+    The following pseudo-code shows how to use the CSRF protection in
+    an opportunistic fashion, gracefully degrading when the mechanism
+    is not available.
+
+    .. code-block:: javascript
+
+        if (hasCookie("CouchDB-CSRF")) {
+          setRequestHeader("X-CouchDB-CSRF", cookieValue("CouchDB-CSRF"));
+        } else {
+          setRequestHeader("X-CouchDB-CSRF", "true");
+        }
+
+    .. config:option:: mandatory
+
+        CouchDB can insist on CSRF Cookie/Header for all requests
+        (except those to the welcome handler, /, so you can acquire a
+        cookie) with this setting. The default is false::
+
+            [csrf]
+            mandatory = true
+
+    .. config:option:: secret
+
+        All CSRF cookies are signed by the server using this value. A
+        random value will be chosen if you don't specify it, but we
+        recommend setting it yourself, especially if you are running a
+        cluster of more than one node. The secret must match on all
+        nodes in a cluster to avoid sadness::
+
+            [csrf]
+            secret = b6fdf2e8213a36dbcca34e61e4000967
+
+    .. config:option:: timeout
+
+        All CSRF cookies expire after `timeout` seconds. The default
+        is an hour::
+
+            [csrf]
+            timeout = 3600
+
 Per Virtual Host Configuration
 ------------------------------
 


Mime
View raw message