juanelas / scrypt-pbkdf

A faster JS implementation of the scrypt password-based key derivation function

scrypt-pbkdf

A faster JS implementation of the scrypt password-based key derivation function defined in RFC 7914. It works with Node.js, and modern browsers' JS, including React and Angular.

The code has been optimized using modern Javascript ArrayBuffers and views, and by using all the available native implementations in both Node.js and browsers.

scrypt-pbkdf runs slower in Firefox than it could run because scrypt internally uses pbkdf2, but the native Firefox implementation has an issue that prevents using it under some circumstances. Therefore, a custom but slower fallback pbkdf2 function has been created.

Why another scrypt package?

scrypt-pbkdf is 2 to 3 times faster in browsers than other state-of-the-art proposals (namely scrypt-js and scryptsy), and this means that it is 2 to 3 times more secure.

Let me explain such a populist and utterly simplified answer. The more secure scrypt is, the more time it needs to complete. Frontend developers know that usability comes first and time is crucial. Therefore, it is likely that they can't allow scrypt to last for more than a few seconds (at most)

Scrypt obviously can be tuned to accomplish such a goal. Quoting the RFC:

Users of scrypt can tune the parameters N, r, and p according to the amount of memory and computing power available, the latency-bandwidth product of the memory subsystem, and the amount of parallelism desired. At the current time, r=8 and p=1 appears to yield good results, but as memory latency and CPU parallelism increase, it is likely that the optimum values for both r and p will increase.

Parameter recommendations rely on the idea of using fixed r=8and p=1 and get the biggest N (the one and only work factor) that will make scrypt run in less than the desired time. Since memory and CPU usage scale linearly with N, so does time and security. Consequently (and oversimplifying), being 2 to 3 times faster is being 2 to 3 times more secure.

The following table summarizes benchmarks obtained with Benchmark.js for fixed values r=8, p=1 and varying N values. The benchmarks were run with Chrome 83 Linux 64 bits in an Intel Core i5-6200U with 8 GB of RAM. The comparison is similar in Firefox (although twice slower).

N	scrypt-pbkdf	scrypt-js	scryptsy
2**12=4096	85ms ±10.66%	438ms ±4.52%	190ms ±5.89%
2**13=8192	165ms ±4.47%	896ms ±2.10%	379ms ±1.35%
2**14=16384	336ms ±2.65%	1748ms ±2.29%	759ms ±1.47%
2**15=32768	648ms ±1.93%	3565ms ±2.04%	1516ms ±1.88%
2**16=65536	1297ms ±0.29%	7041ms ±2.43%	2988ms ±0.20%
2**17=131072	2641ms ±0.36%	14318ms ±0.67%	6014ms ±1.70%
2**18=262144	5403ms ±2.31%	28477ms ±1.22%	11917ms ±0.31%
2**19=524288	10949ms ±0.32%	57097ms ±0.79%	23974ms ±1.56%
2**20=1048576	22882ms ±0.45%	114637ms ±0.98%	47470ms ±0.15%

You can easily create your own benchmark by cloning this repo, running npm install, then npm run build and finally open benchmark/browser/index.html with your browser.

Benchmarks for Node.js are way better than the ones obtained with browsers, probably because the different packages make use of native implementations. In the case of scrypt-pbkdf the performance is the same as the native Node.js crypto.scrypt(), since it is just a thin wrapper of it. The following table summarizes the benchmarks with Node 12 LTS in the same computer.

N	scrypt-pbkdf	scrypt-js	scryptsy
2**12=4096	12ms ±6.45%	49ms ±8.74%	106ms ±2.88%
2**13=8192	23ms ±1.80%	96ms ±4.50%	212ms ±1.32%
2**14=16384	47ms ±2.82%	192ms ±2.67%	423ms ±1.86%
2**15=32768	94ms ±0.66%	387ms ±1.89%	849ms ±0.66%
2**16=65536	210ms ±0.77%	792ms ±0.96%	1699ms ±0.49%
2**17=131072	422ms ±1.81%	1561ms ±0.49%	3429ms ±0.54%
2**18=262144	847ms ±0.81%	3128ms ±0.97%	6826ms ±0.55%
2**19=524288	1704ms ±0.70%	6310ms ±0.37%	13754ms ±1.80%
2**20=1048576	3487ms ±3.42%	12516ms ±0.28%	27446ms ±1.34%
2**21=2097152	7031ms ±1.06%	- (N too large)	- (N too large)

Usage

scrypt-pbkdf can be imported to your project with npm:

npm install scrypt-pbkdf

Then either require (Node.js CJS):

const scryptPbkdf = require('scrypt-pbkdf')

or import (JavaScript ES module):

import * as scryptPbkdf from 'scrypt-pbkdf'

The appropriate version for browser or node should be automatically chosen when importing. However, if your bundler does not import the appropriate module version (node esm, node cjs or browser esm), you can force it to use a specific one by just importing one of the followings:

