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 versions shipped with Rack before Rack 3 use signed sessions, not encrypted sessions, so if the attacker has the ability to read cookie data and you are using one of those Rack::Session::Cookie versions, it will still be possible for an attacker to generate valid CSRF tokens specific to arbitrary request method and request path. Roda’s session plugin uses encrypted sessions and therefore is safe even if the attacker can read cookie data.
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’) | ||||||||
| :formaction_field |
Form input parameter name for path-specific CSRF tokens (used by the | ||||||||
| :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:
| ||||||||
| :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: | ||||||||
| :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 |
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:
| check_csrf!(opts={}) |
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 |
| csrf_formaction_tag(path, method=‘POST’) |
An HTML hidden input tag string containing the CSRF token, suitable for placing in an HTML form that has inputs that use formaction attributes to change the endpoint to which the form is submitted. Takes the same arguments as csrf_token. |
| csrf_field |
The field name to use for the hidden tag containing the CSRF token. |
| csrf_path(action) |
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 (using appropriate URL encoding). |
| 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. |
| use_request_specific_csrf_tokens? |
Whether the plugin is configured to only support request-specific tokens, true by default. |
| valid_csrf?(opts={}) |
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:
| csrf_header |
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. |
| csrf_metatag |
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.
Classes and Modules
Constants
| DEFAULTS | = | { :field => '_csrf'.freeze, :formaction_field => '_csrfs'.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
# File lib/roda/plugins/route_csrf.rb 179 def self.configure(app, opts=OPTS, &block) 180 options = app.opts[:route_csrf] = (app.opts[:route_csrf] || DEFAULTS).merge(opts) 181 if block || opts[:csrf_failure].is_a?(Proc) 182 if block && opts[:csrf_failure] 183 raise RodaError, "Cannot specify both route_csrf plugin block and :csrf_failure option" 184 end 185 block ||= opts[:csrf_failure] 186 options[:csrf_failure] = :csrf_failure_method 187 app.define_roda_method(:_roda_route_csrf_failure, 1, &app.send(:convert_route_block, block)) 188 end 189 options[:env_header] = "HTTP_#{options[:header].to_s.gsub('-', '_').upcase}".freeze 190 options.freeze 191 end
# File lib/roda/plugins/route_csrf.rb 175 def self.load_dependencies(app, opts=OPTS, &_) 176 app.plugin :_base64 177 end