diff --git a/Documentation/ApiOverview/ContentSecurityPolicy/Index.rst b/Documentation/ApiOverview/ContentSecurityPolicy/Index.rst index c34382fa94..2650375f70 100644 --- 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//csp.yaml | typo3conf/sites//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//csp.yaml | typo3conf/sites//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//csp.yaml | typo3conf/sites//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//csp.yaml | typo3conf/sites//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//csp.yaml | typo3conf/sites//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//csp.yaml | typo3conf/sites//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//csp.yaml | typo3conf/sites//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//csp.yaml | typo3conf/sites//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 new file mode 100644 index 0000000000..d6cada99da --- /dev/null +++ b/Documentation/ApiOverview/ContentSecurityPolicy/_ContentSecurityPolicies_mode_append.php @@ -0,0 +1,33 @@ +