You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by rn...@apache.org on 2015/08/08 19:46:55 UTC
documentation commit: updated refs/heads/master to 13e9832
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 <rn...@apache.org>
Authored: Sat Aug 8 13:41:59 2015 +0100
Committer: Robert Newson <rn...@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
------------------------------