Fixed #34170 -- Implemented Heal The Breach (HTB) in GzipMiddleware.

2 files changed, 34 insertions, 9 deletions

diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt
index 3f55e36d36..a270b8b774 100644
--- a/docs/ref/middleware.txt
+++ b/docs/ref/middleware.txt
@@ -93,18 +93,33 @@ GZip middleware
 
 .. class:: GZipMiddleware
 
-.. warning::
+    .. attribute:: max_random_bytes
+
+        Defaults to 100. Subclass ``GZipMiddleware`` and override the attribute
+        to change the maximum number of random bytes that is included with
+        compressed responses.
+
+.. note::
 
-    Security researchers recently revealed that when compression techniques
-    (including ``GZipMiddleware``) are used on a website, the site may become
-    exposed to a number of possible attacks. Before using ``GZipMiddleware`` on
-    your site, you should consider very carefully whether you are subject to
-    these attacks. If you're in *any* doubt about whether you're affected, you
-    should avoid using ``GZipMiddleware``. For more details, see the `the BREACH
-    paper (PDF)`_ and `breachattack.com`_.
+    Security researchers revealed that when compression techniques (including
+    ``GZipMiddleware``) are used on a website, the site may become exposed to a
+    number of possible attacks.
 
-    .. _the BREACH paper (PDF): https://www.breachattack.com/resources/BREACH%20-%20SSL,%20gone%20in%2030%20seconds.pdf
+    To mitigate attacks, Django implements a technique called *Heal The Breach
+    (HTB)*. It adds up to 100 bytes (see
+    :attr:`.max_random_bytes`) of random bytes to each response
+    to make the attacks less effective.
+
+    For more details, see the `BREACH paper (PDF)`_, `breachattack.com`_, and
+    the `Heal The Breach (HTB) paper`_.
+
+    .. _BREACH paper (PDF): https://www.breachattack.com/resources/BREACH%20-%20SSL,%20gone%20in%2030%20seconds.pdf
     .. _breachattack.com: https://www.breachattack.com/
+    .. _Heal The Breach (HTB) paper: https://ieeexplore.ieee.org/document/9754554
+
+.. versionchanged:: 4.2
+
+    Mitigation for the BREACH attack was added.
 
 The ``django.middleware.gzip.GZipMiddleware`` compresses content for browsers
 that understand GZip compression (all modern browsers).
diff --git a/docs/releases/4.2.txt b/docs/releases/4.2.txt
index 077762275a..682fce2a53 100644
--- a/docs/releases/4.2.txt
+++ b/docs/releases/4.2.txt
@@ -40,6 +40,16 @@ in the future.
 .. _psycopg: https://www.psycopg.org/psycopg3/
 .. _psycopg library: https://pypi.org/project/psycopg/
 
+Mitigation for the BREACH attack
+--------------------------------
+
+:class:`~django.middleware.gzip.GZipMiddleware` now includes a mitigation for
+the BREACH attack. It will add up to 100 random bytes to gzip responses to make
+BREACH attacks harder. Read more about the mitigation technique in the `Heal
+The Breach (HTB) paper`_.
+
+.. _Heal The Breach (HTB) paper: https://ieeexplore.ieee.org/document/9754554
+
 Minor features
 --------------