0
@@ -1,37 +1,45 @@
0
+h1. Internal Changes to code
0
 
0
-Following best practices recommended in
0
-* "The OWASP Guide to Building Secure Web Applications":http://www.owasp.org/index.php/Category:OWASP_Guide_Project
0
-* "Secure Programming for Linux and Unix HOWTO":http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/web-authentication.html
0
-* http://www.coresecuritypatterns.com/patterns.htm
0
+As always, this is just a copy-and-pasted version of the CHANGELOG file in the source code tree.
0
 
0
-They're described in more detail below.
0
+h2. Changes for the May, 2008 version of restful-authentication
0
 
0
-h2. Changes to session_controller
0
+h3. Changes to user model
0
+
0
+* recently_activated? belongs only if stateful
0
+* Gave migration a 40-char limit on remember_token & an index on users by login
0
+* **Much** stricter login and email validation
0
+* put length constraints in migration too
0
+* password in 6, 40
0
+* salt and remember_token now much less predictability
0
+
0
+h3. Changes to session_controller
0
 
0
 * use uniform logout function
0
+* use uniform remember_cookie functions
0
 * avoid calling logged_in? which will auto-log-you-in (safe in the face of
0
-  logout! call, but idiot-proof
0
-* log in is where reset_session is really needed -- wherever it goes, it has to
0
-  be in front of the current_user= call
0
-* using uniform remember_cookie functions
0
+  logout! call, but idiot-proof)
0
+* Moved reset_session into only the "now logged in" branch
0
+** wherever it goes, it has to be in front of the current_user= call
0
+** See more in README-Tradeoffs.txt
0
 * made a place to take action on failed login attempt
0
 * recycle login and remember_me setting on failed login
0
 * nil'ed out the password field in 'new' view
0
 
0
 h3. Changes to users_controller
0
 
0
+* use uniform logout function
0
+* use uniform remember_cookie functions
0
+* Moved reset_session into only the "now logged in" branch
0
+** wherever it goes, it has to be in front of the current_user= call
0
+** See more in README-Tradeoffs.txt
0
 * made the implicit login only happen for non-activationed sites
0
-* made logout / session_reset'ing uniform across controllers
0
 * On a failed signup, kick you back to the signin screen (but strip out the password & confirmation)
0
-* use uniform logout function
0
 * more descriptive error messages in activate()
0
-* don't auto-login on activate.  If the plugin is going to, there needs to be a
0
-  single point of entry among session/new, users/new and users/activate.
0
 
0
 h3. users_helper
0
 
0
-* link_to_user, link_to_current_user, link_to_signin_with_IP convenience
0
-  functions
0
+* link_to_user, link_to_current_user, link_to_signin_with_IP 
0
 * if_authorized(action, resource, &block) view function (with appropriate
0
   warning)
0
 
0
@@ -39,12 +47,11 @@ h3. authenticated_system
0
 
0
 * Made authorized? take optional arguments action=nil, resource=nil, *args
0
   This makes its signature better match traditional approaches to access control
0
-  eg Reference Monitor in \"Security Patterns\":http://www.securitypatterns.org/patterns.html)
0
+  eg Reference Monitor in "Security Patterns":http://www.securitypatterns.org/patterns.html)
0
 * authorized? should be a helper too
0
 * added uniform logout! methods
0
 * format.any (as found in access_denied) doesn't work until
0
   http://dev.rubyonrails.org/changeset/8987 lands.
0
-  
0
 * cookies are now refreshed each time we cross the logged out/in barrier
0
   http://www.owasp.org/index.php/Session_Management#Regeneration_of_Session_Tokens
0
   http://palisade.plynt.com/issues/2004Jul/safe-auth-practices/
0
@@ -56,138 +63,13 @@ h3. authenticated_system
0
   exposure as helper methods.  But if there's a less kludgy fix please educate
0
   me.
0
 
