unified_csrf_prevention 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: efb44eb12723e4bc987a8480023d81806f5802ef
+  data.tar.gz: b77f535be345db63c4949fa3ede96d9c52f11768
+SHA512:
+  metadata.gz: dec3d84b3db6f629fbb25049e7bbab44fdf769bfad03352c504967c7cba4e76e9b47de0a46af5bd0b968e6fde33932c2002d6a3c9f3e77dda66ce06d3ce33dc7
+  data.tar.gz: c72c8c82e6740c1d239da46e1320d83b8a5b3092e8ed0271a444525a375f52106b3db77167295967a8f4f2871717a9b939f98a67e09c8a74a26feb60d7c9c800

data/.gitignore

@@ -0,0 +1,5 @@
+.bundle
+Gemfile.lock
+*.log
+pkg/
+gemfiles/

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,24 @@
+AllCops:
+  TargetRubyVersion: 2.3
+  Exclude:
+    - 'spec/dummy/**/*'
+    - 'gems/**/*'
+
+Metrics/LineLength:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*.rb'
+
+Layout/IndentationWidth:
+  Enabled: false
+
+Layout/ElseAlignment:
+  Enabled: false
+
+Style/TrailingCommaInLiteral:
+  Enabled: false
+
+Lint/EndAlignment:
+  Enabled: false

