kotovalexarian-likes-github/rails--rails
1
0
Fork 0
mirror of https://github.com/rails/rails.git synced 2022-11-09 12:12:34 -05:00
Code Releases Activity

Merge pull request #10031 from trevorturk/cookie-store-auto-upgrade-docs

Browse source 
Improve documentation around the cookie store auto-upgrade to encryption
This commit is contained in:
Santiago Pastorino 2013-04-01 10:45:55 -07:00
commit e456ad514a
2 changed files with 40 additions and 23 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

59
actionpack/lib/action_dispatch/middleware/session/cookie_store.rb
View file

@ -4,36 +4,51 @@ require 'rack/session/cookie'
module ActionDispatch module ActionDispatch
module Session module Session
# This cookie-based session store is the Rails default. Sessions typically # This cookie-based session store is the Rails default. It is
# contain at most a user_id and flash message; both fit within the 4K cookie # dramatically faster than the alternatives.
# size limit. Cookie-based sessions are dramatically faster than the
# alternatives.
# #
# If you have more than 4K of session data or don't want your data to be # Sessions typically contain at most a user_id and flash message; both fit
# visible to the user, pick another session store. # 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: # If you only have secret_token set, your cookies will be signed, but
# a user cannot alter his +user_id+ without knowing the secret key # not encrypted. This means a user cannot alter his +user_id+ without
# included in the hash. New apps are generated with a pregenerated secret # knowing your app's secret key, but can easily read his +user_id+. This
# in config/environment.rb. Set your own for old apps you're upgrading. # 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 # If you have both secret_token and secret_key base set, your cookies will
# the secret is not vulnerable to a dictionary attack. Therefore, you # be encrypted, and signed cookies generated by Rails 3 will be
# should choose a secret consisting of random numbers and letters and # transparently read and encrypted to provide a smooth upgrade path.
# more than 30 characters.
# #
# secret: '449fe2e7daee471bffae2fd8dc02313d' # Configure your session store in config/initializers/session_store.rb:
# #
# * <tt>:digest</tt>: The message digest algorithm used to verify session # Myapp::Application.config.session_store :cookie_store, key: '_your_app_session'
# integrity defaults to 'SHA1' but may be any digest provided by OpenSSL,
# such as 'MD5', 'RIPEMD160', 'SHA256', etc.
# #
# To generate a secret key for an existing application, run # Configure your secret key in config/initializers/secret_token.rb:
# "rake secret" and set the 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! # Note that changing digest or secret invalidates all existing sessions!
class CookieStore < Rack::Session::Abstract::ID class CookieStore < Rack::Session::Abstract::ID

4
guides/source/upgrading_ruby_on_rails.md
View file

@ -94,7 +94,7 @@ Please note that you should wait to set `secret_key_base` until you have 100% of
If you are relying on the ability for external applications or Javascript to be able to read your Rails app's signed session cookies (or signed cookies in general) you should not set `secret_key_base` until you have decoupled these concerns. If you are relying on the ability for external applications or Javascript to be able to read your Rails app's signed session cookies (or signed cookies in general) you should not set `secret_key_base` until you have decoupled these concerns.
* Rails 4.0 encrypts the contents of cookie-based sessions if `secret_key_base` has been set. Rails 3.x signed, but did not encrypt, the contents of cookie-based session. Signed cookies are "secure" in that they are verified to have been generated by your app and are tamper-proof. However, the contents can be viewed by end users, and encrypting the contents eliminates this caveat/concern. * Rails 4.0 encrypts the contents of cookie-based sessions if `secret_key_base` has been set. Rails 3.x signed, but did not encrypt, the contents of cookie-based session. Signed cookies are "secure" in that they are verified to have been generated by your app and are tamper-proof. However, the contents can be viewed by end users, and encrypting the contents eliminates this caveat/concern without a significant performance penalty.
As described above, existing signed cookies generated with Rails 3.x will be transparently upgraded if you leave your existing `secret_token` in place and add the new `secret_key_base`. As described above, existing signed cookies generated with Rails 3.x will be transparently upgraded if you leave your existing `secret_token` in place and add the new `secret_key_base`.
@ -106,6 +106,8 @@ As described above, existing signed cookies generated with Rails 3.x will be tra
The same caveats apply here, too. You should wait to set `secret_key_base` until you have 100% of your userbase on Rails 4.x and are reasonably sure you will not need to rollback to Rails 3.x. You should also 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. The same caveats apply here, too. You should wait to set `secret_key_base` until you have 100% of your userbase on Rails 4.x and are reasonably sure you will not need to rollback to Rails 3.x. You should also 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.
Please read [Pull Request #9978](https://github.com/rails/rails/pull/9978) for details on the move to encrypted session cookies.
* Rails 4.0 removed the `ActionController::Base.asset_path` option. Use the assets pipeline feature. * Rails 4.0 removed the `ActionController::Base.asset_path` option. Use the assets pipeline feature.
* Rails 4.0 has deprecated `ActionController::Base.page_cache_extension` option. Use `ActionController::Base.default_static_extension` instead. * Rails 4.0 has deprecated `ActionController::Base.page_cache_extension` option. Use `ActionController::Base.default_static_extension` instead.