0
-h3. Changes to model
0
-
0
-* recently_activated? belongs only if stateful
0
-* Gave migration a 40-char limit on remember_token & an index on users by login
0
-
0
-h4. Token generation
0
-
0
-The salt and the remember_token should be generated from completely
0
-unpredictable, irreversible input.  Using the user's email and Time.now leave
0
-the improbable but feasible attack of watching a person (whose email you've
0
-captured) log in with 'remember me', then replaying the hash of their email and
0
-times +/- a few seconds.  I made salt, activation_code and remember_token calls
0
-all use the same call, and I increased the entropy of that call.
0
-
0
-h4. Token regeneration
0
-
0
-The session and the remember_token should both be expired and regenerated
0
-every time we cross the logged out / logged in barrier by either password
0
-or cookie.  ("To reduce the risk from session hijacking":http://www.owasp.org/index.php/Session_Management#Regeneration_of_Session_Tokens
0
-and brute force attacks, the HTTP server can seamlessly expire and
0
-regenerate tokens. This decreases the window of opportunity for a replay or
0
-brute force attack.)
0
-
0
-h4. Session resetting
0
-
0
-I moved the reset_session call in the session controller (and the
0
-users_controller on signup) into the 'success' path -- the CSRF can't do
0
-anything until the user logs in. Since a redirect follows, it doesn't give
0
-request-forgery crapstains going forward, though hitting back button and
0
-resubmiting an earlier form will.  I think it's Mostly Harmless but I've left it
0
-commented out.  
0
-
0
-I'd like to get the advice of someone who understands CSRF better than I on this
0
-change.  This says we _should_ reset the session:
0
-
0
-  (http://tinyurl.com/5vdvuq) Regenerate session IDs upon privilege
0
-  changes. Most Web applications assign a session ID upon the first request for
0
-  a URL, even for anonymous users. If the user logs in, then the application
0
-  should create and assign a new session ID to the user. This not only
0
-  represents that the user has authenticated, but it reduces the chances of
0
-  eavesdropping attacks if the initial access to the application wasn't
0
-  conducted over SSL. It also mitigates against session fixation attacks
0
-  discussed earlier in the chapter, where an attacker goes to a site and gets a
0
-  session ID, then e-mails it to the victim and allows them to log in using the
0
-  ID that the attacker already knows
0
-
0
-
0
-
0
-h2. Non-backwards compatible Changes
0
-
0
-Here are a few changes that increase "Defense in Depth" but will invalidate
0
-existing login/passwords without a migration.
0
-
0
-* If you have an existing site, none of these changes are compelling enough to
0
-  warrant migrating your userbase.
0
-* If you are generating for a new site, all of these changes are low-impact.
0
-  You should apply them.
0
-
0
-h3. minor changes
0
-
0
-* login in /\w+\.\-_@/  This allows (most) email addresses and is safe for urls, database expressions (@, technically reserved in a url, will survive in most browsers)
0
-  If you want to be more permissive:
0
-  "URL-legal characters":http://www.blooberry.com/indexdot/html/topics/urlencoding.htm are <nowiki>-_.!~*'()</nowiki>
0
-  "XML-legal characters":http://www.sklar.com/blog/archives/96-XML-vs.-Control-Characters.html are <nowiki>Char ::= #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]</nowiki>
0
-  "Email-address legal characters":http://tools.ietf.org/html/rfc2822#section-3.4.1 are <nowiki>0-9a-zA-Z!#\$%\&\'\*\+_/=\?^\-`\{|\}~\.</nowiki> but see "this discussion of what is sane"http://www.regular-expressions.info/email.html (as opposed to legal)
0
-* put length constraints in migration too
0
-* password in 6, 40
0
-* Trivial email validation
0
-* Added site key to generator, users.yml.
0
-* Made site key generation idempotent in the most crude and hackish way
0
-
0
-h3. Site key
0
-
0
-A Site key gives additional protection against a dictionary attack if your
0
-DB is ever compromised.  With no site key, we store
0
-  DB_password = hash(user_password, DB_user_salt)
0
-If your database were to be compromised you'd be vulnerable to a dictionary
0
-attack on all your stupid users' passwords.  With a site key, we store
0
-  DB_password = hash(user_password, DB_user_salt, Code_site_key)
0
-That means an attacker needs access to both your site's code *and* its
0
-database to mount an "offline dictionary attack.":http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/web-authentication.html
0
-
0
-It's probably of minor importance, but recommended by best practices: 'defense
0
-in depth'.  Needless to say, if you upload this to github or the youtubes or
0
-otherwise place it in public view you'll kinda defeat the point.  Your users'
0
-passwords are still secure, and the world won't end, but defense_in_depth -= 1.
0
-
0
-Please note: if you change this, all the passwords will be invalidated, so DO
0
-keep it someplace secure.  Use the random value given or type in the lyrics to
0
-your favorite Jay-Z song or something; any moderately long, unpredictable text.
0
-
0
-h3. Password Encryption Stretching
0
-
0
-Repeated applications of the hash make brute force (even with a compromised
0
-database and site key) harder, and scale with Moore's law.
0
-
0
-  bq. "To squeeze the most security out of a limited-entropy password or
0
-  passphrase, we can use two techniques [salting and stretching]... that are so
0
-  simple and obvious that they should be used in every password system.  There
0
-  is really no excuse not to use them. ... Choose stretching factor so computing
0
-  K from (salt, passwd) takes 200-1000 ms. Store r with the user's password, and
0
-  increase it as computers get faster." -- http://tinyurl.com/37lb73
0
-  Practical Security (Ferguson & Scheier) p350
0
-
0
-Now, adding even a 0.2s delay to page requests isn't justifiable for most online
0
-applications, and storing r is unnecessary (at least on your first design
0
-iteration).  But 
0
-  On a 1G Slicehost already under moderate load:
0
-  irb(main):005:0> puts Time.now; (10**6).times{ secure_digest(Time.now, rand) }; puts Time.now
0
-  Fri May 16 08:26:16 +0000 2008
0
-  Fri May 16 08:30:58 +0000 2008
0
-  => 280s/1M ~= 0.000_3 ms / digest
0
-A modest 10 (the default here) foldings makes brute forcing, even given the site
0
-key and database, 10 times harder at a 3ms penalty.  An app that otherwise
0
-serves 100 reqs/s is reduced to 78 signin reqs/s; an app that does 10reqs/s is
0
-reduced to 9.7 signin reqs/s
0
-
0
-More:
0
-* http://www.owasp.org/index.php/Hashing_Java
0
-* "An Illustrated Guide to Cryptographic Hashes":http://www.unixwiz.net/techtips/iguide-crypto-hashes.html
0
-
0
-
0
-h3. Views
0
+h3. Other
0
 
0
 * Used escapes <%= %> in email templates (among other reasons, so courtenay's
0
   "'dumbass' test":http://tinyurl.com/684g9t doesn't complain)
0
-
0
-h3. Specs
0
-
0
-* 100% coverage (needed some access_control checks, and the http_auth stuff)
0
-
0
-h3. Stories
0
-
0
-* added them
0
+* Added site key to generator, users.yml.
0
+* Made site key generation idempotent in the most crude and hackish way
0
+* 100% coverage apart from the stateful code. (needed some access_control
0
+  checks, and the http_auth stuff)
0
+* Stories!
0
 

0
@@ -1,28 +1,94 @@
0
-This is mrflip's fork of "technoweenie's restful-authentication":/technoweenie/restful-authentication/
0
-plugin. The goal is to
0
-
0
-* Modularize to match security design patterns:
0
-** Authentication (currently: password, browser cookie token, HTTP basic)
0
-** Trust metric (email validation) 
0
-** Authorization (stateful roles)
0
-* Add full RSpec and Story test suite
0
+h1. Restful Authentication Generator
0
+
0
+This widely-used plugin provides a foundation for securely managing user
0
+authentication:
0
+* Login / logout
0
+* Secure password handling
0
+* Account activation by validating email
0
+* Account approval / disabling by admin
0
+* Rudimentary hooks for authorization and access control.
0
+
0
+Several features were updated in May, 2008.  The newest version of this plugin
0
+may be found in
0
+  http://github.com/technoweenie/restful-authentication/tree/master
0
+While a "classic" (backward-compatible) version may be found in
0
+  http://github.com/technoweenie/restful-authentication/tree/classic
0
+
0
+  !! important: if you upgrade your site, existing user account !!
0
+  !! passwords will stop working unless you use --old-passwords !!
0
+
0
+This page has notes on
0
+* "Installation":#INSTALL
0
+* "Compatibility Warning":#COMPATIBILITY
0
+* "New Features":#AWESOME
0
+* "After installing":#POST-INSTALL
0
+
0
+See the "wiki":http://github.com/technoweenie/restful-authentication/wikis/home
0
+(or the notes/ directory) if you want to learn more about:
0
+
0
+* "Security Design Patterns":Security-Patterns with "snazzy diagram":http://github.com/technoweenie/restful-authentication/tree/master/notes/SecurityFramework.png
0
+* [[Authentication]] -- Lets a visitor identify herself (and lay  claim to her corresponding Roles and measure of Trust)
0
+* "Trust Metrics":Trustification -- Confidence we can rely on the outcomes of this visitor's actions.
0
+* [[Authorization]] and Policy -- Based on trust and identity, what actions may this visitor perform?
0
+* [[Access Control]] -- How the Authorization policy is actually enforced in your code (A: hopefully without turning it into  a spaghetti of if thens)
0
+* [[Rails Plugins]] for Authentication, Trust,  Authorization and Access Control
0
+* [[Tradeoffs]] -- for the paranoid or the curious, a rundown of tradeoffs made in the code
0
+* [[CHANGELOG]] -- Summary of changes to internals
0
+* [[TODO]] -- Ideas for how you can help
0
+
0
+These best version of the release notes are in the notes/ directory in the
0
+"source code":http://github.com/technoweenie/restful-authentication/tree/master
0
+-- look there for the latest version.  The wiki versions are taken (manually)
0
+from there.
0
+  
0
+***************************************************************************
0
+<a id="AWESOME"/> </a>
0
+h2. Exciting new features
0
+
0
+h3. Stories
0
+
0
+There are now RSpec stories that allow expressive, enjoyable tests for the
0
+authentication code. The flexible code for resource testing in stories was
0
+extended from "Ben Mabey's.":http://www.benmabey.com/2008/02/04/rspec-plain-text-stories-webrat-chunky-bacon/
0
+
0
+h3. Modularize to match security design patterns:
0
+* Authentication (currently: password, browser cookie token, HTTP basic)
0
+* Trust metric (email validation) 
0
+* Authorization (stateful roles)
0
 * Leave a flexible framework that will play nicely with other access control / policy definition / trust metric plugins
0
 
0
-See the "wiki":http://github.com/mrflip/restful-authentication/wikis/home for notes on
0
-* "Security Design Patterns":Security-Patterns
0
-* [[Authentication]] -- Lets a visitor identify herself (and lay claim to her corresponding Roles and measure of Trust)
0
-* "Trust Metrics":Trustification -- Confidence we can rely on the outcomes of this visitor's actions.
0
-* "Authorization and Policy":Authorization -- Based on trust and identity, what actions may this visitor perform?
0
-* "Access Control":Access-Control -- How the Authorization policy is actually enforced in your code (hopefully without turning it into a spaghetti of if thens)
0
-* "Rails Security Plugins":RailsPlugins -- for Authentication, Trust, Authorization and Access Control
0
+h3. Other
0
+* Added a few helper methods for linking to user pages
0
+* Uniform handling of logout, remember_token
0
+* Stricter email, login field validation
0
+* Minor security fixes -- see CHANGELOG
0
 
0
-These best versions are in the notes/ directory in the "source code":http://github.com/mrflip/restful-authentication/tree/master -- look there for the latest version.
0
-The wiki versions are taken (manually) from there.
0
+***************************************************************************
0
+<a id="COMPATIBILITY"/> </a>
0
+h2. Non-backwards compatible Changes
0
 
0
-===========================================================================
0
+Here are a few changes in the May 2008 release that increase "Defense in Depth"
0
+but may require changes to existing accounts
0
 
0
-Restful Authentication Generator
0
-====
0
+* If you have an existing site, none of these changes are compelling enough to
0
+  warrant migrating your userbase.
0
+* If you are generating for a new site, all of these changes are low-impact.
0
+  You should apply them.
0
+
0
+h3. Passwords
0
+
0
+The new password encryption (using a site key salt and stretching) will break
0
+existing user accounts' passwords.  We recommend you use the --old-passwords
0
+option or write a migration tool and submit it as a patch.  See the
0
+[[Tradeoffs]] note for more information.
0
+
0
+h3. Validations
0
+
0
+By default, 
0
+
0
+***************************************************************************
0
+<a id="INSTALL"/> </a>
0
+h2. Installation
0
 
0
 This is a basic restful authentication generator for rails, taken from
0
 acts as authenticated.  Currently it requires Rails 1.2.6 or above.
0
@@ -34,76 +100,73 @@ To use:
0
     --stateful \
0
     --rspec \
0
     --skip-migration \
0
-    --skip-routes
0
+    --skip-routes \
0
+    --old-passwords
0
 
0
-The first parameter specifies the model that gets created in signup
0
-(typically a user or account model).  A model with migration is
0
-created, as well as a basic controller with the create method.
0
+* The first parameter specifies the model that gets created in signup (typically
0
+  a user or account model).  A model with migration is created, as well as a
0
+  basic controller with the create method. You probably want to say "User" here.
0
 
0
-The second parameter specifies the sessions controller name.  This is
0
-the controller that handles the actual login/logout function on the
0
-site.
0
+* The second parameter specifies the session controller name.  This is the
0
+  controller that handles the actual login/logout function on the site.
0
+  (probably: "Session").
0
 
0
-The third parameter (--include-activation) generates the code for a
0
-ActionMailer and its respective Activation Code through email.
0
+* --include-activation: Generates the code for a ActionMailer and its respective
0
+  Activation Code through email.
0
 
0
-The fourth (--stateful) builds in support for acts_as_state_machine and
0
-generates activation code.  (--stateful implies --include-activation).
0
-This was taken from:
0
+* --stateful: Builds in support for acts_as_state_machine and generates
0
+  activation code.  (@--stateful@ implies @--include-activation@). Based on the
0
+  idea at [[http://www.vaporbase.com/postings/stateful_authentication]]. Passing
0
+  @--skip-migration@ will skip the user migration, and @--skip-routes@ will skip
0
+  resource generation -- both useful if you've already run this generator.
0
 
0
-http://www.vaporbase.com/postings/stateful_authentication
0
+* --rspec: Generate RSpec tests and Stories in place of standard rails tests.
0
+  This requires the
0
+    "RSpec and Rspec-on-rails plugins":http://rspec.info/
0
+  (make sure you "./script/generate rspec" after installing RSpec.)  The rspec
0
+  and story suite are much more thorough than the rails tests, and changes are
0
+  unlikely to be backported.
0
+  
0
+* --old-passwords: Use the older password scheme (see [[#COMPATIBILITY]], above)
0
 
0
-Passing --skip-migration will skip the user migration, and --skip-routes will
0
-skip resource generation -- both useful if you've already run this generator.
0
+* --skip-migration: Don't generate a migration file for this model
0
 
0
-Pass --rspec to generate a (more thorough) set of RSpec tests.  This
0
-requires the RSpec and Rspec-on-rails plugins: http://rspec.info/
0
+* --skip-routes: Don't generate a resource line in @config/routes.rb@
0
 
0
-***************************************************************************
0
-Post-install
0
-
0
-The below assumes a Model named 'User' and a Controller named
0
-'Session'; please alter to suit.
0
-
0
-Try these for some familiar login URLs if you like:
0
-  map.signup  '/signup', :controller => 'users',   :action => 'new'
0
-  map.signin  '/login',  :controller => 'session', :action => 'new'
0
-  map.signout '/logout', :controller => 'session', :action => 'destroy'
0
-
0
-With --include-activation:
0
 
0
-* Add a route to config/routes.rb:
0
-    map.activate '/activate/:activation_code', :controller => 'users', :action => 'activate', :activation_code => nil)
0
-
0
-* Add an observer to config/environment.rb:
0
+***************************************************************************
0
+<a id="POST-INSTALL"/> </a>
0
+h2. After installing
0
+
0
+The below assumes a Model named 'User' and a Controller named 'Session'; please
0
+alter to suit. There are additional security minutae in @notes/README-Tradeoffs@
0
+-- only the paranoid or the curious need bother, though.
0
+
0
+* Add these familiar login URLs to your @config/routes.rb@ if you like:
0
+
0
+     map.signup  '/signup', :controller => 'users',   :action => 'new' @
0
+     map.signin  '/login',  :controller => 'session', :action => 'new' @
0
+     map.signout '/logout', :controller => 'session', :action => 'destroy' @
0
+    
0
+* With @--include-activation@, also add to your @config/routes.rb@:
0
+  
0
+    map.activate '/activate/:activation_code', :controller => 'users', :action => 'activate', :activation_code => nil) 
0
+    
0
+  and add an observer to @config/environment.rb@:
0
+  
0
     config.active_record.observers = :users_observer
0
 
0
-* Add an observer to config/environment.rb
0
-  config.active_record.observers = :user_observer # or whatever you 
0
-                                                  # named your model
0
-
0
-With --stateful:
0
-
0
-* If you're using acts_as_state_machine, define your users resource like this:
0
+* With @--stateful@, add an observer to config/environment.rb:
0
+  
0
+    config.active_record.observers = :user_observer
0
+  
0
+  and modify the users resource line to read
0
+  
0
     map.resources :users, :member => { :suspend   => :put,
0
                                        :unsuspend => :put,
0
-                                       :purge     => :delete }
0
-
0
-Security Alert
0
-====
0
-
0
-I introduced a change to the model controller that's been tripping 
0
-folks up on Rails 2.0.  The change was added as a suggestion to help
0
-combat session fixation attacks.  However, this resets the Form 
0
-Authentication token used by Request Forgery Protection.  I've left
0
-it out now, since Rails 1.2.6 and Rails 2.0 will both stop session
0
-fixation attacks anyway.
0
-
0
-***************************************************************************
0
-Stories
0
-
0
-There are now RSpec stories that allow expressive enjoyable tests for the
0
-authentication code.
0
+                                       :purge     => :delete } 
0
 
0
-The flexible code for resource testing came out of code from Ben Mabey
0
-http://www.benmabey.com/2008/02/04/rspec-plain-text-stories-webrat-chunky-bacon/
0
+* If you use a public repository for your code (such as github, rubyforge,
0
+  gitorious, etc.) make sure to NOT post your site_keys.rb (add a line like
0
+  '/config/initializers/site_keys.rb' to your .gitignore or do the svn ignore
0
+  dance), but make sure you DO keep it backed up somewhere safe.