From 3a2bf006f27231cd3c225383828148abd8fc797a Mon Sep 17 00:00:00 2001 From: Mark Story Date: Tue, 16 May 2017 23:43:29 -0400 Subject: [PATCH 1/3] Document CSRF middleware. Refs cakephp/cakephp#10561 --- en/appendices/3-5-migration-guide.rst | 4 ++ en/controllers/components/cookie.rst | 4 ++ en/controllers/components/csrf.rst | 4 ++ en/controllers/middleware.rst | 55 +++++++++++++++++++++++++++ 4 files changed, 67 insertions(+) diff --git a/en/appendices/3-5-migration-guide.rst b/en/appendices/3-5-migration-guide.rst index c3d9bc0465..83a732492a 100644 --- a/en/appendices/3-5-migration-guide.rst +++ b/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 diff --git a/en/controllers/components/cookie.rst b/en/controllers/components/cookie.rst index d6ce93092c..7906e1639f 100644 --- a/en/controllers/components/cookie.rst +++ b/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 =================== diff --git a/en/controllers/components/csrf.rst b/en/controllers/components/csrf.rst index 8d0526b317..4053fe24a3 100644 --- a/en/controllers/components/csrf.rst +++ b/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 ======================= diff --git a/en/controllers/middleware.rst b/en/controllers/middleware.rst index 821a2962d1..0610140896 100644 --- a/en/controllers/middleware.rst +++ b/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,59 @@ 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'); + +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. + +.. versionadded:: 3.5.0 + The ``CsrfProtectionMiddleware`` was added in 3.5.0 + .. _adding-http-stack: Adding the new HTTP Stack to an Existing Application From 16de010035d198884863b3cd704529bfeb36444f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc=20W=C3=BCrth?= Date: Thu, 18 May 2017 11:50:27 +0200 Subject: [PATCH 2/3] Reformat CSRF example --- en/controllers/middleware.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/en/controllers/middleware.rst b/en/controllers/middleware.rst index 0610140896..5d4468437a 100644 --- a/en/controllers/middleware.rst +++ b/en/controllers/middleware.rst @@ -333,7 +333,10 @@ 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 = [ ... ]; + + $options = [ + // ... + ]; $csrf = new CsrfProtectionMiddleware($options); $middleware->add($csrf); From 42b1ebf70a7d4f381aa1288e32bd80fa614f566b Mon Sep 17 00:00:00 2001 From: Mark Story Date: Thu, 18 May 2017 21:41:32 -0400 Subject: [PATCH 3/3] Move versionadded. --- en/controllers/middleware.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/en/controllers/middleware.rst b/en/controllers/middleware.rst index 5d4468437a..60520e331f 100644 --- a/en/controllers/middleware.rst +++ b/en/controllers/middleware.rst @@ -356,6 +356,10 @@ 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 --------------------------- @@ -377,9 +381,6 @@ 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. -.. versionadded:: 3.5.0 - The ``CsrfProtectionMiddleware`` was added in 3.5.0 - .. _adding-http-stack: Adding the new HTTP Stack to an Existing Application