pillarjs / csrf Goto Github PK

View Code? Open in Web Editor NEW

294.0 18.0 35.0 128 KB

Logic behind CSRF token creation and verification.

License: MIT License

JavaScript 100.00%

javascript nodejs csrf tokens

csrf's Introduction

CSRF

Logic behind CSRF token creation and verification.

Read Understanding-CSRF for more information on CSRF. Use this module to create custom CSRF middleware.

Looking for a CSRF framework for your favorite framework that uses this module?

Express/connect: csurf or alt-xsrf
Koa: koa-csrf or koa-atomic-session

Install

$ npm install csrf

TypeScript

This module includes a TypeScript declaration file to enable auto complete in compatible editors and type information for TypeScript projects.

API

var Tokens = require('csrf')

new Tokens([options])

Create a new token generation/verification instance. The options argument is optional and will just use all defaults if missing.

Options

Tokens accepts these properties in the options object.

saltLength

The length of the internal salt to use, in characters. Internally, the salt is a base 62 string. Defaults to 8 characters.

secretLength

The length of the secret to generate, in bytes. Note that the secret is passed around base-64 encoded and that this length refers to the underlying bytes, not the length of the base-64 string. Defaults to 18 bytes.

tokens.create(secret)

Create a new CSRF token attached to the given secret. The secret is a string, typically generated from the tokens.secret() or tokens.secretSync() methods. This token is what you should add into HTML <form> blocks and expect the user's browser to provide back.

var secret = tokens.secretSync()
var token = tokens.create(secret)

tokens.secret(callback)

Asynchronously create a new secret, which is a string. The secret is to be kept on the server, typically stored in a server-side session for the user. The secret should be at least per user.

tokens.secret(function (err, secret) {
  if (err) throw err
  // do something with the secret
})

tokens.secret()

Asynchronously create a new secret and return a Promise. Please see tokens.secret(callback) documentation for full details.

Note: To use promises in Node.js prior to 0.12, promises must be "polyfilled" using global.Promise = require('bluebird').

tokens.secret().then(function (secret) {
  // do something with the secret
})

tokens.secretSync()

A synchronous version of tokens.secret(callback). Please see tokens.secret(callback) documentation for full details.

var secret = tokens.secretSync()

tokens.verify(secret, token)

Check whether a CSRF token is valid for the given secret, returning a Boolean.

if (!tokens.verify(secret, token)) {
  throw new Error('invalid token!')
}

License

MIT

csrf's People

Contributors

Stargazers

Watchers

csrf's Issues

Attaching domain to token

Don't you think, one should attach a domain to token creation, which means if token is received from a different domain it will be discarded.

Example

tokens.create(secret, domain)
tokens.verify(secret, token, domain)

Here's why

First i agree, it is not this module problem to deal with sessions or cookies. But as a general approach i will do following with this module.

Create a token and set it under input field.
Save secret under session or cookie.
Check token with session using verify method.

Now the problem is, anyone can quickly grab this token by visiting a webpage on my website. Also they can copy the session from the network tab.

After this all one need to do is make CURL request by setting above values and VOILA csrf has been compromised.

Please use rand-token instead of uid2

Hi,

as reported for session middleware:
expressjs/session#49

Could you please consider to use another module instead of uid2 ?

In that issue I suggested node-uuid, but rand-token is now used. Could you please consider to make same change here?

Why do we hash the CSRF?

I was looking through the code to understand the security model and noticed that the CSRF is being hashed with SHA-1. There's a lot of talk about replacing SHA-1 with harder to break hashing function (eg. SHA-256) in other areas so it worried me at first to see SHA-1 used to protect CSRFs. But then I got to thinking about it more... why are we hashing the CSRF? AFAIK the CSRF (even in plaintext) is not enough for a malicious agent to generate the cookie that they would need to steal a session.

What threat does hashing the CSRF token secure against as opposed to storing the CSRF in plain text in both the browser javascript and the cookie? And if the hashing is important to security of CSRFs should we be migrating CSRF to SHA-256?

Remove tokenize option

If we change this to basically a class, theoretically if we just attached the tokenize function to the prototype, people could overwrite the function on instances themselves or even subclass this.

Thoughts, @jonathanong ? Are there people even using the tokenize option?

Question: refresh token and secret

If I understand correctly:

We should refresh token on every request and every page to mitigate BREACH (if we only refresh page with form, attacker can still guess content by repeatedly visit page without such protection)
Secret is per-user and if we store it on server session store, we can reuse it for a longtime, maybe a year, forever?

That's how koa-csrf appear to be using it.

I know create token is fast, only concern I have is refreshing token cause Set-Cookie every time, seem to be less than performant, any alternative available if I am to write my own csrf middleware?

RNG in CSRF module code

Hello,

We use this module in our code.
According to what we see, you use Math.random() which does not produce cryptographically safe random numbers.
Is it possible to switch to some strong RNG, like "crypto.randomBytes" for example?

Thank you and Best Regards,
Zvi

new release with all changes since 3.0.6

I am looking forward to a release, which includes 43f660a