[TASK] Explain Content Security Policy modes (#4710)

* [TASK] Explain Content Security Policy modes Related: TYPO3-Documentation/Changelog-To-Doc#390 Releases: main, 12.4 * Update Documentation/ApiOverview/ContentSecurityPolicy/Index.rst Co-authored-by: Stefan Frömken <[email protected]> --------- Co-authored-by: Stefan Frömken <[email protected]>
TYPO3-Documentation · Sep 10, 2024 · 2107735 · 2107735
1 parent 7548f94
commit 2107735
Show file tree

Hide file tree

Showing 15 changed files with 524 additions and 1 deletion.
diff --git a/Documentation/ApiOverview/ContentSecurityPolicy/Index.rst b/Documentation/ApiOverview/ContentSecurityPolicy/Index.rst
@@ -116,7 +116,201 @@ used to declare policies for a specific site, for example:
     :language: yaml
     :caption: config/sites/<my_site>/csp.yaml | typo3conf/sites/<my_site>/csp.yaml
 
-..  todo: Explain "inheritDefault", "mutations", "mode", "directive", "sources", ...
+..  _content-security-policy-modes:
+
+Modes
+-----
+
+The following modes are available:
+
+..  confval-menu::
+    :name: content-security-policy-modes
+
+    ..  confval:: append
+        :name: content-security-policy-mode-append
+        :YAML: :yaml:`append`
+        :PHP: :php:`\TYPO3\CMS\Core\Security\ContentSecurityPolicy\MutationMode::Append`
+
+        Appends to a given directive.
+
+        Example:
+
+        ..  literalinclude:: _csp_mode_append.yaml
+            :language: yaml
+            :caption: config/sites/<my_site>/csp.yaml | typo3conf/sites/<my_site>/csp.yaml
+            :emphasize-lines: 12-15
+
+        ..  literalinclude:: _ContentSecurityPolicies_mode_append.php
+            :language: php
+            :caption: EXT:my_extension/Configuration/ContentSecurityPolicies.php
+            :emphasize-lines: 27-31
+
+        Results in:
+
+        ..  code-block:: http
+
+            Content-Security-Policy: default-src 'self'; img-src example.org example.com
+
+    ..  confval:: extend
+        :name: content-security-policy-mode-extend
+        :YAML: :yaml:`extend`
+        :PHP: :php:`\TYPO3\CMS\Core\Security\ContentSecurityPolicy\MutationMode::Extend`
+
+        Extends the given directive. It is a shortcut for
+        :confval:`content-security-policy-mode-inherit-once` and
+        :confval:`content-security-policy-mode-append`.
+
+        Example:
+
+        ..  literalinclude:: _csp_mode_extend.yaml
+            :language: yaml
+            :caption: config/sites/<my_site>/csp.yaml | typo3conf/sites/<my_site>/csp.yaml
+            :emphasize-lines: 7-10
+
+        ..  literalinclude:: _ContentSecurityPolicies_mode_extend.php
+            :language: php
+            :caption: EXT:my_extension/Configuration/ContentSecurityPolicies.php
+            :emphasize-lines: 22-26
+
+        Results in:
+
+        ..  code-block:: http
+
+            Content-Security-Policy: default-src 'self'; img-src 'self' example.com
+
+    ..  confval:: inherit-again
+        :name: content-security-policy-mode-inherit-again
+        :YAML: :yaml:`inherit-again`
+        :PHP: :php:`\TYPO3\CMS\Core\Security\ContentSecurityPolicy\MutationMode::InheritAgain`
+
+        Inherits again from the corresponding ancestor chain and merges existing
+        sources.
+
+        Example:
+
+        ..  literalinclude:: _csp_mode_inherit_again.yaml
+            :language: yaml
+            :caption: config/sites/<my_site>/csp.yaml | typo3conf/sites/<my_site>/csp.yaml
+            :emphasize-lines: 8-9,21-22
+
+        ..  literalinclude:: _ContentSecurityPolicies_mode_inherit_again.php
+            :language: php
+            :caption: EXT:my_extension/Configuration/ContentSecurityPolicies.php
+            :emphasize-lines: 23-26,37-40
+
+        Results in:
+
+        ..  code-block:: http
+
+            Content-Security-Policy: default-src data:; img-src data: 'self' example.com
+
+        Note that `data:` is inherited to `img-src`
+        (in opposite to :confval:`content-security-policy-mode-inherit-once`).
+
+    ..  confval:: inherit-once
+        :name: content-security-policy-mode-inherit-once
+        :YAML: :yaml:`inherit-once`
+        :PHP: :php:`\TYPO3\CMS\Core\Security\ContentSecurityPolicy\MutationMode::InheritOnce`
+
+        Inherits once from the corresponding ancestor chain. When `inherit-once` is
+        called multiple times on the same directive, only the first time is applied.
+
+        Example:
+
+        ..  literalinclude:: _csp_mode_inherit_once.yaml
+            :language: yaml
+            :caption: config/sites/<my_site>/csp.yaml | typo3conf/sites/<my_site>/csp.yaml
+            :emphasize-lines: 8-9,21-22
+
+        ..  literalinclude:: _ContentSecurityPolicies_mode_inherit_once.php
+            :language: php
+            :caption: EXT:my_extension/Configuration/ContentSecurityPolicies.php
+            :emphasize-lines: 23-26,37-40
+
+        Results in:
+
+        ..  code-block:: http
+
+            Content-Security-Policy: default-src data:; img-src 'self' example.com
+
+        Note that `data:` is not inherited to `img-src`. If you want to inherit
+        also `data:` to `img-src` use
+        :confval:`content-security-policy-mode-inherit-again`.
+
+    ..  confval:: reduce
+        :name: content-security-policy-mode-reduce
+        :YAML: :yaml:`reduce`
+        :PHP: :php:`\TYPO3\CMS\Core\Security\ContentSecurityPolicy\MutationMode::Reduce`
+
+        Reduces a directive by a given aspect.
+
+        Example:
+
+        ..  literalinclude:: _csp_mode_reduce.yaml
+            :language: yaml
+            :caption: config/sites/<my_site>/csp.yaml | typo3conf/sites/<my_site>/csp.yaml
+            :emphasize-lines: 9-12
+
+        ..  literalinclude:: _ContentSecurityPolicies_mode_reduce.php
+            :language: php
+            :caption: EXT:my_extension/Configuration/ContentSecurityPolicies.php
+            :emphasize-lines: 24-28
+
+        Results in:
+
+        ..  code-block:: http
+
+            Content-Security-Policy: default-src 'self' example.com
+
+    ..  confval:: remove
+        :name: content-security-policy-mode-remove
+        :YAML: :yaml:`remove`
+        :PHP: :php:`\TYPO3\CMS\Core\Security\ContentSecurityPolicy\MutationMode::Remove`
+
+        Removes a directive completely.
+
+        Example:
+
+        ..  literalinclude:: _csp_mode_remove.yaml
+            :language: yaml
+            :caption: config/sites/<my_site>/csp.yaml | typo3conf/sites/<my_site>/csp.yaml
+            :emphasize-lines: 12-13
+
+        ..  literalinclude:: _ContentSecurityPolicies_mode_remove.php
+            :language: php
+            :caption: EXT:my_extension/Configuration/ContentSecurityPolicies.php
+            :emphasize-lines: 27-30
+
+        Results in:
+
+        ..  code-block:: http
+
+            Content-Security-Policy: img-src 'self'
+
+    ..  confval:: set
+        :name: content-security-policy-mode-set
+        :YAML: :yaml:`set`
+        :PHP: :php:`\TYPO3\CMS\Core\Security\ContentSecurityPolicy\MutationMode::Set`
+
+        Sets (overrides) a directive completely.
+
+        Example:
+
+        ..  literalinclude:: _csp_mode_set.yaml
+            :language: yaml
+            :caption: config/sites/<my_site>/csp.yaml | typo3conf/sites/<my_site>/csp.yaml
+            :emphasize-lines: 2-5
+
+        ..  literalinclude:: _ContentSecurityPolicies_mode_set.php
+            :language: php
+            :caption: EXT:my_extension/Configuration/ContentSecurityPolicies.php
+            :emphasize-lines: 16-20
+
+        Results in:
+
+        ..  code-block:: http
+
+            Content-Security-Policy: img-src 'self'
 
 
 .. _content-security-policy-nonce:

diff --git a/Documentation/ApiOverview/ContentSecurityPolicy/_ContentSecurityPolicies_mode_append.php b/Documentation/ApiOverview/ContentSecurityPolicy/_ContentSecurityPolicies_mode_append.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\Directive;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\Mutation;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\MutationCollection;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\MutationMode;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\Scope;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\SourceKeyword;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\UriValue;
+use TYPO3\CMS\Core\Type\Map;
+
+return Map::fromEntries([
+    Scope::frontend(),
+    new MutationCollection(
+        new Mutation(
+            MutationMode::Set,
+            Directive::DefaultSrc,
+            SourceKeyword::self,
+        ),
+        new Mutation(
+            MutationMode::Set,
+            Directive::ImgSrc,
+            new UriValue('example.org'),
+        ),
+        new Mutation(
+            MutationMode::Append,
+            Directive::ImgSrc,
+            new UriValue('example.com'),
+        ),
+    ),
+]);
diff --git a/Documentation/ApiOverview/ContentSecurityPolicy/_ContentSecurityPolicies_mode_extend.php b/Documentation/ApiOverview/ContentSecurityPolicy/_ContentSecurityPolicies_mode_extend.php
@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\Directive;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\Mutation;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\MutationCollection;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\MutationMode;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\Scope;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\SourceKeyword;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\UriValue;
+use TYPO3\CMS\Core\Type\Map;
+
+return Map::fromEntries([
+    Scope::frontend(),
+    new MutationCollection(
+        new Mutation(
+            MutationMode::Set,
+            Directive::DefaultSrc,
+            SourceKeyword::self,
+        ),
+        new Mutation(
+            MutationMode::Extend,
+            Directive::ImgSrc,
+            new UriValue('example.com'),
+        ),
+    ),
+]);
diff --git a/...ntation/ApiOverview/ContentSecurityPolicy/_ContentSecurityPolicies_mode_inherit_again.php b/...ntation/ApiOverview/ContentSecurityPolicy/_ContentSecurityPolicies_mode_inherit_again.php
@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\Directive;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\Mutation;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\MutationCollection;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\MutationMode;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\Scope;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\SourceKeyword;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\SourceScheme;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\UriValue;
+use TYPO3\CMS\Core\Type\Map;
+
+return Map::fromEntries([
+    Scope::frontend(),
+    new MutationCollection(
+        new Mutation(
+            MutationMode::Set,
+            Directive::DefaultSrc,
+            SourceKeyword::self,
+        ),
+        new Mutation(
+            MutationMode::InheritAgain,
+            Directive::ImgSrc,
+        ),
+        new Mutation(
+            MutationMode::Append,
+            Directive::ImgSrc,
+            new UriValue('example.com'),
+        ),
+        new Mutation(
+            MutationMode::Set,
+            Directive::DefaultSrc,
+            SourceScheme::data,
+        ),
+        new Mutation(
+            MutationMode::InheritAgain,
+            Directive::ScriptSrc,
+        ),
+    ),
+]);
diff --git a/...entation/ApiOverview/ContentSecurityPolicy/_ContentSecurityPolicies_mode_inherit_once.php b/...entation/ApiOverview/ContentSecurityPolicy/_ContentSecurityPolicies_mode_inherit_once.php
@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\Directive;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\Mutation;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\MutationCollection;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\MutationMode;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\Scope;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\SourceKeyword;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\SourceScheme;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\UriValue;
+use TYPO3\CMS\Core\Type\Map;
+
+return Map::fromEntries([
+    Scope::frontend(),
+    new MutationCollection(
+        new Mutation(
+            MutationMode::Set,
+            Directive::DefaultSrc,
+            SourceKeyword::self,
+        ),
+        new Mutation(
+            MutationMode::InheritOnce,
+            Directive::ImgSrc,
+        ),
+        new Mutation(
+            MutationMode::Append,
+            Directive::ImgSrc,
+            new UriValue('example.com'),
+        ),
+        new Mutation(
+            MutationMode::Set,
+            Directive::DefaultSrc,
+            SourceScheme::data,
+        ),
+        new Mutation(
+            MutationMode::InheritOnce,
+            Directive::ImgSrc,
+        ),
+    ),
+]);
diff --git a/Documentation/ApiOverview/ContentSecurityPolicy/_ContentSecurityPolicies_mode_reduce.php b/Documentation/ApiOverview/ContentSecurityPolicy/_ContentSecurityPolicies_mode_reduce.php
@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\Directive;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\Mutation;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\MutationCollection;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\MutationMode;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\Scope;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\SourceKeyword;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\SourceScheme;
+use TYPO3\CMS\Core\Security\ContentSecurityPolicy\UriValue;
+use TYPO3\CMS\Core\Type\Map;
+
+return Map::fromEntries([
+    Scope::frontend(),
+    new MutationCollection(
+        new Mutation(
+            MutationMode::Set,
+            Directive::ImgSrc,
+            SourceKeyword::self,
+            SourceScheme::data,
+            new UriValue('example.com'),
+        ),
+        new Mutation(
+            MutationMode::Reduce,
+            Directive::ImgSrc,
+            SourceScheme::data,
+        ),
+    ),
+]);