Merge pull request #5327 from kenjis/fix-docs-security.rst

docs: improve security.rst

Author: kenjis

user_guide_src/source/libraries/security.rst

@@ -6,7 +6,7 @@ The Security Class contains methods that help protect your site against Cross-Si
 
 .. contents::
     :local:
-    :depth: 2
+    :depth: 3
 
 *******************
 Loading the Library
@@ -26,8 +26,11 @@ Cross-site request forgery (CSRF)
 .. warning:: The CSRF Protection is only available for **POST/PUT/PATCH/DELETE** requests.
     Requests for other methods are not protected.
 
+Config for CSRF
+===============
+
 CSRF Protection Methods
-=======================
+-----------------------
 
 By default, the Cookie based CSRF Protection is used. It is
 `Double Submit Cookie <https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#double-submit-cookie>`_
@@ -41,6 +44,49 @@ You can set to use the Session based CSRF protection by editing the following co
 
     public $csrfProtection = 'session';
 
+Token Randomization
+-------------------
+
+To mitigate compression side-channel attacks like `BREACH`_, and prevent an attacker from guessing the CSRF tokens, you can configure token randomization (off by default).
+
+If you enable it, a random mask is added to the token and used to scramble it.
+
+.. _`BREACH`: https://en.wikipedia.org/wiki/BREACH
+
+You can enable it by editing the following config parameter value in
+**app/Config/Security.php**::
+
+    public $tokenRandomize = true;
+
+Token Regeneration
+------------------
+
+Tokens may be either regenerated on every submission (default) or
+kept the same throughout the life of the CSRF cookie. The default
+regeneration of tokens provides stricter security, but may result
+in usability concerns as other tokens become invalid (back/forward
+navigation, multiple tabs/windows, asynchronous actions, etc). You
+may alter this behavior by editing the following config parameter value in
+**app/Config/Security.php**::
+
+    public $regenerate  = true;
+
+Redirection on Failure
+----------------------
+
+When a request fails the CSRF validation check, it will redirect to the previous page by default,
+setting an ``error`` flash message that you can display to the end user with the following code in your view::
+
+    <?= session()->getFlashdata('error') ?>
+
+This provides a nicer experience
+than simply crashing. This can be turned off by editing the following config parameter value in
+**app/Config/Security.php**::
+
+    public $redirect = false;
+
+Even when the redirect value is ``true``, AJAX calls will not redirect, but will throw an error.
+
 Enable CSRF Protection
 ======================
 
@@ -79,20 +125,6 @@ It is also possible to enable the CSRF filter only for specific methods::
         'post' => ['csrf'],
     ];
 
-Token Randomization
-===================
-
-To mitigate compression side-channel attacks like `BREACH`_, and prevent an attacker from guessing the CSRF tokens, you can configure token randomization (default off).
-
-If you enable it, a random mask is added to the token and used to scramble it.
-
-.. _`BREACH`: https://en.wikipedia.org/wiki/BREACH
-
-You can enable it by editing the following config parameter value in
-**app/Config/Security.php**::
-
-    public $tokenRandomize = true;
-
 HTML Forms
 ==========
 
@@ -134,31 +166,6 @@ The order of checking the availability of the CSRF token is as follows:
 2. HTTP header
 3. ``php://input`` (JSON request) - bear in mind that this approach is the slowest one since we have to decode JSON and then re-encode it
 
-Token Regeneration
-===================
-
-Tokens may be either regenerated on every submission (default) or
-kept the same throughout the life of the CSRF cookie. The default
-regeneration of tokens provides stricter security, but may result
-in usability concerns as other tokens become invalid (back/forward
-navigation, multiple tabs/windows, asynchronous actions, etc). You
-may alter this behavior by editing the following config parameter value in
-**app/Config/Security.php**::
-
-    public $regenerate  = true;
-
-Redirection on Failure
-======================
-
-When a request fails the CSRF validation check, it will redirect to the previous page by default,
-setting an ``error`` flash message that you can display to the end user. This provides a nicer experience
-than simply crashing. This can be turned off by editing the following config parameter value in
-**app/Config/Security.php**::
-
-    public $redirect = false;
-
-Even when the redirect value is ``true``, AJAX calls will not redirect, but will throw an error.
-
 *********************
 Other Helpful Methods
 *********************