npm

Ready to take your JavaScript development to the next level? Meet npm Enterprise - the ultimate in enterprise JavaScript. Learn more »

@phc/pbkdf2

1.1.14 • Public • Published

phc-pbkdf2

Mac/Linux Build Status Windows Build status Codecov Coverage report Known Vulnerabilities Dependency Status
XO Code Style used AVA Test Runner used Istanbul Test Coverage used NI Scaffolding System used NP Release System used
Latest version on npm Project license

🔒 Node.JS PBKDF2 password hashing algorithm following the PHC string format.
Coded with ❤️ by Simone Primarosa.

Synopsis

Protects against brute force, rainbow tables, and timing attacks.

Employs cryptographically secure, per password salts to prevent rainbow table attacks.
Key stretching is used to make brute force attacks impractical.
A constant time verification check prevents variable response time attacks.

PHC String Format

The PHC String Format is an attempt to specify a common hash string format that’s a restricted & well defined subset of the Modular Crypt Format. New hashes are strongly encouraged to adhere to the PHC specification, rather than the much looser Modular Crypt Format.

The hash strings generated by this package are in the following format:

$pbkdf2-<digest>$i=<iterations>$<salt>$<hash>

Where:

Field Type Description
<digest> string The HMAC digest algorithm applied to derive a key of the input password.
<iterations> number The number of iterations desired. The higher the number of iterations, the more secure the derived key will be, but will take a longer amount of time to complete.
<salt> string A sequence of bits, known as a cryptographic salt encoded in B64.
<hash> string The computed derived key by the pbkdf2 algorithm encoded in B64.

For more details consult the pbkdf2 paper here.

Install

npm install --save @phc/pbkdf2

Usage

const pbkdf2 = require('@phc/pbkdf2');
 
// Hash and verify with pbkdf2 and default configs
const hash = await pbkdf2.hash('password');
// => $pbkdf2-sha512$i=10000$O484sW7giRw+nt5WVnp15w$jEUMVZ9adB+63ko/8Dr9oB1jWdndpVVQ65xRlT+tA1GTKcJ7BWlTjdaiILzZAhIPEtgTImKvbgnu8TS/ZrjKgA
 
const match = await pbkdf2.verify(hash, 'password');
// => true
 
const match = await pbkdf2.verify(hash, 'wrong');
// => false
 
const ids = pbkdf2.identifiers();
// => ['pbkdf2-sha1', 'pbkdf2-sha256', 'pbkdf2-sha512']

Benchmarks

Below you can find usage statistics of this hashing algorithm with different options.
This should help you understand how the different options affects the running time and memory usage of the algorithm.

Usage reports are generated thanks to sympact.

System Report
Distro    Release  Platform  Arch
--------  -------  --------  ----
Mac OS X  10.12.6  darwin    x64

CPU     Brand           Clock     Cores
------  --------------  --------  -----
Intel®  Core™ i5-6360U  2.00 GHz  4    

Memory                  Type    Size         Clock   
----------------------  ------  -----------  --------
Micron Technology Inc.  LPDDR3  4294.967 MB  1867 MHz
Micron Technology Inc.  LPDDR3  4294.967 MB  1867 MHz
Default options - {iterations:25000, digest:'sha512'}
CPU Usage (avarage ± σ)  CPU Usage Range (min … max)
-----------------------  ---------------------------
0.90 % ± 0.00 %          0.90 % … 0.90 %            

RAM Usage (avarage ± σ)  RAM Usage Range (min … max)
-----------------------  ---------------------------
22.069 MB ± 0.504 MB     21.357 MB … 22.434 MB      

Execution time  Sampling time  Samples  
--------------  -------------  ---------
0.045 s         0.098 s        3 samples

Instant  CPU Usage  RAM Usage  PIDS
-------  ---------  ---------  ----
0.030 s  0.90 %     21.357 MB  5268
0.081 s  0.90 %     22.417 MB  5268
0.098 s  0.90 %     22.434 MB  5268
1˙000 iterations - {iterations:1000, digest:'sha512'}
CPU Usage (avarage ± σ)  CPU Usage Range (min … max)
-----------------------  ---------------------------
1.70 % ± 1.00 %          0.70 % … 2.70 %            

RAM Usage (avarage ± σ)  RAM Usage Range (min … max)
-----------------------  ---------------------------
23.601 MB ± 0.561 MB     23.040 MB … 24.162 MB      

Execution time  Sampling time  Samples  
--------------  -------------  ---------
0.010 s         0.06 s         2 samples

