.gitignore @@ -1,37 +1,45 @@ +h1. Internal Changes to code -Following best practices recommended in -* "The OWASP Guide to Building Secure Web Applications":http://www.owasp.org/index.php/Category:OWASP_Guide_Project -* "Secure Programming for Linux and Unix HOWTO":http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/web-authentication.html -* http://www.coresecuritypatterns.com/patterns.htm +As always, this is just a copy-and-pasted version of the CHANGELOG file in the source code tree. -They're described in more detail below. +h2. Changes for the May, 2008 version of restful-authentication -h2. Changes to session_controller +h3. Changes to user model + +* recently_activated? belongs only if stateful +* Gave migration a 40-char limit on remember_token & an index on users by login +* **Much** stricter login and email validation +* put length constraints in migration too +* password in 6, 40 +* salt and remember_token now much less predictability + +h3. Changes to session_controller * use uniform logout function +* use uniform remember_cookie functions * avoid calling logged_in? which will auto-log-you-in (safe in the face of - logout! call, but idiot-proof -* log in is where reset_session is really needed -- wherever it goes, it has to - be in front of the current_user= call -* using uniform remember_cookie functions + logout! call, but idiot-proof) +* Moved reset_session into only the "now logged in" branch +** wherever it goes, it has to be in front of the current_user= call +** See more in README-Tradeoffs.txt * made a place to take action on failed login attempt * recycle login and remember_me setting on failed login * nil'ed out the password field in 'new' view h3. Changes to users_controller +* use uniform logout function +* use uniform remember_cookie functions +* Moved reset_session into only the "now logged in" branch +** wherever it goes, it has to be in front of the current_user= call +** See more in README-Tradeoffs.txt * made the implicit login only happen for non-activationed sites -* made logout / session_reset'ing uniform across controllers * On a failed signup, kick you back to the signin screen (but strip out the password & confirmation) -* use uniform logout function * more descriptive error messages in activate() -* don't auto-login on activate. If the plugin is going to, there needs to be a - single point of entry among session/new, users/new and users/activate. h3. users_helper -* link_to_user, link_to_current_user, link_to_signin_with_IP convenience - functions +* link_to_user, link_to_current_user, link_to_signin_with_IP * if_authorized(action, resource, &block) view function (with appropriate warning) @@ -39,12 +47,11 @@ h3. authenticated_system * Made authorized? take optional arguments action=nil, resource=nil, *args This makes its signature better match traditional approaches to access control - eg Reference Monitor in \"Security Patterns\":http://www.securitypatterns.org/patterns.html) + eg Reference Monitor in "Security Patterns":http://www.securitypatterns.org/patterns.html) * authorized? should be a helper too * added uniform logout! methods * format.any (as found in access_denied) doesn't work until http://dev.rubyonrails.org/changeset/8987 lands. - * cookies are now refreshed each time we cross the logged out/in barrier http://www.owasp.org/index.php/Session_Management#Regeneration_of_Session_Tokens http://palisade.plynt.com/issues/2004Jul/safe-auth-practices/ @@ -56,138 +63,13 @@ h3. authenticated_system exposure as helper methods. But if there's a less kludgy fix please educate me. -h3. Changes to model - -* recently_activated? belongs only if stateful -* Gave migration a 40-char limit on remember_token & an index on users by login - -h4. Token generation - -The salt and the remember_token should be generated from completely -unpredictable, irreversible input. Using the user's email and Time.now leave -the improbable but feasible attack of watching a person (whose email you've -captured) log in with 'remember me', then replaying the hash of their email and -times +/- a few seconds. I made salt, activation_code and remember_token calls -all use the same call, and I increased the entropy of that call. - -h4. Token regeneration - -The session and the remember_token should both be expired and regenerated -every time we cross the logged out / logged in barrier by either password -or cookie. ("To reduce the risk from session hijacking":http://www.owasp.org/index.php/Session_Management#Regeneration_of_Session_Tokens -and brute force attacks, the HTTP server can seamlessly expire and -regenerate tokens. This decreases the window of opportunity for a replay or -brute force attack.) - -h4. Session resetting - -I moved the reset_session call in the session controller (and the -users_controller on signup) into the 'success' path -- the CSRF can't do -anything until the user logs in. Since a redirect follows, it doesn't give -request-forgery crapstains going forward, though hitting back button and -resubmiting an earlier form will. I think it's Mostly Harmless but I've left it -commented out. - -I'd like to get the advice of someone who understands CSRF better than I on this -change. This says we _should_ reset the session: - - (http://tinyurl.com/5vdvuq) Regenerate session IDs upon privilege - changes. Most Web applications assign a session ID upon the first request for - a URL, even for anonymous users. If the user logs in, then the application - should create and assign a new session ID to the user. This not only - represents that the user has authenticated, but it reduces the chances of - eavesdropping attacks if the initial access to the application wasn't - conducted over SSL. It also mitigates against session fixation attacks - discussed earlier in the chapter, where an attacker goes to a site and gets a - session ID, then e-mails it to the victim and allows them to log in using the - ID that the attacker already knows - - - -h2. Non-backwards compatible Changes - -Here are a few changes that increase "Defense in Depth" but will invalidate -existing login/passwords without a migration. - -* If you have an existing site, none of these changes are compelling enough to - warrant migrating your userbase. -* If you are generating for a new site, all of these changes are low-impact. - You should apply them. - -h3. minor changes - -* 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) - If you want to be more permissive: - "URL-legal characters":http://www.blooberry.com/indexdot/html/topics/urlencoding.htm are <nowiki>-_.!~*'()</nowiki> - "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> - "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) -* put length constraints in migration too -* password in 6, 40 -* Trivial email validation -* Added site key to generator, users.yml. -* Made site key generation idempotent in the most crude and hackish way - -h3. Site key - -A Site key gives additional protection against a dictionary attack if your -DB is ever compromised. With no site key, we store - DB_password = hash(user_password, DB_user_salt) -If your database were to be compromised you'd be vulnerable to a dictionary -attack on all your stupid users' passwords. With a site key, we store - DB_password = hash(user_password, DB_user_salt, Code_site_key) -That means an attacker needs access to both your site's code *and* its -database to mount an "offline dictionary attack.":http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/web-authentication.html - -It's probably of minor importance, but recommended by best practices: 'defense -in depth'. Needless to say, if you upload this to github or the youtubes or -otherwise place it in public view you'll kinda defeat the point. Your users' -passwords are still secure, and the world won't end, but defense_in_depth -= 1. - -Please note: if you change this, all the passwords will be invalidated, so DO -keep it someplace secure. Use the random value given or type in the lyrics to -your favorite Jay-Z song or something; any moderately long, unpredictable text. - -h3. Password Encryption Stretching - -Repeated applications of the hash make brute force (even with a compromised -database and site key) harder, and scale with Moore's law. - - bq. "To squeeze the most security out of a limited-entropy password or - passphrase, we can use two techniques [salting and stretching]... that are so - simple and obvious that they should be used in every password system. There - is really no excuse not to use them. ... Choose stretching factor so computing - K from (salt, passwd) takes 200-1000 ms. Store r with the user's password, and - increase it as computers get faster." -- http://tinyurl.com/37lb73 - Practical Security (Ferguson & Scheier) p350 - -Now, adding even a 0.2s delay to page requests isn't justifiable for most online -applications, and storing r is unnecessary (at least on your first design -iteration). But - On a 1G Slicehost already under moderate load: - irb(main):005:0> puts Time.now; (10**6).times{ secure_digest(Time.now, rand) }; puts Time.now - Fri May 16 08:26:16 +0000 2008 - Fri May 16 08:30:58 +0000 2008 - => 280s/1M ~= 0.000_3 ms / digest -A modest 10 (the default here) foldings makes brute forcing, even given the site -key and database, 10 times harder at a 3ms penalty. An app that otherwise -serves 100 reqs/s is reduced to 78 signin reqs/s; an app that does 10reqs/s is -reduced to 9.7 signin reqs/s - -More: -* http://www.owasp.org/index.php/Hashing_Java -* "An Illustrated Guide to Cryptographic Hashes":http://www.unixwiz.net/techtips/iguide-crypto-hashes.html - - -h3. Views +h3. Other * Used escapes <%= %> in email templates (among other reasons, so courtenay's "'dumbass' test":http://tinyurl.com/684g9t doesn't complain) - -h3. Specs - -* 100% coverage (needed some access_control checks, and the http_auth stuff) - -h3. Stories - -* added them +* Added site key to generator, users.yml. +* Made site key generation idempotent in the most crude and hackish way +* 100% coverage apart from the stateful code. (needed some access_control + checks, and the http_auth stuff) +* Stories! CHANGELOG @@ -1,28 +1,94 @@ -This is mrflip's fork of "technoweenie's restful-authentication":/technoweenie/restful-authentication/ -plugin. The goal is to - -* Modularize to match security design patterns: -** Authentication (currently: password, browser cookie token, HTTP basic) -** Trust metric (email validation) -** Authorization (stateful roles) -* Add full RSpec and Story test suite +h1. Restful Authentication Generator + +This widely-used plugin provides a foundation for securely managing user +authentication: +* Login / logout +* Secure password handling +* Account activation by validating email +* Account approval / disabling by admin +* Rudimentary hooks for authorization and access control. + +Several features were updated in May, 2008. The newest version of this plugin +may be found in + http://github.com/technoweenie/restful-authentication/tree/master +While a "classic" (backward-compatible) version may be found in + http://github.com/technoweenie/restful-authentication/tree/classic + + !! important: if you upgrade your site, existing user account !! + !! passwords will stop working unless you use --old-passwords !! + +This page has notes on +* "Installation":#INSTALL +* "Compatibility Warning":#COMPATIBILITY +* "New Features":#AWESOME +* "After installing":#POST-INSTALL + +See the "wiki":http://github.com/technoweenie/restful-authentication/wikis/home +(or the notes/ directory) if you want to learn more about: + +* "Security Design Patterns":Security-Patterns with "snazzy diagram":http://github.com/technoweenie/restful-authentication/tree/master/notes/SecurityFramework.png +* [[Authentication]] -- Lets a visitor identify herself (and lay claim to her corresponding Roles and measure of Trust) +* "Trust Metrics":Trustification -- Confidence we can rely on the outcomes of this visitor's actions. +* [[Authorization]] and Policy -- Based on trust and identity, what actions may this visitor perform? +* [[Access Control]] -- How the Authorization policy is actually enforced in your code (A: hopefully without turning it into a spaghetti of if thens) +* [[Rails Plugins]] for Authentication, Trust, Authorization and Access Control +* [[Tradeoffs]] -- for the paranoid or the curious, a rundown of tradeoffs made in the code +* [[CHANGELOG]] -- Summary of changes to internals +* [[TODO]] -- Ideas for how you can help + +These best version of the release notes are in the notes/ directory in the +"source code":http://github.com/technoweenie/restful-authentication/tree/master +-- look there for the latest version. The wiki versions are taken (manually) +from there. + +*************************************************************************** +<a id="AWESOME"/> </a> +h2. Exciting new features + +h3. Stories + +There are now RSpec stories that allow expressive, enjoyable tests for the +authentication code. The flexible code for resource testing in stories was +extended from "Ben Mabey's.":http://www.benmabey.com/2008/02/04/rspec-plain-text-stories-webrat-chunky-bacon/ + +h3. Modularize to match security design patterns: +* Authentication (currently: password, browser cookie token, HTTP basic) +* Trust metric (email validation) +* Authorization (stateful roles) * Leave a flexible framework that will play nicely with other access control / policy definition / trust metric plugins -See the "wiki":http://github.com/mrflip/restful-authentication/wikis/home for notes on -* "Security Design Patterns":Security-Patterns -* [[Authentication]] -- Lets a visitor identify herself (and lay claim to her corresponding Roles and measure of Trust) -* "Trust Metrics":Trustification -- Confidence we can rely on the outcomes of this visitor's actions. -* "Authorization and Policy":Authorization -- Based on trust and identity, what actions may this visitor perform? -* "Access Control":Access-Control -- How the Authorization policy is actually enforced in your code (hopefully without turning it into a spaghetti of if thens) -* "Rails Security Plugins":RailsPlugins -- for Authentication, Trust, Authorization and Access Control +h3. Other +* Added a few helper methods for linking to user pages +* Uniform handling of logout, remember_token +* Stricter email, login field validation +* Minor security fixes -- see CHANGELOG -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. -The wiki versions are taken (manually) from there. +*************************************************************************** +<a id="COMPATIBILITY"/> </a> +h2. Non-backwards compatible Changes -=========================================================================== +Here are a few changes in the May 2008 release that increase "Defense in Depth" +but may require changes to existing accounts -Restful Authentication Generator -==== +* If you have an existing site, none of these changes are compelling enough to + warrant migrating your userbase. +* If you are generating for a new site, all of these changes are low-impact. + You should apply them. + +h3. Passwords + +The new password encryption (using a site key salt and stretching) will break +existing user accounts' passwords. We recommend you use the --old-passwords +option or write a migration tool and submit it as a patch. See the +[[Tradeoffs]] note for more information. + +h3. Validations + +By default, + +*************************************************************************** +<a id="INSTALL"/> </a> +h2. Installation This is a basic restful authentication generator for rails, taken from acts as authenticated. Currently it requires Rails 1.2.6 or above. @@ -34,76 +100,73 @@ To use: --stateful \ --rspec \ --skip-migration \ - --skip-routes + --skip-routes \ + --old-passwords -The first parameter specifies the model that gets created in signup -(typically a user or account model). A model with migration is -created, as well as a basic controller with the create method. +* The first parameter specifies the model that gets created in signup (typically + a user or account model). A model with migration is created, as well as a + basic controller with the create method. You probably want to say "User" here. -The second parameter specifies the sessions controller name. This is -the controller that handles the actual login/logout function on the -site. +* The second parameter specifies the session controller name. This is the + controller that handles the actual login/logout function on the site. + (probably: "Session"). -The third parameter (--include-activation) generates the code for a -ActionMailer and its respective Activation Code through email. +* --include-activation: Generates the code for a ActionMailer and its respective + Activation Code through email. -The fourth (--stateful) builds in support for acts_as_state_machine and -generates activation code. (--stateful implies --include-activation). -This was taken from: +* --stateful: Builds in support for acts_as_state_machine and generates + activation code. (@--stateful@ implies @--include-activation@). Based on the + idea at [[http://www.vaporbase.com/postings/stateful_authentication]]. Passing + @--skip-migration@ will skip the user migration, and @--skip-routes@ will skip + resource generation -- both useful if you've already run this generator. -http://www.vaporbase.com/postings/stateful_authentication +* --rspec: Generate RSpec tests and Stories in place of standard rails tests. + This requires the + "RSpec and Rspec-on-rails plugins":http://rspec.info/ + (make sure you "./script/generate rspec" after installing RSpec.) The rspec + and story suite are much more thorough than the rails tests, and changes are + unlikely to be backported. + +* --old-passwords: Use the older password scheme (see [[#COMPATIBILITY]], above) -Passing --skip-migration will skip the user migration, and --skip-routes will -skip resource generation -- both useful if you've already run this generator. +* --skip-migration: Don't generate a migration file for this model -Pass --rspec to generate a (more thorough) set of RSpec tests. This -requires the RSpec and Rspec-on-rails plugins: http://rspec.info/ +* --skip-routes: Don't generate a resource line in @config/routes.rb@ -*************************************************************************** -Post-install - -The below assumes a Model named 'User' and a Controller named -'Session'; please alter to suit. - -Try these for some familiar login URLs if you like: - map.signup '/signup', :controller => 'users', :action => 'new' - map.signin '/login', :controller => 'session', :action => 'new' - map.signout '/logout', :controller => 'session', :action => 'destroy' - -With --include-activation: -* Add a route to config/routes.rb: - map.activate '/activate/:activation_code', :controller => 'users', :action => 'activate', :activation_code => nil) - -* Add an observer to config/environment.rb: +*************************************************************************** +<a id="POST-INSTALL"/> </a> +h2. After installing + +The below assumes a Model named 'User' and a Controller named 'Session'; please +alter to suit. There are additional security minutae in @notes/README-Tradeoffs@ +-- only the paranoid or the curious need bother, though. + +* Add these familiar login URLs to your @config/routes.rb@ if you like: + + map.signup '/signup', :controller => 'users', :action => 'new' @ + map.signin '/login', :controller => 'session', :action => 'new' @ + map.signout '/logout', :controller => 'session', :action => 'destroy' @ + +* With @--include-activation@, also add to your @config/routes.rb@: + + map.activate '/activate/:activation_code', :controller => 'users', :action => 'activate', :activation_code => nil) + + and add an observer to @config/environment.rb@: + config.active_record.observers = :users_observer -* Add an observer to config/environment.rb - config.active_record.observers = :user_observer # or whatever you - # named your model - -With --stateful: - -* If you're using acts_as_state_machine, define your users resource like this: +* With @--stateful@, add an observer to config/environment.rb: + + config.active_record.observers = :user_observer + + and modify the users resource line to read + map.resources :users, :member => { :suspend => :put, :unsuspend => :put, - :purge => :delete } - -Security Alert -==== - -I introduced a change to the model controller that's been tripping -folks up on Rails 2.0. The change was added as a suggestion to help -combat session fixation attacks. However, this resets the Form -Authentication token used by Request Forgery Protection. I've left -it out now, since Rails 1.2.6 and Rails 2.0 will both stop session -fixation attacks anyway. - -*************************************************************************** -Stories - -There are now RSpec stories that allow expressive enjoyable tests for the -authentication code. + :purge => :delete } -The flexible code for resource testing came out of code from Ben Mabey -http://www.benmabey.com/2008/02/04/rspec-plain-text-stories-webrat-chunky-bacon/ +* If you use a public repository for your code (such as github, rubyforge, + gitorious, etc.) make sure to NOT post your site_keys.rb (add a line like + '/config/initializers/site_keys.rb' to your .gitignore or do the svn ignore + dance), but make sure you DO keep it backed up somewhere safe. README e9e046262d06f30765f0030202179250d3b07a1f Philip (flip) Kromer flip@infochimps.org http://github.com/smartocci/modulr-authentication/commit/68cbb447208e1a9cf6d82e961aad2c129bd0d455 68cbb447208e1a9cf6d82e961aad2c129bd0d455 2008-05-19T09:30:47-07:00 2008-05-19T09:30:47-07:00 Organized README, CHANGELOG and notes/; renamed notes/* (removed README- prefix) 59812ec7bc19bc6264ba3086ad3f5e9c5892a8f8 Philip (flip) Kromer flip@infochimps.org