class Rack::Protection::AuthenticityToken

Prevented attack

CSRF

Supported browsers

all

More infos

en.wikipedia.org/wiki/Cross-site_request_forgery

This middleware only accepts requests other than GET, HEAD, OPTIONS, TRACE if their given access token matches the token included in the session.

It checks the X-CSRF-Token header and the POST form data.

Compatible with the rack-csrf gem.

Options

:authenticity_param

the name of the param that should contain the token on a request. Default value: "authenticity_token"

Example: Forms application

To show what the AuthenticityToken does, this section includes a sample program which shows two forms. One with, and one without a CSRF token The one without CSRF token field will get a 403 Forbidden response.

Install the gem, then run the program:

gem install 'rack-protection'
ruby server.rb

Here is server.rb:

require 'rack/protection'

app = Rack::Builder.app do
  use Rack::Session::Cookie, secret: 'secret'
  use Rack::Protection::AuthenticityToken

  run -> (env) do
    [200, {}, [
      <<~EOS
        <!DOCTYPE html>
        <html lang="en">
        <head>
          <meta charset="UTF-8" />
          <title>rack-protection minimal example</title>
        </head>
        <body>
          <h1>Without Authenticity Token</h1>
          <p>This takes you to <tt>Forbidden</tt></p>
          <form action="" method="post">
            <input type="text" name="foo" />
            <input type="submit" />
          </form>

          <h1>With Authenticity Token</h1>
          <p>This successfully takes you to back to this form.</p>
          <form action="" method="post">
            <input type="hidden" name="authenticity_token" value="#{env['rack.session'][:csrf]}" />
            <input type="text" name="foo" />
            <input type="submit" />
          </form>
        </body>
        </html>
      EOS
    ]]
  end
end

Rack::Handler::WEBrick.run app

Example: Customize which POST parameter holds the token

To customize the authenticity parameter for form data, use the :authenticity_param option:

use Rack::Protection::AuthenticityToken, authenticity_param: 'your_token_param_name'

Constants

TOKEN_LENGTH

Public Class Methods

random_token() click to toggle source
# File lib/rack/protection/authenticity_token.rb, line 94
def self.random_token
  SecureRandom.base64(TOKEN_LENGTH)
end
token(session) click to toggle source
# File lib/rack/protection/authenticity_token.rb, line 90
def self.token(session)
  self.new(nil).mask_authenticity_token(session)
end

Public Instance Methods

accepts?(env) click to toggle source
# File lib/rack/protection/authenticity_token.rb, line 98
def accepts?(env)
  session = session env
  set_token(session)

  safe?(env) ||
    valid_token?(session, env['HTTP_X_CSRF_TOKEN']) ||
    valid_token?(session, Request.new(env).params[options[:authenticity_param]]) ||
    ( options[:allow_if] && options[:allow_if].call(env) )
end
mask_authenticity_token(session) click to toggle source
# File lib/rack/protection/authenticity_token.rb, line 108
def mask_authenticity_token(session)
  token = set_token(session)
  mask_token(token)
end

Private Instance Methods

compare_with_real_token(token, session) click to toggle source
# File lib/rack/protection/authenticity_token.rb, line 175
def compare_with_real_token(token, session)
  secure_compare(token, real_token(session))
end
decode_token(token) click to toggle source
# File lib/rack/protection/authenticity_token.rb, line 187
def decode_token(token)
  Base64.strict_decode64(token)
end
encode_token(token) click to toggle source
# File lib/rack/protection/authenticity_token.rb, line 183
def encode_token(token)
  Base64.strict_encode64(token)
end
mask_token(token) click to toggle source

Creates a masked version of the authenticity token that varies on each request. The masking is used to mitigate SSL attacks like BREACH.

# File lib/rack/protection/authenticity_token.rb, line 149
def mask_token(token)
  token = decode_token(token)
  one_time_pad = SecureRandom.random_bytes(token.length)
  encrypted_token = xor_byte_strings(one_time_pad, token)
  masked_token = one_time_pad + encrypted_token
  encode_token(masked_token)
end
masked_token?(token) click to toggle source
# File lib/rack/protection/authenticity_token.rb, line 171
def masked_token?(token)
  token.length == TOKEN_LENGTH * 2
end
real_token(session) click to toggle source
# File lib/rack/protection/authenticity_token.rb, line 179
def real_token(session)
  decode_token(session[:csrf])
end
set_token(session) click to toggle source
# File lib/rack/protection/authenticity_token.rb, line 115
def set_token(session)
  session[:csrf] ||= self.class.random_token
end
unmask_token(masked_token) click to toggle source

Essentially the inverse of mask_token.

# File lib/rack/protection/authenticity_token.rb, line 158
def unmask_token(masked_token)
  # Split the token into the one-time pad and the encrypted
  # value and decrypt it
  token_length = masked_token.length / 2
  one_time_pad = masked_token[0...token_length]
  encrypted_token = masked_token[token_length..-1]
  xor_byte_strings(one_time_pad, encrypted_token)
end
unmasked_token?(token) click to toggle source
# File lib/rack/protection/authenticity_token.rb, line 167
def unmasked_token?(token)
  token.length == TOKEN_LENGTH
end
valid_token?(session, token) click to toggle source

Checks the client's masked token to see if it matches the session token.

# File lib/rack/protection/authenticity_token.rb, line 121
def valid_token?(session, token)
  return false if token.nil? || token.empty?

  begin
    token = decode_token(token)
  rescue ArgumentError # encoded_masked_token is invalid Base64
    return false
  end

  # See if it's actually a masked token or not. We should be able
  # to handle any unmasked tokens that we've issued without error.

  if unmasked_token?(token)
    compare_with_real_token token, session

  elsif masked_token?(token)
    token = unmask_token(token)

    compare_with_real_token token, session

  else
    false # Token is malformed
  end
end
xor_byte_strings(s1, s2) click to toggle source
# File lib/rack/protection/authenticity_token.rb, line 191
def xor_byte_strings(s1, s2)
  s1.bytes.zip(s2.bytes).map { |(c1,c2)| c1 ^ c2 }.pack('c*')
end