From d58ce836695e122c418171efcaf5a7a7a6e3fad3 Mon Sep 17 00:00:00 2001 From: kenjis Date: Sat, 4 Nov 2023 15:45:13 +0900 Subject: [PATCH 1/4] docs: add csp.rst and move existing contents --- user_guide_src/source/outgoing/csp.rst | 127 ++++++++++++++++++ .../source/outgoing/{response => csp}/011.php | 0 .../source/outgoing/{response => csp}/012.php | 0 .../source/outgoing/{response => csp}/013.php | 0 user_guide_src/source/outgoing/index.rst | 1 + user_guide_src/source/outgoing/response.rst | 116 ---------------- 6 files changed, 128 insertions(+), 116 deletions(-) create mode 100644 user_guide_src/source/outgoing/csp.rst rename user_guide_src/source/outgoing/{response => csp}/011.php (100%) rename user_guide_src/source/outgoing/{response => csp}/012.php (100%) rename user_guide_src/source/outgoing/{response => csp}/013.php (100%) diff --git a/user_guide_src/source/outgoing/csp.rst b/user_guide_src/source/outgoing/csp.rst new file mode 100644 index 000000000000..b0ca5263c1ef --- /dev/null +++ b/user_guide_src/source/outgoing/csp.rst @@ -0,0 +1,127 @@ +.. _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 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:: 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 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 =============== From 202a8751419a3e5024b748a70619d9696be83ad3 Mon Sep 17 00:00:00 2001 From: kenjis Date: Sat, 4 Nov 2023 15:47:14 +0900 Subject: [PATCH 2/4] docs: trivail fix in sample code --- user_guide_src/source/outgoing/csp/011.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/user_guide_src/source/outgoing/csp/011.php b/user_guide_src/source/outgoing/csp/011.php index bfac115c6bd3..193105592586 100644 --- a/user_guide_src/source/outgoing/csp/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; } From fd2fd4d633a2b03ff4c265b868b7fcd8d0537c70 Mon Sep 17 00:00:00 2001 From: kenjis Date: Sat, 4 Nov 2023 15:52:10 +0900 Subject: [PATCH 3/4] docs: add (CSP) --- user_guide_src/source/outgoing/csp.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user_guide_src/source/outgoing/csp.rst b/user_guide_src/source/outgoing/csp.rst index b0ca5263c1ef..44eb585256db 100644 --- a/user_guide_src/source/outgoing/csp.rst +++ b/user_guide_src/source/outgoing/csp.rst @@ -12,7 +12,7 @@ Content Security Policy What is Content Security Policy? ******************************** -One of the best protections you have against XSS attacks is to implement a Content Security Policy on the site. +One of the best protections you have against XSS attacks is to implement a Content Security Policy (CSP) 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 From 178c4c07d3c181aaf74caa60b6c51bbc35c5210f Mon Sep 17 00:00:00 2001 From: kenjis Date: Sat, 4 Nov 2023 15:57:29 +0900 Subject: [PATCH 4/4] docs: remove `whitelist` --- user_guide_src/source/outgoing/csp.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/user_guide_src/source/outgoing/csp.rst b/user_guide_src/source/outgoing/csp.rst index 44eb585256db..0761f289a611 100644 --- a/user_guide_src/source/outgoing/csp.rst +++ b/user_guide_src/source/outgoing/csp.rst @@ -12,11 +12,13 @@ Content Security Policy 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 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. +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.