Move CSP info from 5.2 release notes to guide [ci skip]

- Add mention about "nonce".

Related to https://github.com/rails/rails/pull/32222#issuecomment-372268157

2 files changed, 109 insertions, 63 deletions

diff --git a/guides/source/5_2_release_notes.md b/guides/source/5_2_release_notes.md
index 8086c8cb55..541c025fac 100644
--- a/guides/source/5_2_release_notes.md
+++ b/guides/source/5_2_release_notes.md
@@ -85,69 +85,9 @@ Rails 5.2 ships with a new DSL that allows you to configure a
 for your application. You can configure a global default policy and then
 override it on a per-resource basis and even use lambdas to inject per-request
 values into the header such as account subdomains in a multi-tenant application.
-
-Example global policy:
-
-```ruby
-# config/initializers/content_security_policy.rb
-Rails.application.config.content_security_policy do |policy|
-  policy.default_src :self, :https
-  policy.font_src    :self, :https, :data
-  policy.img_src     :self, :https, :data
-  policy.object_src  :none
-  policy.script_src  :self, :https
-  policy.style_src   :self, :https
-
-  # Specify URI for violation reports
-  policy.report_uri "/csp-violation-report-endpoint"
-end
-```
-
-Example controller overrides:
-
-```ruby
-# Override policy inline
-class PostsController < ApplicationController
-  content_security_policy do |p|
-    p.upgrade_insecure_requests true
-  end
-end
-
-# Using literal values
-class PostsController < ApplicationController
-  content_security_policy do |p|
-    p.base_uri "https://www.example.com"
-  end
-end
-
-# Using mixed static and dynamic values
-class PostsController < ApplicationController
-  content_security_policy do |p|
-    p.base_uri :self, -> { "https://#{current_user.domain}.example.com" }
-  end
-end
-
-# Disabling the global CSP
-class LegacyPagesController < ApplicationController
-  content_security_policy false, only: :index
-end
-```
-
-To report only content violations for migrating
-legacy content using the `content_security_policy_report_only`
-configuration attribute:
-
-```ruby
-# config/initializers/content_security_policy.rb
-Rails.application.config.content_security_policy_report_only = true
-```
-
-```ruby
-# Controller override
-class PostsController < ApplicationController
-  content_security_policy_report_only only: :index
-end
-```
+You can read more about this in the
+[Securing Rails Applications](security.html#content-security-policy)
+guide.
 
 Railties
 --------
diff --git a/guides/source/security.md b/guides/source/security.md
index 4cf6c06f2d..b419f7b48d 100644
--- a/guides/source/security.md
+++ b/guides/source/security.md
@@ -1089,6 +1089,112 @@ Here is a list of common headers:
 * **Access-Control-Allow-Origin:** Used to control which sites are allowed to bypass same origin policies and send cross-origin requests.
 * **Strict-Transport-Security:** [Used to control if the browser is allowed to only access a site over a secure connection](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security)
 
+### Content Security Policy
+
+Rails provides a DSL that allows you to configure a
+[Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)
+for your application. You can configure a global default policy and then
+override it on a per-resource basis and even use lambdas to inject per-request
+values into the header such as account subdomains in a multi-tenant application.
+
+Example global policy:
+
+```ruby
+# config/initializers/content_security_policy.rb
+Rails.application.config.content_security_policy do |policy|
+  policy.default_src :self, :https
+  policy.font_src    :self, :https, :data
+  policy.img_src     :self, :https, :data
+  policy.object_src  :none
+  policy.script_src  :self, :https
+  policy.style_src   :self, :https
+
+  # Specify URI for violation reports
+  policy.report_uri "/csp-violation-report-endpoint"
+end
+```
+
+Example controller overrides:
+
+```ruby
+# Override policy inline
+class PostsController < ApplicationController
+  content_security_policy do |p|
+    p.upgrade_insecure_requests true
+  end
+end
+
+# Using literal values
+class PostsController < ApplicationController
+  content_security_policy do |p|
+    p.base_uri "https://www.example.com"
+  end
+end
+
+# Using mixed static and dynamic values
+class PostsController < ApplicationController
+  content_security_policy do |p|
+    p.base_uri :self, -> { "https://#{current_user.domain}.example.com" }
+  end
+end
+
+# Disabling the global CSP
+class LegacyPagesController < ApplicationController
+  content_security_policy false, only: :index
+end
+```
+
+Use the `content_security_policy_report_only`
+configuration attribute to set
+[Content-Security-Policy-Report-Only](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy-Report-Only)
+in order to report only content violations for migrating
+legacy content
+
+```ruby
+# config/initializers/content_security_policy.rb
+Rails.application.config.content_security_policy_report_only = true
+```
+
+```ruby
+# Controller override
+class PostsController < ApplicationController
+  content_security_policy_report_only only: :index
+end
+```
+
+You can enable automatic nonce generation:
+
+```ruby
+# config/initializers/content_security_policy.rb
+Rails.application.config.content_security_policy do |policy|
+  policy.script_src :self, :https
+end
+
+Rails.application.config.content_security_policy_nonce_generator = -> request { SecureRandom.base64(16) }
+```
+
+Then you can add an automatic nonce value by passing `nonce: true`
+as part of `html_options`. Example:
+
+```html+erb
+<%= javascript_tag nonce: true do -%>
+  alert('Hello, World!');
+<% end -%>
+```
+
+Use [`csp_meta_tag`](http://api.rubyonrails.org/classes/ActionView/Helpers/CspHelper.html#method-i-csp_meta_tag)
+helper to create a meta tag "csp-nonce" with the per-session nonce value
+for allowing inline `<script>` tags.
+
+```html+erb
+<head>
+  <%= csp_meta_tag %>
+</head>
+```
+
+This is used by the Rails UJS helper to create dynamically
+loaded inline `<script>` elements.
+
 Environmental Security
 ----------------------