support Origin: null in csrf_trusted_origins and check_origin=False

1 files changed, 6 insertions, 1 deletions

diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 9d45dfb6a..f1bb37c69 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -885,7 +885,12 @@ is the current host, however additional origins may be configured by setting
 are non-standard). If a host in the list of domains starts with a ``.`` then
 that will allow all subdomains as well as the domain without the ``.``.  If no
 ``Referer`` or ``Origin`` header is present in an HTTPS request, the CSRF check
-will fail unless ``allow_no_origin`` is set.
+will fail unless ``allow_no_origin`` is set. The special ``Origin: null`` can
+be allowed by adding ``null`` to the ``pyramid.csrf_trusted_origins`` list.
+
+It is possible to opt out of checking the origin by passing
+``check_origin=False``. This is useful if the :term:`CSRF storage policy` is
+known to be secure such that the token cannot be easily used by an attacker.
 
 If CSRF checks fail then a :class:`pyramid.exceptions.BadCSRFToken` or
 :class:`pyramid.exceptions.BadCSRFOrigin` exception will be raised. This