Browse Source

Merge pull request #1484 from ckeditor/t/335

Docs: Created the Content Security Policy guide. Closes #335.
Piotrek Koszuliński 6 years ago
parent
commit
cec2f795e2
4 changed files with 202 additions and 15 deletions
  1. 70 0
      docs/builds/guides/integration/csp.md
  2. 2 2
      mgit.json
  3. 1 1
      package.json
  4. 129 12
      yarn.lock

+ 70 - 0
docs/builds/guides/integration/csp.md

@@ -0,0 +1,70 @@
+---
+# Scope:
+# * Guide developers through the Content Security Policy directives that have an impact on the editor.
+# * List the recommended Content Security Policy settings.
+# * List the strictest working Content Security Policy settings.
+
+category: builds-integration
+order: 70
+---
+
+# Content Security Policy
+
+CKEditor 5 is compatible with applications that use [<abbr title="Content Security Policy">CSP</abbr> rules](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) and helps developers build secure web.
+
+## Recommended CSP configuration
+
+The recommended CSP configuration that allows the rich text editor to run out–of–the–box with all standard features using the content like images or media from external hosts looks as follows:
+
+```
+default-src 'none'; connect-src 'self'; script-src 'self'; img-src * data:; style-src 'self' 'unsafe-inline'; frame-src *
+```
+
+## Impact of CSP on editor features
+
+Some CSP directives have an impact on certain rich text editor features. Here is the round-up of directives and their specific roles in the editor:
+
+* `default-src 'none'`: resets the policy and blocks everything. All successive directives work as a white–list. By itself, as long as followed by other directives, it has no impact on the editor.
+* `connect-src 'self'`
+	* Allows the {@link features/image-upload editor upload features} to use [`XMLHttpReqests`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) (AJAX) to upload files to the server, for instance, when an image is pasted or dropped into the editor content. The `'self`' value ensures the requests remain within the same host.
+	* Allows {@link builds/guides/integration/saving-data#autosave-feature auto–saving editor data} using `XMLHttpRequest`.
+
+	**Note**: To use [CKEditor Cloud Services](https://ckeditor.com/ckeditor-cloud-services/), include the `http://*.cke-cs.com` domain in the `connect-src` directive, for instance, `connect-src 'self' http://*.cke-cs.com`.
+* `script-src 'self'`: allows the execution of JavaScript from the current host only and can be applied only if the CKEditor 5 script file (`<script src="[ckeditor-build-path]/ckeditor.js"></script>`) is also served from that host.
+
+	**Note**: If CKEditor 5 is served from another host, for instance, the {@link builds/guides/integration/installation#cdn official CDN}, make sure the value of `script-src` includes that host (`script-src 'self' https://cdn.ckeditor.com`).
+* `img-src * data:`
+	* The `*` directive value allows images in the editor content to come from any hosts.
+	* The `data:` value allows:
+		* pasting {@link features/image-upload images from the clipboard} and {@link features/paste-from-word from Word} into editor content. Pasted images are usually represented as Base64–encoded strings (`<img src="data:..." />`) and without `data:` they cannot be displayed and uploaded.
+		* displaying the {@link features/media-embed Media embed} feature placeholders for the inserted media.
+
+	**Note**: Use the more strict `img-src 'self'` if all images in the editor content are hosted from the same domain and you do **not** want to enable the {@link features/media-embed Media embed} and {@link features/paste-from-word Paste from Word} features.
+* `style-src 'self' 'unsafe-inline'`: `'unsafe-inline'` is necessary for:
+	* webpack's [style-loader](https://github.com/webpack-contrib/style-loader) to load {@link framework/guides/theme-customization#styles-processing-and-bundling editor UI styles}.
+
+	**Note**: You can {@link builds/guides/integration/advanced-setup#option-extracting-css extract styles to a separate `.css` file} during the editor building process and remove this directive.
+	* certain editor content styles to work properly. For instance, you are going to need it if you want to enable editor features like {@link features/font Font} or {@link features/text-alignment Text alignment} or any other feature that uses inline `style="..."` attributes in the content.
+* `frame-src *`: Necessary for the {@link features/media-embed Media embed} feature to load media with previews (containing `<iframe>`).
+
+	**Note**: Use the more strict `frame-src 'self'` if all the media in the edited content come from the same domain as your application.
+
+<info-box>
+	A different set of Content Security Policy directives might be necessary to run {@link features/ckfinder CKFinder} along with CKEditor 5. Check out the file manager [documentation](https://ckeditor.com/docs/ckfinder/ckfinder3/#!/guide/dev_integration-section-csp-directives-required-by-ckfinder) to learn more.
+</info-box>
+
+## Strictest working configuration
+
+Knowing the role of each directive, the strictest set of rules that allows CKEditor 5 to run is as follows:
+
+```
+default-src 'none'; connect-src 'self'; script-src 'self'; img-src 'self'; style-src 'self'; frame-src 'self'
+```
+
+but it comes with some trade–offs, for instance, it requires you to:
+
+* use an editor build with the {@link builds/guides/integration/advanced-setup#option-extracting-css styles extracted to a separate `.css` file} (no style-loader),
+* load images in the content from the same host,
+* load previewable media in the content from the same host,
+* give up certain features that use inline styles like {@link features/font Font} or {@link features/text-alignment Text alignment},
+* give up pasting images from the clipboard or {@link features/paste-from-word from Word},

+ 2 - 2
mgit.json

@@ -14,7 +14,7 @@
     "@ckeditor/ckeditor5-build-inline": "ckeditor/ckeditor5-build-inline",
     "@ckeditor/ckeditor5-clipboard": "ckeditor/ckeditor5-clipboard",
     "@ckeditor/ckeditor5-cloud-services": "ckeditor/ckeditor5-cloud-services",
-    "@ckeditor/ckeditor5-ckfinder": "ckeditor/ckeditor5-ckfinder",
+    "@ckeditor/ckeditor5-ckfinder": "ckeditor/ckeditor5-ckfinder#t/ckeditor5/335",
     "@ckeditor/ckeditor5-core": "ckeditor/ckeditor5-core",
     "@ckeditor/ckeditor5-easy-image": "ckeditor/ckeditor5-easy-image",
     "@ckeditor/ckeditor5-editor-balloon": "ckeditor/ckeditor5-editor-balloon",
@@ -35,7 +35,7 @@
     "@ckeditor/ckeditor5-paragraph": "ckeditor/ckeditor5-paragraph",
     "@ckeditor/ckeditor5-paste-from-office": "ckeditor/ckeditor5-paste-from-office",
     "@ckeditor/ckeditor5-table": "ckeditor/ckeditor5-table",
-    "@ckeditor/ckeditor5-theme-lark": "ckeditor/ckeditor5-theme-lark",
+    "@ckeditor/ckeditor5-theme-lark": "ckeditor/ckeditor5-theme-lark#t/ckeditor5/335",
     "@ckeditor/ckeditor5-typing": "ckeditor/ckeditor5-typing",
     "@ckeditor/ckeditor5-ui": "ckeditor/ckeditor5-ui",
     "@ckeditor/ckeditor5-undo": "ckeditor/ckeditor5-undo",

+ 1 - 1
package.json

@@ -67,7 +67,7 @@
     "@ckeditor/ckeditor5-comments": "^1.0.1",
     "@ckeditor/ckeditor5-dev-docs": "^10.0.3",
     "@ckeditor/ckeditor5-dev-env": "^13.0.2",
-    "@ckeditor/ckeditor5-dev-tests": "^15.0.1",
+    "@ckeditor/ckeditor5-dev-tests": "^15.2.0",
     "@ckeditor/ckeditor5-dev-utils": "^11.0.1",
     "@ckeditor/ckeditor5-dev-webpack-plugin": "^7.0.1",
     "css-loader": "^1.0.0",

+ 129 - 12
yarn.lock

@@ -9,6 +9,26 @@
   dependencies:
     "@babel/highlight" "^7.0.0"
 
+"@babel/core@^7.0.0":
+  version "7.2.2"
+  resolved "https://registry.yarnpkg.com/@babel/core/-/core-7.2.2.tgz#07adba6dde27bb5ad8d8672f15fde3e08184a687"
+  integrity sha512-59vB0RWt09cAct5EIe58+NzGP4TFSD3Bz//2/ELy3ZeTeKF6VTD1AXlH8BGGbCX0PuobZBsIzO7IAI9PH67eKw==
+  dependencies:
+    "@babel/code-frame" "^7.0.0"
+    "@babel/generator" "^7.2.2"
+    "@babel/helpers" "^7.2.0"
+    "@babel/parser" "^7.2.2"
+    "@babel/template" "^7.2.2"
+    "@babel/traverse" "^7.2.2"
+    "@babel/types" "^7.2.2"
+    convert-source-map "^1.1.0"
+    debug "^4.1.0"
+    json5 "^2.1.0"
+    lodash "^4.17.10"
+    resolve "^1.3.2"
+    semver "^5.4.1"
+    source-map "^0.5.0"
+
 "@babel/core@^7.1.2":
   version "7.1.2"
   resolved "https://registry.yarnpkg.com/@babel/core/-/core-7.1.2.tgz#f8d2a9ceb6832887329a7b60f9d035791400ba4e"
@@ -40,6 +60,17 @@
     source-map "^0.5.0"
     trim-right "^1.0.1"
 
+"@babel/generator@^7.2.2":
+  version "7.3.2"
+  resolved "https://registry.yarnpkg.com/@babel/generator/-/generator-7.3.2.tgz#fff31a7b2f2f3dad23ef8e01be45b0d5c2fc0132"
+  integrity sha512-f3QCuPppXxtZOEm5GWPra/uYUjmNQlu9pbAD8D/9jze4pTY83rTtB1igTBSwvkeNlC5gR24zFFkz+2WHLFQhqQ==
+  dependencies:
+    "@babel/types" "^7.3.2"
+    jsesc "^2.5.1"
+    lodash "^4.17.10"
+    source-map "^0.5.0"
+    trim-right "^1.0.1"
+
 "@babel/helper-annotate-as-pure@^7.0.0":
   version "7.0.0"
   resolved "https://registry.yarnpkg.com/@babel/helper-annotate-as-pure/-/helper-annotate-as-pure-7.0.0.tgz#323d39dd0b50e10c7c06ca7d7638e6864d8c5c32"
@@ -204,6 +235,15 @@
     "@babel/traverse" "^7.1.0"
     "@babel/types" "^7.1.2"
 
+"@babel/helpers@^7.2.0":
+  version "7.3.1"
+  resolved "https://registry.yarnpkg.com/@babel/helpers/-/helpers-7.3.1.tgz#949eec9ea4b45d3210feb7dc1c22db664c9e44b9"
+  integrity sha512-Q82R3jKsVpUV99mgX50gOPCWwco9Ec5Iln/8Vyu4osNIOQgSrd9RFrQeUvmvddFNoLwMyOUWU+5ckioEKpDoGA==
+  dependencies:
+    "@babel/template" "^7.1.2"
+    "@babel/traverse" "^7.1.5"
+    "@babel/types" "^7.3.0"
+
 "@babel/highlight@^7.0.0":
   version "7.0.0"
   resolved "https://registry.yarnpkg.com/@babel/highlight/-/highlight-7.0.0.tgz#f710c38c8d458e6dd9a201afb637fcb781ce99e4"
@@ -218,6 +258,11 @@
   resolved "https://registry.yarnpkg.com/@babel/parser/-/parser-7.1.3.tgz#2c92469bac2b7fbff810b67fca07bd138b48af77"
   integrity sha512-gqmspPZOMW3MIRb9HlrnbZHXI1/KHTOroBwN1NcLL6pWxzqzEKGvRTq0W/PxS45OtQGbaFikSQpkS5zbnsQm2w==
 
+"@babel/parser@^7.2.2", "@babel/parser@^7.2.3":
+  version "7.3.2"
+  resolved "https://registry.yarnpkg.com/@babel/parser/-/parser-7.3.2.tgz#95cdeddfc3992a6ca2a1315191c1679ca32c55cd"
+  integrity sha512-QzNUC2RO1gadg+fs21fi0Uu0OuGNzRKEmgCxoLNzbCdoprLwjfmZwzUrpUNfJPaVRwBpDY47A17yYEGWyRelnQ==
+
 "@babel/plugin-proposal-async-generator-functions@^7.1.0":
   version "7.1.0"
   resolved "https://registry.yarnpkg.com/@babel/plugin-proposal-async-generator-functions/-/plugin-proposal-async-generator-functions-7.1.0.tgz#41c1a702e10081456e23a7b74d891922dd1bb6ce"
@@ -567,6 +612,15 @@
     "@babel/parser" "^7.1.2"
     "@babel/types" "^7.1.2"
 
+"@babel/template@^7.2.2":
+  version "7.2.2"
+  resolved "https://registry.yarnpkg.com/@babel/template/-/template-7.2.2.tgz#005b3fdf0ed96e88041330379e0da9a708eb2907"
+  integrity sha512-zRL0IMM02AUDwghf5LMSSDEz7sBCO2YnNmpg3uWTZj/v1rcG2BmQUvaGU8GhU8BvfMh1k2KIAYZ7Ji9KXPUg7g==
+  dependencies:
+    "@babel/code-frame" "^7.0.0"
+    "@babel/parser" "^7.2.2"
+    "@babel/types" "^7.2.2"
+
 "@babel/traverse@^7.1.0":
   version "7.1.4"
   resolved "https://registry.yarnpkg.com/@babel/traverse/-/traverse-7.1.4.tgz#f4f83b93d649b4b2c91121a9087fa2fa949ec2b4"
@@ -582,6 +636,21 @@
     globals "^11.1.0"
     lodash "^4.17.10"
 
+"@babel/traverse@^7.1.5", "@babel/traverse@^7.2.2":
+  version "7.2.3"
+  resolved "https://registry.yarnpkg.com/@babel/traverse/-/traverse-7.2.3.tgz#7ff50cefa9c7c0bd2d81231fdac122f3957748d8"
+  integrity sha512-Z31oUD/fJvEWVR0lNZtfgvVt512ForCTNKYcJBGbPb1QZfve4WGH8Wsy7+Mev33/45fhP/hwQtvgusNdcCMgSw==
+  dependencies:
+    "@babel/code-frame" "^7.0.0"
+    "@babel/generator" "^7.2.2"
+    "@babel/helper-function-name" "^7.1.0"
+    "@babel/helper-split-export-declaration" "^7.0.0"
+    "@babel/parser" "^7.2.3"
+    "@babel/types" "^7.2.2"
+    debug "^4.1.0"
+    globals "^11.1.0"
+    lodash "^4.17.10"
+
 "@babel/types@^7.0.0", "@babel/types@^7.1.2", "@babel/types@^7.1.3":
   version "7.1.3"
   resolved "https://registry.yarnpkg.com/@babel/types/-/types-7.1.3.tgz#3a767004567060c2f40fca49a304712c525ee37d"
@@ -591,6 +660,15 @@
     lodash "^4.17.10"
     to-fast-properties "^2.0.0"
 
+"@babel/types@^7.2.2", "@babel/types@^7.3.0", "@babel/types@^7.3.2":
+  version "7.3.2"
+  resolved "https://registry.yarnpkg.com/@babel/types/-/types-7.3.2.tgz#424f5be4be633fff33fb83ab8d67e4a8290f5a2f"
+  integrity sha512-3Y6H8xlUlpbGR+XvawiH0UXehqydTmNmEpozWcXymqwcrwYAl5KMvKtQ+TF6f6E08V6Jur7v/ykdDSF+WDEIXQ==
+  dependencies:
+    esutils "^2.0.2"
+    lodash "^4.17.10"
+    to-fast-properties "^2.0.0"
+
 "@ckeditor/ckeditor-cloud-services-collaboration@^2.0.2":
   version "2.0.2"
   resolved "https://registry.yarnpkg.com/@ckeditor/ckeditor-cloud-services-collaboration/-/ckeditor-cloud-services-collaboration-2.0.2.tgz#ba16db2694436d6219742ec1c131ac299c4d4b5e"
@@ -675,13 +753,14 @@
     request "^2.83.0"
     semver "^5.4.1"
 
-"@ckeditor/ckeditor5-dev-tests@^15.0.1":
-  version "15.1.0"
-  resolved "https://registry.yarnpkg.com/@ckeditor/ckeditor5-dev-tests/-/ckeditor5-dev-tests-15.1.0.tgz#50db3a1fbddb6c52ed57c237d5338d6c77b74f85"
-  integrity sha512-udscXhNxXCmcXbAK+5BtLDilRBQGJG/ND7WZwG3Q3EIHdE/Dxg3GV6jRTvc8mcabOvVyFKw2I8Sagv42jF298g==
+"@ckeditor/ckeditor5-dev-tests@^15.2.0":
+  version "15.2.0"
+  resolved "https://registry.yarnpkg.com/@ckeditor/ckeditor5-dev-tests/-/ckeditor5-dev-tests-15.2.0.tgz#17847661c174abf3233dcd1e295cea1a52f08560"
+  integrity sha512-0p2wr67Lh7eaKV7oHJ6v3E0rxyLy85+zh/OdDXMPSDMgysiB8KGDNqVnLCCL9xFda03zxVISYz2d5D6rxeYX2w==
   dependencies:
-    "@ckeditor/ckeditor5-dev-utils" "^11.0.1"
-    "@ckeditor/ckeditor5-dev-webpack-plugin" "^7.0.1"
+    "@babel/core" "^7.0.0"
+    "@ckeditor/ckeditor5-dev-utils" "^11.0.2"
+    "@ckeditor/ckeditor5-dev-webpack-plugin" "^7.0.2"
     babel-core "^6.26.0"
     babel-loader "^8.0.2"
     babel-plugin-transform-es2015-modules-commonjs "^6.26.0"
@@ -713,7 +792,6 @@
     minimist "^1.2.0"
     mkdirp "^0.5.1"
     mocha "^5.0.5"
-    mockery "^2.1.0"
     postcss-loader "^3.0.0"
     raw-loader "^1.0.0"
     sinon "^6.3.4"
@@ -740,6 +818,26 @@
     shelljs "^0.8.1"
     through2 "^2.0.3"
 
+"@ckeditor/ckeditor5-dev-utils@^11.0.2":
+  version "11.0.2"
+  resolved "https://registry.yarnpkg.com/@ckeditor/ckeditor5-dev-utils/-/ckeditor5-dev-utils-11.0.2.tgz#d883bef3be3a9f2bd866dd9a263f20521c35f018"
+  integrity sha512-lo/46QCpmA8yCTh3G+zlD9+92YuE9Kz/7wmZJVqKIu6EGdy2Wx8kBQvZN2ON00WO7F9E0SsNHPVpR3BwOtjN5A==
+  dependencies:
+    acorn "^5.1.2"
+    chalk "^2.4.1"
+    cssnano "^4.0.0"
+    del "^3.0.0"
+    escodegen "^1.9.0"
+    fs-extra "^7.0.0"
+    javascript-stringify "^1.6.0"
+    pofile "^1.0.9"
+    postcss "^6.0.23"
+    postcss-import "^12.0.0"
+    postcss-mixins "^6.2.0"
+    postcss-nesting "^6.0.0"
+    shelljs "^0.8.1"
+    through2 "^2.0.3"
+
 "@ckeditor/ckeditor5-dev-webpack-plugin@^7.0.1":
   version "7.0.1"
   resolved "https://registry.yarnpkg.com/@ckeditor/ckeditor5-dev-webpack-plugin/-/ckeditor5-dev-webpack-plugin-7.0.1.tgz#a992a4c479895e83237788d144da604d2669680b"
@@ -750,6 +848,16 @@
     rimraf "^2.6.2"
     webpack-sources "^1.1.0"
 
+"@ckeditor/ckeditor5-dev-webpack-plugin@^7.0.2":
+  version "7.0.2"
+  resolved "https://registry.yarnpkg.com/@ckeditor/ckeditor5-dev-webpack-plugin/-/ckeditor5-dev-webpack-plugin-7.0.2.tgz#afcf6dac59c565be0d0f0e42b838fa88d50880fd"
+  integrity sha512-T+GsXrf8GvHR5YCkDlUZbB7ATw2I2rbySv5wvXtaDPvmGluh9rx9GiNM3bEXTaFa8EP7uQWNlPlddQJSx+XR2w==
+  dependencies:
+    "@ckeditor/ckeditor5-dev-utils" "^11.0.2"
+    chalk "^2.4.1"
+    rimraf "^2.6.2"
+    webpack-sources "^1.1.0"
+
 "@ckeditor/ckeditor5-operations-compressor@^1.0.1":
   version "1.0.1"
   resolved "https://registry.yarnpkg.com/@ckeditor/ckeditor5-operations-compressor/-/ckeditor5-operations-compressor-1.0.1.tgz#fff403afb622c9fc58f3fd0b92309ed64a0275d0"
@@ -3227,6 +3335,13 @@ debug@^4.0.1:
   dependencies:
     ms "^2.1.1"
 
+debug@^4.1.0:
+  version "4.1.1"
+  resolved "https://registry.yarnpkg.com/debug/-/debug-4.1.1.tgz#3b72260255109c6b589cee050f1d516139664791"
+  integrity sha512-pYAIzeRo8J6KPEaJ0VWOh5Pzkbw/RetuzehGM7QRRX5he4fPHx2rdKMB256ehJCkX+XRQm16eZLqLNS8RSZXZw==
+  dependencies:
+    ms "^2.1.1"
+
 decamelize-keys@^1.0.0:
   version "1.1.0"
   resolved "https://registry.yarnpkg.com/decamelize-keys/-/decamelize-keys-1.1.0.tgz#d171a87933252807eb3cb61dc1c1445d078df2d9"
@@ -5917,6 +6032,13 @@ json5@^0.5.0, json5@^0.5.1:
   resolved "https://registry.yarnpkg.com/json5/-/json5-0.5.1.tgz#1eade7acc012034ad84e2396767ead9fa5495821"
   integrity sha1-Hq3nrMASA0rYTiOWdn6tn6VJWCE=
 
+json5@^2.1.0:
+  version "2.1.0"
+  resolved "https://registry.yarnpkg.com/json5/-/json5-2.1.0.tgz#e7a0c62c48285c628d20a10b85c89bb807c32850"
+  integrity sha512-8Mh9h6xViijj36g7Dxi+Y4S6hNGV96vcJZr/SrlHh1LR/pEn/8j/+qIBbs44YKl69Lrfctp4QD+AdWLTMqEZAQ==
+  dependencies:
+    minimist "^1.2.0"
+
 jsonfile@^2.1.0:
   version "2.4.0"
   resolved "https://registry.yarnpkg.com/jsonfile/-/jsonfile-2.4.0.tgz#3736a2b428b87bbda0cc83b53fa3d633a35c2ae8"
@@ -7022,11 +7144,6 @@ mocha@^5.0.5:
     mkdirp "0.5.1"
     supports-color "5.4.0"
 
-mockery@^2.1.0:
-  version "2.1.0"
-  resolved "https://registry.yarnpkg.com/mockery/-/mockery-2.1.0.tgz#5b0aef1ff564f0f8139445e165536c7909713470"
-  integrity sha512-9VkOmxKlWXoDO/h1jDZaS4lH33aWfRiJiNT/tKj+8OGzrcFDLo8d0syGdbsc3Bc4GvRXPb+NMMvojotmuGJTvA==
-
 modify-values@^1.0.0:
   version "1.0.1"
   resolved "https://registry.yarnpkg.com/modify-values/-/modify-values-1.0.1.tgz#b3939fa605546474e3e3e3c63d64bd43b4ee6022"