Document CSRF middleware.

en/appendices/3-5-migration-guide.rst

@@ -14,6 +14,8 @@ features will continue to function until 4.0.0 after which they will be removed.
   ``Cake\Http\Cookie\CookieCollection`` instead.
 * ``Cake\View\Helper\RssHelper`` is deprecated. Due to infrequent use the
   RssHelper is deprecated.
+* ``Cake\Controller\Component\CsrfComponent`` is deprecated. Use
+  :ref:`csrf-middleware` instead.
 
 Deprecated Combined Get/Set Methods
 -----------------------------------
@@ -99,6 +101,8 @@ New Features
   :ref:`security-header-middleware` for more information.
 * New middleware has been added to transparently encrypt cookie data. See
   :ref:`encrypted-cookie-middleware` for more information.
+* New middleware has been added to make protecting against CSRF easier. See
+  :ref:`csrf-middleware` for more information.
 * ``Cake\Event\EventManager::on()`` and ``off()`` methods are now chainable
   making it simpler to set multiple events at once.
 * ``Cake\Validation\Validator::regex()`` was added for a more convenient way

en/controllers/components/cookie.rst

@@ -8,6 +8,10 @@ Cookie
 The CookieComponent is a wrapper around the native PHP ``setcookie()`` method. It
 makes it easier to manipulate cookies, and automatically encrypt cookie data.
 
+.. deprecated:: 3.5.0
+    You should use :ref:`encrypted-cookie-middleware` instead of
+    ``CookieComponent``.
+
 Configuring Cookies
 ===================
 

en/controllers/components/csrf.rst

@@ -27,6 +27,10 @@ component will throw a
     :php:class:`Cake\\Network\\Exception\\ForbiddenException` to
     :php:class:`Cake\\Network\\Exception\\InvalidCsrfTokenException`.
 
+.. deprecated:: 3.5.0
+    You should use :ref:`csrf-middleware` instead of
+    ``CsrfComponent``.
+
 Using the CsrfComponent
 =======================
 

en/controllers/middleware.rst

@@ -23,6 +23,8 @@ CakePHP provides several middleware out of the box:
   security related headers like ``X-Frame-Options`` to responses.
 * ``Cake\Http\Middleware\EncryptedCookieMiddleware`` makes it easy to add
   security related headers like ``X-Frame-Options`` to responses.
+* ``Cake\Http\Middleware\CsrfProtectionMiddleware`` adds CSRF protection to your
+  application.
 
 .. _using-middleware:
 
@@ -322,6 +324,63 @@ backwards compatible with ``CookieComponent`` from earlier versions of CakePHP.
 .. versionadded:: 3.5.0
     The ``EncryptedCookieMiddleware`` was added in 3.5.0
 
+.. _csrf-middleware:
+
+Cross Site Request Forgery (CSRF) Middleware
+============================================
+
+CSRF protection can be applied to your entire application, or to specific scopes
+by applying the ``CsrfProtectionMiddleware`` to your middleware stack::
+
+    use Cake\Http\Middleware\CsrfProtectionMiddleware;
+
+    $options = [
+        // ...
+    ];
+    $csrf = new CsrfProtectionMiddleware($options);
+
+    $middleware->add($csrf);
+
+Options can be passed into the middleware's constructor.
+The available configuration options are:
+
+- ``cookieName`` The name of the cookie to send. Defaults to ``csrfToken``.
+- ``expiry`` How long the CSRF token should last. Defaults to browser session.
+- ``secure`` Whether or not the cookie will be set with the Secure flag. That is,
+  the cookie will only be set on a HTTPS connection and any attempt over normal HTTP
+  will fail. Defaults to ``false``.
+- ``field`` The form field to check. Defaults to ``_csrfToken``. Changing this
+  will also require configuring FormHelper.
+
+When enabled, you can access the current CSRF token on the request object::
+
+    $token = $this->request->getParam('_csrfToken');
+
+.. versionadded:: 3.5.0
+    The ``CsrfProtectionMiddleware`` was added in 3.5.0
+
+
+Integration with FormHelper
+---------------------------
+
+The ``CsrfProtectionMiddleware`` integrates seamlessly with ``FormHelper``. Each
+time you create a form with FormHelper, it will insert a hidden field containing
+the CSRF token.
+
+.. note::
+
+    When using CSRF protection you should always start your forms with the
+    FormHelper. If you do not, you will need to manually create hidden inputs in
+    each of your forms.
+
+CSRF Protection and AJAX Requests
+----------------------------------
+
+In addition to request data parameters, CSRF tokens can be submitted through
+a special ``X-CSRF-Token`` header. Using a header often makes it easier to
+integrate a CSRF token with JavaScript heavy applications, or XML/JSON based API
+endpoints.
+
 .. _adding-http-stack:
 
 Adding the new HTTP Stack to an Existing Application