data/Appraisals

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+appraise 'rails-4.2' do
+  gem 'rails', '~>4.2'
+end
+
+appraise 'rails-5.0' do
+  gem 'rails', '~>5.0'
+end
+
+appraise 'rails-5.1' do
+  gem 'rails', '~>5.1'
+end
+
+appraise 'rails-5.2' do
+  gem 'rails', '~>5.2'
+end

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 1.0.0
+
+The first open source version, functionally equivalent to Xing's internal
+xing-csrf_prevention gem v1.0.0.

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017-2018 XING SE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,90 @@
+# Unified CSRF Protection for Rails
+
+This gem is a drop-in upgrade for request forgery protection in Rails 4 and 5 with the following benefits:
+
+* It is self-healing by design. Whenever a user comes in with an invalid authenticity token, they will have a valid one sent back along with the error response so the next request will succeed. There's no need for the user to reload the page.
+* The CSRF protection is decoupled from the users' sessions that could eventually get wiped out or overwritten, resulting in errors.
+* The approach is framework/language agnostic, so the token generated by one application will be accepted by any other, including non-Rails applications (given they implement the same CSRF protection scheme).
+* The mechanism is stateless from the backend's perspective. The data is stored in the browser's cookies, requiring no backend storage.
+* The solution design was audited by Xing Security team and [cure53](https://cure53.de).
+* It is both React- and jQuery-friendly.
+
+Please read the [Cross-application CSRF Prevention specification](https://github.com/xing/cross-application-csrf-prevention) for design and implementation details.
+
+## Configuring Your Application
+
+1. Add the gem to the `Gemfile`:
+
+```ruby
+gem 'unified_csrf_prevention'
+```
+
+2. Set the shared secret key configuration value for `production`, `preview` and whatever other environment your have:
+
+```ruby
+Rails.application.configure do
+  # existing configuration settings
+
+  config.unified_csrf_prevention_key = '64 random characters'
+end
+```
+
+3. Replace the unobtrusive scripting adapter that adds the `X-CSRF-Token` header which comes with Rails with this one (assuming jQuery is used):
+
+```js
+$.ajaxPrefilter(function(options) {
+  var token = (document.cookie.match(/(?:^|;\s*)csrf_token=([^;]+)/) || [])[1];
+
+  if (token) {
+    options.headers["X-CSRF-Token"] = token;
+  }
+});
+```
+
+Important note: **the token must be read from cookies for each and every frontend request the application makes. It is not acceptable to read the token once and store it in some variable, DOM node or in any other form.**
+
+In other words, please do exactly what the provided snippet does - for any request read the token from the cookie right before the request is sent. Don't try to cache the token, transfer it from the backend, or optimize out the cookie access, otherwise your application could end up using invalid tokens.
+
+If your application uses something different from jQuery to make AJAX calls, please adjust the snippet accordingly. The key parts are running the code before each request is sent, and setting the header with the value read from the cookie. Basically, `$.ajaxPrefilter` and `options.headers` should be replaced with something that works with the library you use instead of jQuery.
+
+If your application for some reason has several different ways to send AJAX requests, you need to adjust all of them.
+
+## Usage
+
+The gem is seamlessly integrated with Rails' built-in request forgery protection mechanism so there's nothing special to be done on top of the regular `protect_from_forgery` controller setting.
+Authenticity tokens transferred in hidden inputs as well as per-form authenticity tokens introduced in Rails 5 just work out of the box.
+See [Ruby on Rails Security Guide](http://guides.rubyonrails.org/security.html#csrf-countermeasures) for details.
+
+## Testing Controllers with Forgery Protection Enabled
+
+Sometimes it's necessary to test the controller code with the actual forgery protection mechanisms enabled (`allow_forgery_protection` overwritten in tests).
+Providing the cookies for requests to make `unified_csrf_prevention` work is a bit of a hassle, so instead it's possible to mock the token validation and thus make the controller accept the supplied token:
+
+```ruby
+describe '#some_action' do
+  context 'when requested with valid csrf token' do
+    let(:csrf_token) { controller.send(:form_authenticity_token) }
+
+    before do
+      allow(controller).to receive(:valid_token?).with(csrf_token).and_return true
+    end
+
+    it 'executes action' do
+      post :some_action, authenticity_token: csrf_token
+      expect(response).to be_ok
+    end
+  end
+end
+```
+
+## Compatibility
+
+The gem is compatible with Rails 4.2, 5.0, 5.1 and 5.2.
+
+## Running Specs
+
+```bash
+rubocop
+appraisal install
+appraisal rspec
+```

data/Rakefile

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'

data/lib/unified_csrf_prevention/core.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'openssl'
+require 'securerandom'
+
+require 'rails'
+require 'active_support/security_utils'
+
+module UnifiedCsrfPrevention
+  # Low-level routines and constants
+  # See https://github.com/xing/cross-application-csrf-prevention#low-level-implementation-details
+  module Core
+    TOKEN_COOKIE_NAME = 'csrf_token'
+    CHECKSUM_COOKIE_NAME = 'csrf_checksum'
+    TOKEN_RACK_ENV_VAR = 'unified_csrf_prevention.token'
+
+    class << self
+      def generate_token
+        random_bytes_needed = (ActionController::Base::AUTHENTICITY_TOKEN_LENGTH * 0.75).ceil # Base 64 requires four bytes to store three bytes of data
+        random_bytes = SecureRandom.random_bytes(random_bytes_needed)
+        encode(random_bytes)[0...ActionController::Base::AUTHENTICITY_TOKEN_LENGTH]
+      end
+
+      def checksum_for(token)
+        digest_algorithm = OpenSSL::Digest::SHA256.new
+        token_digest = OpenSSL::HMAC.digest(digest_algorithm, shared_secret_key, token)
+        encode(token_digest)
+      end
+
+      def valid_token?(token, checksum)
+        !token.nil? && !checksum.nil? && ActiveSupport::SecurityUtils.secure_compare(checksum_for(token), checksum)
+      end
+
+      private
+
+      def shared_secret_key
+        Rails.configuration.unified_csrf_prevention_key
+      rescue NoMethodError
+        raise UnifiedCsrfPrevention::ConfigurationError, 'Configuration setting `unified_csrf_prevention_key` is not defined'
+      end
+
+      def encode(binary_string)
+        Base64.urlsafe_encode64(binary_string, padding: false)
+      end
+    end
+  end
+end

data/lib/unified_csrf_prevention/middleware.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'unified_csrf_prevention/core'
+
+module UnifiedCsrfPrevention
+  # Rack middleware to set the token and checksum cookies
+  # See https://github.com/xing/cross-application-csrf-prevention#token-generation
+  class Middleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      status, headers, body = @app.call(env)
+
+      if env.key?(Core::TOKEN_RACK_ENV_VAR)
+        token = env[Core::TOKEN_RACK_ENV_VAR]
+        set_csrf_cookies!(headers, token)
+        Rails.logger.info("Set CSRF token: #{token}")
+      end
+
+      [status, headers, body]
+    end
+
+    private
+
+    def set_csrf_cookies!(headers, token)
+      checksum = Core.checksum_for(token)
+
+      set_cookie!(headers, Core::TOKEN_COOKIE_NAME, value: token)
+      set_cookie!(headers, Core::CHECKSUM_COOKIE_NAME, value: checksum, httponly: true)
+    end
+
+    def set_cookie!(headers, name, data)
+      cookie = {
+        path: '/',
+        secure: secure_cookies?,
+        same_site: :strict,
+      }.merge(data)
+
+      Rack::Utils.set_cookie_header!(headers, name, cookie)
+    end
+
+    def secure_cookies?
+      Rails.env.production? || Rails.env.preview?
+    end
+  end
+end

data/lib/unified_csrf_prevention/railtie.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+require 'unified_csrf_prevention/middleware'
+require 'unified_csrf_prevention/request_forgery_protection'
+
+module UnifiedCsrfPrevention
+  # A Railtie to automagically set up the gem's middleware and include
+  # the controller concern when the gem is loaded
+  class Railtie < Rails::Railtie
+    initializer :unified_csrf_prevention_middleware do |app|
+      app.middleware.use UnifiedCsrfPrevention::Middleware
+    end
+
+    initializer :unified_csrf_prevention_concern do
+      ActiveSupport.on_load :action_controller do
+        include UnifiedCsrfPrevention::RequestForgeryProtection
+      end
+    end
+  end
+end

data/lib/unified_csrf_prevention/request_forgery_protection.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+require 'unified_csrf_prevention/core'
+require 'unified_csrf_prevention/middleware'
+
+module UnifiedCsrfPrevention
+  # ApplicationController concern implementing request authenticity validation
+  # See https://github.com/xing/cross-application-csrf-prevention#application-action-filter
+  module RequestForgeryProtection
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def protect_from_forgery(options = {})
+        super
+        prepend_before_action :setup_csrf_token
+      end
+    end
+
+    private
+
+    def valid_authenticity_token?(_session, token)
+      valid_token?(token) || super
+    end
+
+    def compare_with_real_token(token, _session)
+      valid_token?(token)
+    end
+
+    def real_csrf_token(_session)
+      csrf_token
+    end
+
+    def setup_csrf_token
+      csrf_token
+    end
+
+    def csrf_token
+      @csrf_token ||= if valid_token?(existing_token) && token_of_correct_length?(existing_token)
+        existing_token
+      else
+        new_token
+      end
+    end
+
+    def new_token
+      raise UnifiedCsrfPrevention::ConfigurationError, 'UnifiedCsrfPrevention::Middleware middleware must be used' unless Rails.configuration.middleware.include?(UnifiedCsrfPrevention::Middleware)
+      request.env[Core::TOKEN_RACK_ENV_VAR] = Core.generate_token
+    end
+
+    def valid_token?(token)
+      Core.valid_token?(token, checksum)
+    end
+
+    def existing_token
+      request.cookies[Core::TOKEN_COOKIE_NAME]
+    end
+
+    def checksum
+      request.cookies[Core::CHECKSUM_COOKIE_NAME]
+    end
+
+    def token_of_correct_length?(token)
+       token.length == ActionController::RequestForgeryProtection::AUTHENTICITY_TOKEN_LENGTH
+    end
+  end
+end

data/lib/unified_csrf_prevention/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module UnifiedCsrfPrevention
+  VERSION = '1.0.0'
+end

data/lib/unified_csrf_prevention.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'unified_csrf_prevention/version'
+require 'unified_csrf_prevention/railtie'
+
+module UnifiedCsrfPrevention
+  class ConfigurationError < RuntimeError; end
+end

data/spec/controllers/dummy_controller_spec.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+describe DummyController, type: :controller do
+  let(:new_token) { 'This should be exactly 32 bytes.' }
+  let(:short_token) { '😻' }
+
+  before do
+    ActionController::Base.allow_forgery_protection = true # RSpec unconditionally disallows the forgery protection in controller tests
+    allow(UnifiedCsrfPrevention::Core).to receive(:generate_token).and_return(new_token)
+  end
+
+  describe '#index' do
+    render_views
+
+    let(:perform_request) do
+      get :index
+    end
+
+    context 'when token and checksum cookies not sent' do
+      let(:output_token) { new_token }
+
+      it_behaves_like 'an action that outputs the csrf token'
+      it_behaves_like 'an action that outputs the csrf cookies'
+    end
+
+    context 'when token and checksum cookies sent' do
+      include_context 'with token and checksum'
+
+      context 'with a valid token' do
+        let(:valid_token?) { true }
+        let(:output_token) { token }
+
+        it_behaves_like 'an action that outputs the csrf token'
+        it_behaves_like 'an action that does not output the csrf cookies'
+      end
+
+      context 'with a valid but short token' do
+        let(:valid_token?) { true }
+        let(:token) { short_token }
+        let(:output_token) { new_token }
+
+        it_behaves_like 'an action that outputs the csrf token'
+        it_behaves_like 'an action that outputs the csrf cookies'
+      end
+
+      context 'with an invalid token' do
+        let(:valid_token?) { false }
+        let(:output_token) { new_token }
+
+        it_behaves_like 'an action that outputs the csrf token'
+        it_behaves_like 'an action that outputs the csrf cookies'
+      end
+    end
+
+    context 'when cookies middleware is not installed' do
+      before do
+        allow(Rails.application.config.middleware).to receive(:include?).with(UnifiedCsrfPrevention::Middleware).and_return(false)
+      end
+
+      it 'raises a configuration error' do
+        expect { perform_request }.to raise_error UnifiedCsrfPrevention::ConfigurationError
+      end
+    end
+  end
+
+  describe '#success' do
+    let(:perform_request) do
+      get :success
+    end
+
+    context 'when token and checksum cookies not sent' do
+      let(:output_token) { new_token }
+
+      it_behaves_like 'an action that outputs the csrf cookies'
+    end
+
+    context 'when token and checksum cookies sent' do
+      include_context 'with token and checksum'
+
+      context 'with a valid token' do
+        let(:valid_token?) { true }
+        let(:output_token) { token }
+
+        it_behaves_like 'an action that does not output the csrf cookies'
+      end
+
+      context 'with an invalid token' do
+        let(:valid_token?) { false }
+        let(:output_token) { new_token }
+
+        it_behaves_like 'an action that outputs the csrf cookies'
+      end
+    end
+  end
+
+  describe '#update' do
+    context 'when token and checksum cookies not sent' do
+      let(:output_token) { new_token }
+
+      context 'request has no parameters' do
+        include_context 'empty update request'
+
+        it_behaves_like 'an action that responds with a csrf validation error'
+        it_behaves_like 'an action that outputs the csrf cookies'
+      end
+
+      context 'request includes a csrf token form parameter' do
+        let(:token) { 'some token out of nowhere' }
+        include_context 'update request with a csrf token form parameter'
+
+        it_behaves_like 'an action that responds with a csrf validation error'
+        it_behaves_like 'an action that outputs the csrf cookies'
+      end
+
+      context 'request includes a csrf token header' do
+        let(:token) { 'some token out of nowhere' }
+        include_context 'update request with a csrf token header'
+
+        it_behaves_like 'an action that responds with a csrf validation error'
+        it_behaves_like 'an action that outputs the csrf cookies'
+      end
+    end
+
+    context 'when token and checksum cookies sent' do
+      include_context 'with token and checksum'
+
+      context 'with a valid token' do
+        let(:valid_token?) { true }
+
+        context 'and token is of shorter length' do
+          let(:token) { short_token }
+          let(:output_token) { new_token }
+
+          include_context 'update request with a csrf token header'
+
+          it_behaves_like 'an action that responds with OK'
+          it_behaves_like 'an action that outputs the csrf cookies'
+        end
+
+        context 'request has no parameters' do
+          include_context 'empty update request'
+
+          it_behaves_like 'an action that responds with a csrf validation error'
+          it_behaves_like 'an action that does not output the csrf cookies'
+        end
+
+        context 'request includes a csrf token form parameter' do
+          include_context 'update request with a csrf token form parameter'
+
+          it_behaves_like 'an action that responds with OK'
+          it_behaves_like 'an action that does not output the csrf cookies'
+        end
+
+        context 'request includes a csrf token form parameter which was generated on the backend' do
+          include_context 'update request with a fetched csrf token form parameter'
+
+          it_behaves_like 'an action that responds with OK'
+          it_behaves_like 'an action that does not output the csrf cookies'
+        end
+
+        context 'request includes a csrf token header' do
+          include_context 'update request with a csrf token header'
+
+          it_behaves_like 'an action that responds with OK'
+          it_behaves_like 'an action that does not output the csrf cookies'
+        end
+      end
+
+      context 'with an invalid token' do
+        let(:valid_token?) { false }
+        let(:output_token) { new_token }
+
+        context 'request has no parameters' do
+          include_context 'empty update request'
+
+          it_behaves_like 'an action that responds with a csrf validation error'
+          it_behaves_like 'an action that outputs the csrf cookies'
+        end
+
+        context 'request includes a csrf form parameter' do
+          include_context 'update request with a csrf token form parameter'
+
+          it_behaves_like 'an action that responds with a csrf validation error'
+          it_behaves_like 'an action that outputs the csrf cookies'
+        end
+
+        context 'request includes a csrf token header' do
+          include_context 'update request with a csrf token header'
+
+          it_behaves_like 'an action that responds with a csrf validation error'
+          it_behaves_like 'an action that outputs the csrf cookies'
+        end
+      end
+    end
+  end
+
+  describe 'on_load hook' do
+    context 'is triggered twice' do
+      before do
+        ActiveSupport.run_load_hooks(:action_controller, ActionController::Base)
+        ActiveSupport.run_load_hooks(:action_controller, ActionController::Base)
+      end
+
+      it 'includes RequestForgeryProtection only ones' do
+        expect(ActionController::Base.included_modules.find_all { |m| m == UnifiedCsrfPrevention::RequestForgeryProtection }.length).to be 1
+      end
+    end
+  end
+end