Instant  CPU Usage  RAM Usage  PIDS
-------  ---------  ---------  -----
0.028 s  0.70 %     23.040 MB  96698
0.060 s  2.70 %     24.162 MB  96698
10˙000 iterations - {iterations:10000, digest:'sha512'}
  CPU Usage (avarage ± σ)  CPU Usage Range (min … max)
  -----------------------  ---------------------------
  0.50 % ± 0.00 %          0.50 % … 0.50 %            

  RAM Usage (avarage ± σ)  RAM Usage Range (min … max)
  -----------------------  ---------------------------
  23.562 MB ± 0.543 MB     23.020 MB … 24.105 MB      

  Execution time  Sampling time  Samples  
  --------------  -------------  ---------
  0.021 s         0.069 s        2 samples

  Instant  CPU Usage  RAM Usage  PIDS
  -------  ---------  ---------  -----
  0.027 s  0.50 %     23.020 MB  96709
  0.069 s  0.50 %     24.105 MB  96709
25˙000 iterations - {iterations:25000, digest:'sha512'}
CPU Usage (avarage ± σ)  CPU Usage Range (min … max)
-----------------------  ---------------------------
0.90 % ± 0.00 %          0.90 % … 0.90 %            

RAM Usage (avarage ± σ)  RAM Usage Range (min … max)
-----------------------  ---------------------------
23.966 MB ± 0.516 MB     23.237 MB … 24.330 MB      

Execution time  Sampling time  Samples  
--------------  -------------  ---------
0.043 s         0.093 s        3 samples

Instant  CPU Usage  RAM Usage  PIDS
-------  ---------  ---------  -----
0.027 s  0.90 %     23.237 MB  96720
0.078 s  0.90 %     24.330 MB  96720
0.093 s  0.90 %     24.330 MB  96720
50˙000 iterations - {iterations:50000, digest:'sha512'}
CPU Usage (avarage ± σ)  CPU Usage Range (min … max)
-----------------------  ---------------------------
0.90 % ± 0.00 %          0.90 % … 0.90 %            

RAM Usage (avarage ± σ)  RAM Usage Range (min … max)
-----------------------  ---------------------------
24.047 MB ± 0.451 MB     23.265 MB … 24.314 MB      

Execution time  Sampling time  Samples  
--------------  -------------  ---------
0.072 s         0.126 s        4 samples

Instant  CPU Usage  RAM Usage  PIDS
-------  ---------  ---------  -----
0.027 s  0.90 %     23.265 MB  96733
0.075 s  0.90 %     24.293 MB  96733
0.108 s  0.90 %     24.314 MB  96733
0.126 s  0.90 %     24.314 MB  96733
100˙000 iterations - {iterations:100000, digest:'sha512'}
CPU Usage (avarage ± σ)  CPU Usage Range (min … max)
-----------------------  ---------------------------
15.65 % ± 17.27 %        0.70 % … 40.00 %           

RAM Usage (avarage ± σ)  RAM Usage Range (min … max)
-----------------------  ---------------------------
24.246 MB ± 0.389 MB     23.376 MB … 24.437 MB      

Execution time  Sampling time  Samples  
--------------  -------------  ---------
0.142 s         0.192 s        6 samples

Instant  CPU Usage  RAM Usage  PIDS
-------  ---------  ---------  -----
0.028 s  0.70 %     23.376 MB  96748
0.079 s  4.40 %     24.416 MB  96748
0.111 s  4.40 %     24.416 MB  96748
0.142 s  4.40 %     24.416 MB  96748
0.168 s  40.00 %    24.416 MB  96748
0.192 s  40.00 %    24.437 MB  96748
250˙000 iterations - {iterations:250000, digest:'sha512'}
CPU Usage (avarage ± σ)  CPU Usage Range (min … max)
-----------------------  ---------------------------
38.83 % ± 23.16 %        0.60 % … 68.10 %           

RAM Usage (avarage ± σ)  RAM Usage Range (min … max)
-----------------------  ---------------------------
24.286 MB ± 0.304 MB     23.192 MB … 24.388 MB      

Execution time  Sampling time  Samples   
--------------  -------------  ----------
0.368 s         0.42 s         14 samples

Instant  CPU Usage  RAM Usage  PIDS
-------  ---------  ---------  -----
0.028 s  0.60 %     23.192 MB  96767
0.075 s  0.60 %     24.367 MB  96767
0.105 s  20.90 %    24.367 MB  96767
0.136 s  20.90 %    24.367 MB  96767
0.166 s  20.90 %    24.367 MB  96767
0.197 s  20.90 %    24.367 MB  96767
0.229 s  50.90 %    24.367 MB  96767
0.262 s  50.90 %    24.367 MB  96767
0.289 s  50.90 %    24.367 MB  96767
0.319 s  50.90 %    24.367 MB  96767
0.346 s  50.90 %    24.367 MB  96767
0.378 s  68.10 %    24.367 MB  96767
0.404 s  68.10 %    24.388 MB  96767
0.420 s  68.10 %    24.388 MB  96767
500˙000 iterations - {iterations:500000, digest:'sha512'}
CPU Usage (avarage ± σ)  CPU Usage Range (min … max)
-----------------------  ---------------------------
61.37 % ± 28.77 %        0.70 % … 91.30 %           