• scrypt-pbkdf/dist/cjs/index.node: for Node.js CJS module
• scrypt-pbkdf/dist/esm/index.node: for Node.js ESM module
• scrypt-pbkdf/dist/esm/index.browser: for browser ESM module

If you are coding TypeScript, types will not be automatically detected when using the specific versions. You can easily get the types in by creating adding to a types declaration file (.d.ts) the following line:

declare module 'scrypt-pbkdf/dist/esm/index.browser' // use the specific file you were importing

You can also download the IIFE bundle, the ESM bundle or the UMD bundle and manually add it to your project, or, if you have already installed scrypt-pbkdf in your project, just get the bundles from node_modules/scrypt-pbkdf/dist/bundles/.

If you feel comfortable with my choice for scrypt default parameters (N=131072, r=8, p=1), you can easily derive a key (or 'digest') of 256 bits (32 bytes) from a password and a random salt as:

const password = 'mySuperSecurePassword'
const salt = scryptPbkdf.salt()  // returns an ArrayBuffer filled with 16 random bytes
const derivedKeyLength = 32  // in bytes
const key = await scryptPbkdf.scrypt(password, salt, derivedKeyLength)  // key is an ArrayBuffer

or using promises as:

const password = 'mySuperSecurePassword'
const salt = scryptPbkdf.salt()  // returns an ArrayBuffer filled with 16 random bytes
const derivedKeyLength = 32  // in bytes
scryptPbkdf.scrypt(password, salt, derivedKeyLength).then(
  function(key) { // key is an ArrayBuffer
    /* do what you want with the key */
  }, 
  function(error) { /* handle an error */ }
) 

I have chosen a value of N=131072 since, based on my own benchmarks, most browsers will likely compute it in no more than 5 seconds. However, it is likely that you want to tune the scrypt parameters.

An example of usage (from an async function) using scrypt parameters (N=16384, r=8, p=2) and a random salt of 32 bytes to derive a key of 256 bits (32 bytes) from password mySuperSecurePassword:

const password = 'mySuperSecurePassword'
const salt = scryptPbkdf.salt(32)
const scryptParams = {
  N: 16384,
  r: 8,
  p: 2
}
const derivedKeyLength = 32
const key = await scryptPbkdf.scrypt(password, salt, derivedKeyLength, scryptParams)

API reference documentation

Check the API

scrypt-pbkdf's Issues

Library is actually slower than `scrypt-js` with `setImmediate` polyfill

It appears the library is actually around 25% slower than scrypt-js when the polifill for setImmediate is provided (otherwise it fallbacks to setTimeout which is slower due to being run in the tasks queue not micro tasks queue).

Input: {"P":"pleaseletmein","S":"SodiumChloride","N":65536,"r":8,"p":1,"dkLen":64}
  scrypt-pbkdf — mean time: 626ms ±1.84% (9 runs sampled)
  scrypt-js — mean time: 485ms ±3.34% (9 runs sampled)
  scryptsy — mean time: 23649ms ±267.28% (8 runs sampled)

Input: {"P":"pleaseletmein","S":"SodiumChloride","N":131072,"r":8,"p":1,"dkLen":64}
  scrypt-pbkdf — mean time: 1292ms ±4.10% (7 runs sampled)
  scrypt-js — mean time: 946ms ±2.58% (9 runs sampled)
  scryptsy — mean time: 10943ms ±186.85% (6 runs sampled)

Input: {"P":"pleaseletmein","S":"SodiumChloride","N":262144,"r":8,"p":1,"dkLen":64}
  scrypt-pbkdf — mean time: 2529ms ±1.60% (6 runs sampled)
  scrypt-js — mean time: 1888ms ±1.64% (7 runs sampled)
  scryptsy — mean time: 5179ms ±0.14% (5 runs sampled)

Faster chromium version

Hi! this gist (another implementationt of scrypt also based on Web Crypto) seems to be REALLY noticeably faster when running in chromium derived versions (tried on Google Chrome and Iron Browser).

Also tried in Firefox but it doesn't work due to this bug (yet more info here) . Happily it can be easily fixed using this lib also by juanelas. Once applied the fix, the speed is much similar to scrypt-pbkdf but still slighty faster.

Haven't tried with other browsers and I do not know whether the implementation is correct or not. I am not the developer of the gist and frankly the math behind cryptographic algorithms I don't think is my thing so I can't say.
But I think it's worth it to @juanelas to take a look.

Hope it helps! (And thanks for your work!)

Basic question

Hi,
I was looking for a replacement of https://docs.ethers.io/v5/concepts/security/#security--pbkdf . Because it is too slow for react-native. My knowledge on cryptography is limited. So in your examples I can see how to encrypt. But do you have an example on how to de-crypt and get the original values.

Regards,
Mariano

Feature requests

Similar to scrypt js, progress callback support and non-blocking behavior, perhaps via webworker.