module Roda::RodaPlugins::RouteCsrf

  1. lib/roda/plugins/route_csrf.rb

The route_csrf plugin is the recommended plugin to use to support CSRF protection in Roda applications. This plugin allows you set where in the routing tree to enforce CSRF protection. Additionally, the route_csrf plugin uses modern security practices.

By default, the plugin requires tokens be specific to the request method and request path, so a CSRF token generated for one form will not be usable to submit a different form.

This plugin also takes care to not expose the underlying CSRF key (except in the session), so that it is not possible for an attacker to generate valid CSRF tokens specific to an arbitrary request method and request path even if they have access to a token that is not specific to request method and request path. To get this security benefit, you must ensure an attacker does not have access to the session. Rack::Session::Cookie uses signed sessions, not encrypted sessions, so if the attacker has the ability to read cookie data and you are using Rack::Session::Cookie, it will still be possible for an attacker to generate valid CSRF tokens specific to arbitrary request method and request path.

# Usage

It is recommended to use the plugin defaults, loading the plugin with no options:

plugin :route_csrf

This plugin supports the following options:

:field :: Form input parameter name for CSRF token (default: '_csrf')
:header :: HTTP header name for CSRF token (default: 'X-CSRF-Token')
:key :: Session key for CSRF secret (default: '_roda_csrf_secret')
:require_request_specific_tokens :: Whether request-specific tokens are required (default: true).
                                    A false value will allow tokens that are not request-specific
                                    to also work.  You should only set this to false if it is
                                    impossible to use request-specific tokens.  If you must
                                    use non-request-specific tokens in certain cases, it is best
                                    to leave this option true by default, and override it on a
                                    per call basis in those specific cases.
:csrf_failure :: The action to taken if a request fails the CSRF check (default: :raise).  Options:
                 :raise :: raise a Roda::RodaPlugins::RouteCsrf::InvalidToken exception
                 :empty_403 :: return a blank 403 page (rack_csrf's default behavior)
                 :clear_session :: Clear the current session
                 Proc :: Treated as a routing block, called with request object
:check_header :: Whether the HTTP header should be checked for the token value (default: false).
                 If true, checks the HTTP header after checking for the form input parameter.
                 If :only, only checks the HTTP header and doesn't check the form input parameter.
:check_request_methods :: Which request methods require CSRF protection
                          (default: <tt>['POST', 'DELETE', 'PATCH', 'PUT']</tt>)
:upgrade_from_rack_csrf_key :: If provided, the session key that should be checked for the
                               rack_csrf raw token.  If the session key is present, the value
                               will be checked against the submitted token, and if it matches,
                               the CSRF check will be passed.  Should only be set temporarily
                               if upgrading from using rack_csrf to the route_csrf plugin, and
                               should be removed as soon as you are OK with CSRF forms generated
                               before the upgrade not longer being usable. The default rack_csrf
                               key is <tt>'csrf.token'</tt>.

The plugin also supports a block, in which case the block will be used as the value of the :csrf_failure option.

# Methods

This adds the following instance methods:


Used for checking if the submitted CSRF token is valid. If a block is provided, it is treated as a routing block if the CSRF token is not valid. Otherwise, by default, raises a Roda::RodaPlugins::RouteCsrf::InvalidToken exception if a CSRF token is necessary for the request and there is no token provided or the provided token is not valid. Options can be provided to override any of the plugin options for this specific call. The :token option can be used to specify the provided CSRF token (instead of looking for the token in the submitted parameters).


The field name to use for the hidden tag containing the CSRF token.


This takes an argument that would be the value of the HTML form's action attribute, and returns a path you can pass to csrf_token that should be valid for the form submission. The argument should either be nil or a string representing a relative path, absolute path, or full URL.

csrf_tag(path=nil, method='POST')

An HTML hidden input tag string containing the CSRF token, suitable for placing in an HTML form. Takes the same arguments as csrf_token.

csrf_token(path=nil, method='POST')

The value of the csrf token, in case it needs to be accessed directly. It is recommended to call this method with a path, which will create a request-specific token. Calling this method without an argument will create a token that is not specific to the request, but such a token will only work if you set the :require_request_specific_tokens option to false, which is a bad idea from a security standpoint.


Whether the plugin is configured to only support request-specific tokens, true by default.


Returns whether the submitted CSRF token is valid (also true if the request does not require a CSRF token). Takes same option hash as check_csrf!.

This plugin also adds the following instance methods for compatibility with the older csrf plugin, but it is not recommended to use these methods in new code:


The header name to use for submitting the CSRF token via an HTTP header (useful for javascript). Note that this plugin will not look in the HTTP header by default, it will only do so if the :check_header option is used.


An HTML meta tag string containing the CSRF token, suitable for placing in the page header. It is not recommended to use this method, as the token generated is not request-specific and will not work unless you set the :require_request_specific_tokens option to false, which is a bad idea from a security standpoint.

# Token Cryptography

route_csrf uses HMAC-SHA-256 to generate all CSRF tokens. It generates a random 32-byte secret, which is stored base64 encoded in the session. For each CSRF token, it generates 31 bytes of random data.

For request-specific CSRF tokens, this pseudocode generates the HMAC:

hmac = HMAC(secret, method + path + random_data)

For CSRF tokens not specific to a request, this pseudocode generates the HMAC:

hmac = HMAC(secret, random_data)

This pseudocode generates the final CSRF token in both cases:

token = Base64Encode(random_data + hmac)

Using this construction for generating CSRF tokens means that generating any valid CSRF token without knowledge of the secret is equivalent to a successful generic attack on HMAC-SHA-256.

By using an HMAC for tokens not specific to a request, it is not possible to use a valid CSRF token that is not specific to a request to generate a valid request-specific CSRF token.

By including random data in the HMAC for all tokens, different tokens are generated each time, mitigating compression ratio attacks such as BREACH.


Public Class

  1. configure


DEFAULTS = { :field => '_csrf'.freeze, :header => 'X-CSRF-Token'.freeze, :key => '_roda_csrf_secret'.freeze, :require_request_specific_tokens => true, :csrf_failure => :raise, :check_header => false, :check_request_methods => %w'POST DELETE PATCH PUT'.freeze.each(&:freeze) }.freeze  

Default CSRF option values

Public Class methods

configure (app, opts=OPTS, &block)
[show source]
# File lib/roda/plugins/route_csrf.rb, line 162
def self.configure(app, opts=OPTS, &block)
  options = app.opts[:route_csrf] = (app.opts[:route_csrf] || DEFAULTS).merge(opts)
  if block
    if opts[:csrf_failure]
      raise RodaError, "Cannot specify both route_csrf plugin block and :csrf_failure option"
    options[:csrf_failure] = block
  options[:env_header] = "HTTP_#{options[:header].to_s.gsub('-', '_').upcase}".freeze