Improve documentation around the cookie store auto-upgrade to encryption

1 files changed, 37 insertions, 22 deletions

diff --git a/actionpack/lib/action_dispatch/middleware/session/cookie_store.rb b/actionpack/lib/action_dispatch/middleware/session/cookie_store.rb
index a603b33b45..b9eb8036e9 100644
--- a/actionpack/lib/action_dispatch/middleware/session/cookie_store.rb
+++ b/actionpack/lib/action_dispatch/middleware/session/cookie_store.rb
@@ -4,36 +4,51 @@ require 'rack/session/cookie'
 
 module ActionDispatch
   module Session
-    # This cookie-based session store is the Rails default. Sessions typically
-    # contain at most a user_id and flash message; both fit within the 4K cookie
-    # size limit. Cookie-based sessions are dramatically faster than the
-    # alternatives.
+    # This cookie-based session store is the Rails default. It is
+    # dramatically faster than the alternatives.
     #
-    # If you have more than 4K of session data or don't want your data to be
-    # visible to the user, pick another session store.
+    # Sessions typically contain at most a user_id and flash message; both fit
+    # within the 4K cookie size limit. A CookieOverflow exception is raised if
+    # you attempt to store more than 4K of data.
     #
-    # CookieOverflow is raised if you attempt to store more than 4K of data.
+    # The cookie jar used for storage is automatically configured to be the
+    # best possible option given your application's configuration.
     #
-    # A message digest is included with the cookie to ensure data integrity:
-    # a user cannot alter his +user_id+ without knowing the secret key
-    # included in the hash. New apps are generated with a pregenerated secret
-    # in config/environment.rb. Set your own for old apps you're upgrading.
+    # If you only have secret_token set, your cookies will be signed, but
+    # not encrypted. This means a user cannot alter his +user_id+ without
+    # knowing your app's secret key, but can easily read his +user_id+. This
+    # was the default for Rails 3 apps.
     #
-    # Session options:
+    # If you have secret_key_base set, your cookies will be encrypted. This
+    # goes a step further than signed cookies in that encrypted cookies cannot
+    # be altered or read by users. This is the default starting in Rails 4.
     #
-    # * <tt>:secret</tt>: An application-wide key string. It's important that
-    #   the secret is not vulnerable to a dictionary attack. Therefore, you
-    #   should choose a secret consisting of random numbers and letters and
-    #   more than 30 characters.
+    # If you have both secret_token and secret_key base set, your cookies will
+    # be encrypted, and signed cookies generated by Rails 3 will be
+    # transparently read and encrypted to provide a smooth upgrade path.
     #
-    #     secret: '449fe2e7daee471bffae2fd8dc02313d'
+    # Configure your session store in config/initializers/session_store.rb:
     #
-    # * <tt>:digest</tt>: The message digest algorithm used to verify session
-    #   integrity defaults to 'SHA1' but may be any digest provided by OpenSSL,
-    #   such as 'MD5', 'RIPEMD160', 'SHA256', etc.
+    #   Myapp::Application.config.session_store :cookie_store, key: '_your_app_session'
     #
-    # To generate a secret key for an existing application, run
-    # "rake secret" and set the key in config/initializers/secret_token.rb.
+    # Configure your secret key in config/initializers/secret_token.rb:
+    #
+    #   Myapp::Application.config.secret_key_base 'secret key'
+    #
+    # To generate a secret key for an existing application, run `rake secret`.
+    #
+    # If you are upgrading an existing Rails 3 app, you should leave your
+    # existing secret_token in place and simply add the new secret_key_base.
+    # Note that you should wait to set secret_key_base until you have 100% of
+    # your userbase on Rails 4 and are reasonably sure you will not need to
+    # rollback to Rails 3. This is because cookies signed based on the new
+    # secret_key_base in Rails 4 are not backwards compatible with Rails 3.
+    # You are free to leave your existing secret_token in place, not set the
+    # new secret_key_base, and ignore the deprecation warnings until you are
+    # reasonably sure that your upgrade is otherwise complete. Additionally,
+    # you should take care to make sure you are not relying on the ability to
+    # decode signed cookies generated by your app in external applications or
+    # Javascript before upgrading.
     #
     # Note that changing digest or secret invalidates all existing sessions!
     class CookieStore < Rack::Session::Abstract::ID