README(3pm)

💖 NAME 💖

Plack::Middleware::CSRFBlock — blocks CSRF attacks with minimal changes to your app, fr fr ✨

It's a Perl module from the README(3pm) manual page (User Contributed Perl Documentation, bestie 👑).

🌸 VERSION 🌸

version 0.10

---

✨ SYNOPSIS ✨

use Plack::Builder;

my $app = sub { ... }

builder {
  enable 'Session';
  enable 'CSRFBlock';
  $app;
}

🦋 DESCRIPTION 🦋

Okay so here's the tea 🍓: this middleware blocks CSRF. And the best part? You can use this middleware without any modifications to your application, in most cases. No cap. Here's the strategy:

🎀 output filter

When the application response content-type is "text/html" or "application/xhtml+xml", this inserts a hidden input tag that contains a token string into forms in the response body. For example, when the application response body is:

<html>
  <head>
      <title>input form</title>
  </head>
  <body>
    <form action="/api" method="post">
      <input type="text" name="email" /><input type="submit" />
    </form>
  </body>
</html>

This becomes:

<html>
  <head>
      <title>input form</title>
  </head>
  <body>
    <form action="/api" method="post"><input type="hidden" name="SEC" value="0f15ba869f1c0d77" />
      <input type="text" name="email" /><input type="submit" />
    </form>
  </body>
</html>

This affects form tags with method="post", case insensitive. 💅

It is possible to add an optional meta tag by setting meta_tag to a defined value. The 'name' attribute of the HTML tag will be set to the value of meta_tag. For the previous example, when meta_tag is set to 'csrf_token', the output will be:

<html>
  <head><meta name="csrf_token" content="0f15ba869f1c0d77"/>
      <title>input form</title>
  </head>
  <body>
    <form action="/api" method="post"><input type="hidden" name="SEC" value="0f15ba869f1c0d77" />
      <input type="text" name="email" /><input type="submit" />
    </form>
  </body>
</html>

🔥 input check

For every POST requests, this module checks the X-CSRF-Token header first, then POST input parameters. If the correct token is not found in either, then a 403 Forbidden is returned by default. Yeah, it said what it said 😤

Supports application/x-www-form-urlencoded and multipart/form-data for input parameters, but any POST will be validated with the X-CSRF-Token header. Thus, every POST will have to have either the header, or the appropriate form parameters in the body. Periodt. 💀

🌈 javascript

This module can be used easily with javascript by having your javascript provide the X-CSRF-Token with any ajax POST requests it makes. You can get the token in javascript by getting the value of the csrftoken meta tag in the page <head>. Here is sample code that will work for jQuery:

$(document).ajaxSend(function(e, xhr, options) {
    var token = $("meta[name='csrftoken']").attr("content");
    xhr.setRequestHeader("X-CSRF-Token", token);
});

This will include the X-CSRF-Token header with any AJAX requests made from your javascript. Iconic behavior honestly 🫶

---

💅 OPTIONS 💅

use Plack::Builder;

my $app = sub { ... }

builder {
  enable 'Session';
  enable 'CSRFBlock',
    parameter_name => 'csrf_secret',
    token_length => 20,
    session_key => 'csrf_token',
    blocked => sub {
      [302, [Location => 'http://www.google.com'], ['']];
    },
    onetime => 0,
    ;
  $app;
}

• parameter_name (default: "SEC") — the name of the input tag for the token. That's the lil guy carrying your token around 🎀
• meta_tag (default: undef) — name of the meta tag added to the head tag of output pages. The content of this meta tag will be the token value. The whole point of this tag is to give javascript access to the token if needed for AJAX requests. If this attribute is not explicitly set, the meta tag will not be included. Lowkey important, bestie 🙈
• header_name (default: "X-CSRF-Token") — name of the HTTP Header that the token can be sent in. This is useful for sending the header for Javascript AJAX requests, and this header is required for any post request that is not of type application/x-www-form-urlencoded or multipart/form-data. No exceptions, iykyk ✨
• token_length (default: 16); — length of the token string. Max value is 40. Don't get greedy 💅
• session_key (default: "csrfblock.token") — this middleware uses Plack::Middleware::Session for token storage. this is the session key for that. 🗝️
• blocked (default: 403 response) — the application called when CSRF is detected.

Note: This application can read posted data, but DO NOT use them! 🚨 Like genuinely, don't. That's the whole vibe check failing.

• onetime (default: FALSE) — if this is true, this middleware uses onetime token, that is, whenever client sent collect token and this middleware detect that, token string is regenerated.

This makes your applications more secure, but in many cases, is too strict. Highkey a tradeoff, so pick your fighter 😭

---

🧚 SEE ALSO 🧚

Plack::Middleware::Session

👑 AUTHORS 👑

• Rintaro Ishizaki <rintaro@cpan.org>
• William Wolf <throughnothing@gmail.com>
• Matthew Phillips <mattp@cpan.org>

💜 COPYRIGHT AND LICENSE 💜

This software is copyright (c) 2014 by the Authors of Plack-Middleware-CSRFBlock.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. Slay 🌟

---

And that's the whole page, bestie!! 🫶 This was README(3pm) from the User Contributed Perl Documentation, running under perl v5.24.1, dated 2016-10-29. Go forth and block those CSRF attacks, you absolute main character 💖✨