RAM Usage (avarage ± σ)  RAM Usage Range (min … max)
-----------------------  ---------------------------
24.189 MB ± 0.225 MB     23.044 MB … 24.252 MB      

Execution time  Sampling time  Samples   
--------------  -------------  ----------
0.748 s         0.798 s        27 samples

Instant  CPU Usage  RAM Usage  PIDS
-------  ---------  ---------  -----
0.027 s  0.70 %     23.044 MB  96802
0.077 s  13.60 %    24.232 MB  96802
0.107 s  13.60 %    24.232 MB  96802
0.139 s  13.60 %    24.232 MB  96802
0.169 s  13.60 %    24.232 MB  96802
0.198 s  45.10 %    24.232 MB  96802
0.229 s  45.10 %    24.232 MB  96802
0.262 s  45.10 %    24.232 MB  96802
0.289 s  45.10 %    24.232 MB  96802
0.313 s  45.10 %    24.232 MB  96802
0.343 s  65.20 %    24.232 MB  96802
0.373 s  65.20 %    24.232 MB  96802
0.404 s  65.20 %    24.232 MB  96802
0.431 s  65.20 %    24.232 MB  96802
0.462 s  78.20 %    24.232 MB  96802
0.491 s  78.20 %    24.232 MB  96802
0.518 s  78.20 %    24.232 MB  96802
0.547 s  78.20 %    24.232 MB  96802
0.578 s  86.60 %    24.232 MB  96802
0.609 s  86.60 %    24.232 MB  96802
0.639 s  86.60 %    24.232 MB  96802
0.668 s  86.60 %    24.232 MB  96802
0.701 s  91.30 %    24.232 MB  96802
0.727 s  91.30 %    24.232 MB  96802
0.756 s  91.30 %    24.232 MB  96802
0.787 s  91.30 %    24.252 MB  96802
0.798 s  91.30 %    24.252 MB  96802

Test vectors

The pbkdf2 paper lists five test vectors to test implementation.
This package implements them here.

API

TOC

hash(password, [options])Promise.<string>

Computes the hash string of the given password in the PHC format using Node's built-in crypto.randomBytes() and crypto.pbkdf2().

verify(phcstr, password)Promise.<boolean>

Determines whether or not the hash stored inside the PHC formatted string matches the hash generated for the password provided.

identifiers()Array.<string>

Gets the list of all identifiers supported by this hashing function.

hash(password, [options]) ⇒ Promise.<string>

Computes the hash string of the given password in the PHC format using Node's built-in crypto.randomBytes() and crypto.pbkdf2().

Kind: global function
Returns: Promise.<string> - The generated secure hash string in the PHC format.
Access: public

Param Type Default Description
password string The password to hash.
[options] Object Optional configurations related to the hashing function.
[options.iterations] number 25000 Optional number of iterations to use. Must be an integer within the range (1 <= iterations <= 2^32-1).
[options.saltSize] number 16 Optional number of bytes to use when autogenerating new salts. Must be an integer within the range (1 <= saltSize <= 2^10-1).
[options.digest] string "sha512" Optinal name of digest to use when applying the key derivation function. Can be one of ['sha1', 'sha256', 'sha512'].

verify(phcstr, password) ⇒ Promise.<boolean>

Determines whether or not the hash stored inside the PHC formatted string matches the hash generated for the password provided.

Kind: global function
Returns: Promise.<boolean> - A boolean that is true if the hash computed for the password matches.
Access: public

Param Type Description
phcstr string Secure hash string generated from this package.
password string User's password input.

identifiers() ⇒ Array.<string>

Gets the list of all identifiers supported by this hashing function.

Kind: global function
Returns: Array.<string> - A list of identifiers supported by this hashing function.
Access: public

Related

  • @phc/argon2 - 🔒 Node.JS Argon2 password hashing algorithm following the PHC string format.
  • @phc/scrypt - 🔒 Node.JS scrypt password hashing algorithm following the PHC string format.
  • @phc/bcrypt - 🔒 Node.JS bcrypt password hashing algorithm following the PHC string format.

Contributing

Contributions are REALLY welcome and if you find a security flaw in this code, PLEASE report it.

Authors

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the license file for details.

install

npm i @phc/pbkdf2

Downloadsweekly downloads

665

version

1.1.14

license

MIT

homepage

github.com

repository

Gitgithub

last publish

collaborators

  • avatar
Report a vulnerability