Fixed #15727 -- Added Content Security Policy (CSP) support.

This initial work adds a pair of settings to configure specific CSP
directives for enforcing or reporting policy violations, a new
`django.middleware.csp.ContentSecurityPolicyMiddleware` to apply the
appropriate headers to responses, and a context processor to support CSP
nonces in templates for safely inlining assets.

Relevant documentation has been added for the 6.0 release notes,
security overview, a new how-to page, and a dedicated reference section.

Thanks to the multiple reviewers for their precise and valuable feedback.

Co-authored-by: Natalia <124304+nessita@users.noreply.github.com>

1 files changed, 100 insertions, 0 deletions

diff --git a/docs/howto/csp.txt b/docs/howto/csp.txt
new file mode 100644
index 0000000000..756f815bf2
--- /dev/null
+++ b/docs/howto/csp.txt
@@ -0,0 +1,100 @@
+===========================================
+How to use Django's Content Security Policy
+===========================================
+
+.. _csp-config:
+
+Basic config
+============
+
+To enable Content Security Policy (CSP) in your Django project:
+
+1. Add the CSP middleware to your :setting:`MIDDLEWARE` setting::
+
+    MIDDLEWARE = [
+        # ...
+        "django.middleware.csp.ContentSecurityPolicyMiddleware",
+        # ...
+    ]
+
+2. Configure the CSP policies in your ``settings.py`` using either
+   :setting:`SECURE_CSP` or :setting:`SECURE_CSP_REPORT_ONLY` (or both). The
+   :ref:`CSP Settings docs <csp-settings>` provide more details about the
+   differences between these two::
+
+    from django.utils.csp import CSP
+
+    # To enforce a CSP policy:
+    SECURE_CSP = {
+        "default-src": [CSP.SELF],
+        # Add more directives to be enforced.
+    }
+
+    # Or for report-only mode:
+    SECURE_CSP_REPORT_ONLY = {
+        "default-src": [CSP.SELF],
+        # Add more directives as needed.
+        "report-uri": "/path/to/reports-endpoint/",
+    }
+
+.. _csp-nonce-config:
+
+Nonce config
+============
+
+To use nonces in your CSP policy, beside the basic config, you need to:
+
+1. Include the :attr:`~django.utils.csp.CSP.NONCE` placeholder value in the CSP
+   settings. This only applies to ``script-src`` or ``style-src`` directives::
+
+    from django.utils.csp import CSP
+
+    SECURE_CSP = {
+        "default-src": [CSP.SELF],
+        # Allow self-hosted scripts and script tags with matching `nonce` attr.
+        "script-src": [CSP.SELF, CSP.NONCE],
+        # Example of the less secure 'unsafe-inline' option.
+        "style-src": [CSP.SELF, CSP.UNSAFE_INLINE],
+    }
+
+2. Add the :func:`~django.template.context_processors.csp` context processor to
+   your :setting:`TEMPLATES` setting. This makes the generated nonce value
+   available in the Django templates as the ``csp_nonce`` context variable::
+
+    TEMPLATES = [
+        {
+            "BACKEND": "django.template.backends.django.DjangoTemplates",
+            "OPTIONS": {
+                "context_processors": [
+                    # ...
+                    "django.template.context_processors.csp",
+                ],
+            },
+        },
+    ]
+
+3. In your templates, add the ``nonce`` attribute to the relevant inline
+   ``<style>`` or ``<script>`` tags, using the ``csp_nonce`` context variable:
+
+   .. code-block:: html+django
+
+      <style nonce="{{ csp_nonce }}">
+        /* These inline styles will be allowed. */
+      </style>
+
+      <script nonce="{{ csp_nonce }}">
+        // This inline JavaScript will be allowed.
+      </script>
+
+.. admonition:: Caching and Nonce Reuse
+
+   The :class:`~django.middleware.csp.ContentSecurityPolicyMiddleware`
+   automatically handles generating a unique nonce and inserting the
+   appropriate ``nonce-<value>`` source expression into the
+   ``Content-Security-Policy`` (or ``Content-Security-Policy-Report-Only``)
+   header when the nonce is used in a template.
+
+   To ensure correct behavior, make sure both the HTML and the header are
+   generated within the same request and not served from cache. See the
+   reference documentation on :ref:`csp-nonce` for implementation details and
+   important caching considerations.