Merge pull request #13945 from rails/json_cookie_serializer_improvements

Cookies serializer improvements

3 files changed, 47 insertions, 20 deletions

diff --git a/guides/source/4_1_release_notes.md b/guides/source/4_1_release_notes.md
index 90e6b2fcbc..8fcfc71351 100644
--- a/guides/source/4_1_release_notes.md
+++ b/guides/source/4_1_release_notes.md
@@ -346,10 +346,8 @@ for detailed changes.
   params "deep munging" that was used to address security vulnerability
   CVE-2013-0155. ([Pull Request](https://github.com/rails/rails/pull/13188))
 
-* Added `:serializer` option for `config.session_store :cookie_store`. This
-  changes default serializer when using
-  `:cookie_store`. ([Pull Request](https://github.com/rails/rails/pull/13692))
-
+* New config option `config.action_dispatch.cookies_serializer` for specifying
+  a serializer for the signed and encrypted cookie jars. (Pull Requests [1](https://github.com/rails/rails/pull/13692), [2](https://github.com/rails/rails/pull/13945) / [More Details](upgrading_ruby_on_rails.html#cookies-serializer))
 
 Action Mailer
 -------------
diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md
index 9eaf03dd82..222d86afe9 100644
--- a/guides/source/action_controller_overview.md
+++ b/guides/source/action_controller_overview.md
@@ -381,22 +381,6 @@ You can also pass a `:domain` key and specify the domain name for the cookie:
 YourApp::Application.config.session_store :cookie_store, key: '_your_app_session', domain: ".example.com"
 ```
 
-You can pass `:serializer` key to specify serializer for serializing session:
-
-```ruby
-YourApp::Application.config.session_store :cookie_store, key: '_your_app_session', serializer: :json
-```
-
-The default serializer for new application is `:json`. For compatibility with
-old applications `:marshal` is used when `serializer` option is not specified.
-
-It is also possible to pass a custom serializer class with `load` and `dump`
-public methods defined:
-
-```ruby
-YourApp::Application.config.session_store :cookie_store, key: '_your_app_session', serializer: MyCustomSerializer
-```
-
 Rails sets up (for the CookieStore) a secret key used for signing the session data. This can be changed in `config/initializers/secret_token.rb`
 
 ```ruby
@@ -588,6 +572,38 @@ end
 
 Note that while for session values you set the key to `nil`, to delete a cookie value you should use `cookies.delete(:key)`.
 
+Rails also provides a signed cookie jar and an encrypted cookie jar for storing
+sensitive data. The signed cookie jar appends a cryptographic signature on the
+cookie values to protect their integrity. The encrypted cookie jar encrypts the
+values in addition to signing them, so that they cannot be read by the end user.
+Refer to the [API documentation](http://api.rubyonrails.org/classes/ActionDispatch/Cookies.html)
+for more details.
+
+These special cookie jars use a serializer to serialize the assigned values into
+strings and deserializes them into Ruby objects on read.
+
+You can specify what serializer to use:
+
+```ruby
+Rails.application.config.action_dispatch.cookies_serializer = :json
+```
+
+The default serializer for new applications is `:json`. For compatibility with
+old applications with existing cookies, `:marshal` is used when `serializer`
+option is not specified.
+
+You may also set this option to `:hybrid`, in which case Rails would transparently
+deserialize existing (`Marshal`-serialized) cookies on read and re-write them in
+the `JSON` format. This is useful for migrating existing applications to the
+`:json` serializer.
+
+It is also possible to pass a custom serializer that responds to `load` and
+`dump`:
+
+```ruby
+Rails.application.config.action_dispatch.cookies_serializer = MyCustomSerializer
+```
+
 Rendering XML and JSON data
 ---------------------------
 
diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md
index 2055452935..8aae3bbc1a 100644
--- a/guides/source/upgrading_ruby_on_rails.md
+++ b/guides/source/upgrading_ruby_on_rails.md
@@ -98,6 +98,19 @@ If your test helper contains a call to
 is now done automatically when you `require 'test_help'`, although
 leaving this line in your helper is not harmful in any way.
 
+### Cookies serializer
+
+Applications created before Rails 4.1 uses `Marshal` to serialize cookie values into
+the signed and encrypted cookie jars. If you want to use the new `JSON`-based format
+in your application, you can add an initializer file with the following content:
+
+  ```ruby
+  Rails.application.config.cookies_serializer :hybrid
+  ```
+
+This would transparently migrate your existing `Marshal`-serialized cookies into the
+new `JSON`-based format.
+
 ### Changes in JSON handling
 
 There are a few major changes related to JSON handling in Rails 4.1.