diff --git a/user_guide_src/source/outgoing/csp.rst b/user_guide_src/source/outgoing/csp.rst new file mode 100644 index 000000000000..0761f289a611 --- /dev/null +++ b/user_guide_src/source/outgoing/csp.rst @@ -0,0 +1,129 @@ +.. _content-security-policy: + +####################### +Content Security Policy +####################### + +.. contents:: + :local: + :depth: 2 + +******************************** +What is Content Security Policy? +******************************** + +One of the best protections you have against XSS attacks is to implement a Content +Security Policy (CSP) on the site. This requires you to specify and authorize each +source of content that is included in your site's HTML, including images, +stylesheets, JavaScript files, and so on. The browser will reject content from +sources that are not explicitly approved. This authorization is defined within +the response's ``Content-Security-Policy`` header and offers various configuration +options. + +This sounds complex, and on some sites, can definitely be challenging. For many simple sites, though, where all content +is served by the same domain (http://example.com), it is very simple to integrate. + +As this is a complex subject, this user guide will not go over all of the details. For more information, you should +visit the following sites: + +* `Content Security Policy main site `_ +* `W3C Specification `_ +* `Introduction at HTML5Rocks `_ +* `Article at SitePoint `_ + +************** +Turning CSP On +************** + +.. important:: The :ref:`Debug Toolbar ` may use Kint, which + outputs inline scripts. Therefore, when CSP is turned on, CSP nonce is + automatically output for the Debug Toolbar. However, if you are not using + CSP nonce, this will change the CSP header to something you do not intend, + and it will behave differently than in production; if you want to verify CSP + behavior, turn off the Debug Toolbar. + +By default, support for this is off. To enable support in your application, edit the ``CSPEnabled`` value in +**app/Config/App.php**: + +.. literalinclude:: csp/011.php + +When enabled, the response object will contain an instance of ``CodeIgniter\HTTP\ContentSecurityPolicy``. The +values set in **app/Config/ContentSecurityPolicy.php** are applied to that instance, and if no changes are +needed during runtime, then the correctly formatted header is sent and you're all done. + +With CSP enabled, two header lines are added to the HTTP response: a **Content-Security-Policy** header, with +policies identifying content types or origins that are explicitly allowed for different +contexts, and a **Content-Security-Policy-Report-Only** header, which identifies content types +or origins that will be allowed but which will also be reported to the destination +of your choice. + +Our implementation provides for a default treatment, changeable through the ``reportOnly()`` method. +When an additional entry is added to a CSP directive, as shown below, it will be added +to the CSP header appropriate for blocking or preventing. That can be overridden on a per +call basis, by providing an optional second parameter to the adding method call. + +********************* +Runtime Configuration +********************* + +If your application needs to make changes at run-time, you can access the instance at ``$this->response->getCSP()`` in your controllers. The +class holds a number of methods that map pretty clearly to the appropriate header value that you need to set. +Examples are shown below, with different combinations of parameters, though all accept either a directive +name or an array of them: + +.. literalinclude:: csp/012.php + +The first parameter to each of the "add" methods is an appropriate string value, +or an array of them. + +The ``reportOnly()`` method allows you to specify the default reporting treatment +for subsequent sources, unless over-ridden. For instance, you could specify +that youtube.com was allowed, and then provide several allowed but reported sources: + +.. literalinclude:: csp/013.php + +************** +Inline Content +************** + +It is possible to set a website to not protect even inline scripts and styles on its own pages, since this might have +been the result of user-generated content. To protect against this, CSP allows you to specify a nonce within the +`` + +.. warning:: If an attacker injects a string like `` + + // Becomes + + + // OR + diff --git a/user_guide_src/source/outgoing/response/011.php b/user_guide_src/source/outgoing/csp/011.php similarity index 100% rename from user_guide_src/source/outgoing/response/011.php rename to user_guide_src/source/outgoing/csp/011.php index bfac115c6bd3..193105592586 100644 --- a/user_guide_src/source/outgoing/response/011.php +++ b/user_guide_src/source/outgoing/csp/011.php @@ -6,7 +6,7 @@ class App extends BaseConfig { - public bool $CSPEnabled = true; - // ... + + public bool $CSPEnabled = true; } diff --git a/user_guide_src/source/outgoing/response/012.php b/user_guide_src/source/outgoing/csp/012.php similarity index 100% rename from user_guide_src/source/outgoing/response/012.php rename to user_guide_src/source/outgoing/csp/012.php diff --git a/user_guide_src/source/outgoing/response/013.php b/user_guide_src/source/outgoing/csp/013.php similarity index 100% rename from user_guide_src/source/outgoing/response/013.php rename to user_guide_src/source/outgoing/csp/013.php diff --git a/user_guide_src/source/outgoing/index.rst b/user_guide_src/source/outgoing/index.rst index 2b95096511c3..a08a2e52a125 100644 --- a/user_guide_src/source/outgoing/index.rst +++ b/user_guide_src/source/outgoing/index.rst @@ -16,5 +16,6 @@ View components are used to build what is returned to the user. table response api_responses + csp localization alternative_php diff --git a/user_guide_src/source/outgoing/response.rst b/user_guide_src/source/outgoing/response.rst index 078d9d11042a..d5785756d461 100644 --- a/user_guide_src/source/outgoing/response.rst +++ b/user_guide_src/source/outgoing/response.rst @@ -199,122 +199,6 @@ to the ``Cache-Control`` header. You are free to set all of the options exactly situation. While most of the options are applied to the ``Cache-Control`` header, it intelligently handles the ``etag`` and ``last-modified`` options to their appropriate header. -.. _content-security-policy: - -Content Security Policy -======================= - -One of the best protections you have against XSS attacks is to implement a Content Security Policy on the site. -This forces you to whitelist every single source of content that is pulled in from your site's HTML, -including images, stylesheets, javascript files, etc. The browser will refuse content from sources that don't meet -the whitelist. This whitelist is created within the response's ``Content-Security-Policy`` header and has many -different ways it can be configured. - -This sounds complex, and on some sites, can definitely be challenging. For many simple sites, though, where all content -is served by the same domain (http://example.com), it is very simple to integrate. - -As this is a complex subject, this user guide will not go over all of the details. For more information, you should -visit the following sites: - -* `Content Security Policy main site `_ -* `W3C Specification `_ -* `Introduction at HTML5Rocks `_ -* `Article at SitePoint `_ - -Turning CSP On --------------- - -.. important:: The :ref:`Debug Toolbar ` may use Kint, which - outputs inline scripts. Therefore, when CSP is turned on, CSP nonce is - automatically output for the Debug Toolbar. However, if you are not using - CSP nonce, this will change the CSP header to something you do not intend, - and it will behave differently than in production; if you want to verify CSP - behavior, turn off the Debug Toolbar. - -By default, support for this is off. To enable support in your application, edit the ``CSPEnabled`` value in -**app/Config/App.php**: - -.. literalinclude:: response/011.php - -When enabled, the response object will contain an instance of ``CodeIgniter\HTTP\ContentSecurityPolicy``. The -values set in **app/Config/ContentSecurityPolicy.php** are applied to that instance, and if no changes are -needed during runtime, then the correctly formatted header is sent and you're all done. - -With CSP enabled, two header lines are added to the HTTP response: a **Content-Security-Policy** header, with -policies identifying content types or origins that are explicitly allowed for different -contexts, and a **Content-Security-Policy-Report-Only** header, which identifies content types -or origins that will be allowed but which will also be reported to the destination -of your choice. - -Our implementation provides for a default treatment, changeable through the ``reportOnly()`` method. -When an additional entry is added to a CSP directive, as shown below, it will be added -to the CSP header appropriate for blocking or preventing. That can be overridden on a per -call basis, by providing an optional second parameter to the adding method call. - -Runtime Configuration ---------------------- - -If your application needs to make changes at run-time, you can access the instance at ``$this->response->getCSP()`` in your controllers. The -class holds a number of methods that map pretty clearly to the appropriate header value that you need to set. -Examples are shown below, with different combinations of parameters, though all accept either a directive -name or an array of them: - -.. literalinclude:: response/012.php - -The first parameter to each of the "add" methods is an appropriate string value, -or an array of them. - -The ``reportOnly()`` method allows you to specify the default reporting treatment -for subsequent sources, unless over-ridden. For instance, you could specify -that youtube.com was allowed, and then provide several allowed but reported sources: - -.. literalinclude:: response/013.php - -Inline Content --------------- - -It is possible to set a website to not protect even inline scripts and styles on its own pages, since this might have -been the result of user-generated content. To protect against this, CSP allows you to specify a nonce within the -`` - -.. warning:: If an attacker injects a string like `` - - // Becomes - - - // OR - - Class Reference ===============