Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/simonepri/phc-argon2
🔒 Node.JS Argon2 password hashing algorithm following the PHC string format.
https://github.com/simonepri/phc-argon2
api argon2 hashing nodejs password secure unified universal upash
Last synced: 14 days ago
JSON representation
🔒 Node.JS Argon2 password hashing algorithm following the PHC string format.
- Host: GitHub
- URL: https://github.com/simonepri/phc-argon2
- Owner: simonepri
- License: mit
- Created: 2017-08-04T21:46:03.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2022-11-10T05:38:49.000Z (about 2 years ago)
- Last Synced: 2024-10-22T16:11:13.529Z (24 days ago)
- Topics: api, argon2, hashing, nodejs, password, secure, unified, universal, upash
- Language: JavaScript
- Homepage:
- Size: 52.7 KB
- Stars: 17
- Watchers: 3
- Forks: 6
- Open Issues: 12
-
Metadata Files:
- Readme: readme.md
- License: license
Awesome Lists containing this project
README
phc-argon2
🔒 Node.JS Argon2 password hashing algorithm following the PHC string format.
Coded with ❤️ by Simone Primarosa.
## PHC String Format
The [PHC String Format][specs:phc] 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][specs:mcf].
The hash strings generated by this package are in the following format:
```c
$argon2$v=$m=,t=,p=$$
```
Where:
| Field | Type | Description
| --- | --- | --- |
| `` | string | The [variant][specs:a2var] of the algorithm used to derive a key of the input password. |
| `` | number | The version of the argon2 algorithm used. |
| `` | number | The amount of memory to consume in kibibytes. |
| `` | 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. |
| `` | number | The degree of parallelism to use while computing the hash. |
| `` | string | A sequence of bits, known as a [cryptographic salt][specs:salt] encoded in [B64][specs:B64]. |
| `` | string | The computed derived key by the [argon2][specs:Argon2] algorithm encoded in [B64][specs:B64]. |
For more details consult the Argon2 paper [here][paper].
## Install
```bash
npm install --save @phc/argon2
```
## Usage
```js
const argon2 = require('@phc/argon2');
// Hash and verify with argon2 and default configs
const hash = await argon2.hash('password');
// => $argon2id$v=19$m=4096,t=3,p=1$PcEZHj1maR/+ZQynyJHWZg$2jEN4xcww7CYp1jakZB1rxbYsZ55XH2HgjYRtdZtubI
const match = await argon2.verify(hash, 'password');
// => true
const match = await argon2.verify(hash, 'wrong');
// => false
const ids = argon2.identifiers();
// => ['argon2d', 'argon2i', 'argon2id']
```
## 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][gh: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:3, memory:4096, parallelism:1, variant:'id'} ↴
```
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.927 MB ± 2.775 MB 21.152 MB … 26.702 MB
Execution time Sampling time Samples
-------------- ------------- ---------
0.020 s 0.069 s 2 samples
Instant CPU Usage RAM Usage PIDS
------- --------- --------- ----
0.028 s 0.50 % 21.152 MB 4934
0.069 s 0.50 % 26.702 MB 4934
```
5 iterations - {iterations:5, memory:4096, parallelism:1, variant:'id'} ↴
```
CPU Usage (avarage ± σ) CPU Usage Range (min … max)
----------------------- ---------------------------
0.60 % ± 0.00 % 0.60 % … 0.60 %
RAM Usage (avarage ± σ) RAM Usage Range (min … max)
----------------------- ---------------------------
24.906 MB ± 2.591 MB 21.242 MB … 26.739 MB
Execution time Sampling time Samples
-------------- ------------- ---------
0.025 s 0.077 s 3 samples
Instant CPU Usage RAM Usage PIDS
------- --------- --------- ----
0.025 s 0.60 % 21.242 MB 4945
0.076 s 0.60 % 26.739 MB 4945
0.077 s 0.60 % 26.739 MB 4945
```
10 iterations - {iterations:10, memory:4096, parallelism:1, variant:'id'} ↴
```
CPU Usage (avarage ± σ) CPU Usage Range (min … max)
----------------------- ---------------------------
0.40 % ± 0.00 % 0.40 % … 0.40 %
RAM Usage (avarage ± σ) RAM Usage Range (min … max)
----------------------- ---------------------------
24.999 MB ± 2.576 MB 21.357 MB … 26.821 MB
Execution time Sampling time Samples
-------------- ------------- ---------
0.054 s 0.112 s 3 samples
Instant CPU Usage RAM Usage PIDS
------- --------- --------- ----
0.033 s 0.40 % 21.357 MB 4958
0.094 s 0.40 % 26.821 MB 4958
0.112 s 0.40 % 26.821 MB 4958
```
25 iterations - {iterations:25, memory:4096, parallelism:1, variant:'id'} ↴
```
CPU Usage (avarage ± σ) CPU Usage Range (min … max)
----------------------- ---------------------------
6.78 % ± 10.70 % 0.60 % … 25.30 %
RAM Usage (avarage ± σ) RAM Usage Range (min … max)
----------------------- ---------------------------
25.440 MB ± 2.365 MB 21.344 MB … 26.817 MB
Execution time Sampling time Samples
-------------- ------------- ---------
0.082 s 0.129 s 4 samples
Instant CPU Usage RAM Usage PIDS
------- --------- --------- ----
0.026 s 0.60 % 21.344 MB 4971
0.077 s 0.60 % 26.800 MB 4971
0.109 s 0.60 % 26.800 MB 4971
0.129 s 25.30 % 26.817 MB 4971
```
50 iterations - {iterations:50, memory:4096, parallelism:1, variant:'id'} ↴
```
CPU Usage (avarage ± σ) CPU Usage Range (min … max)
----------------------- ---------------------------
12.24 % ± 7.36 % 0.60 % … 16.90 %
RAM Usage (avarage ± σ) RAM Usage Range (min … max)
----------------------- ---------------------------
26.076 MB ± 1.907 MB 21.406 MB … 26.866 MB
Execution time Sampling time Samples
-------------- ------------- ---------
0.158 s 0.207 s 7 samples
Instant CPU Usage RAM Usage PIDS
------- --------- --------- ----
0.026 s 0.60 % 21.406 MB 4986
0.077 s 0.60 % 26.849 MB 4986
0.107 s 16.90 % 26.849 MB 4986
0.145 s 16.90 % 26.849 MB 4986
0.167 s 16.90 % 26.849 MB 4986
0.196 s 16.90 % 26.866 MB 4986
0.207 s 16.90 % 26.866 MB 4986
```
100 iterations - {iterations:100, memory:4096, parallelism:1, variant:'id'} ↴
```
CPU Usage (avarage ± σ) CPU Usage Range (min … max)
----------------------- ---------------------------
37.25 % ± 22.39 % 1.10 % … 59.20 %
RAM Usage (avarage ± σ) RAM Usage Range (min … max)
----------------------- ---------------------------
26.418 MB ± 1.453 MB 21.385 MB … 26.849 MB
Execution time Sampling time Samples
-------------- ------------- ----------
0.408 s 0.479 s 13 samples
Instant CPU Usage RAM Usage PIDS
------- --------- --------- ----
0.026 s 1.10 % 21.385 MB 5007
0.076 s 1.10 % 26.833 MB 5007
0.106 s 1.10 % 26.833 MB 5007
0.153 s 30.70 % 26.833 MB 5007
0.170 s 30.70 % 26.833 MB 5007
0.201 s 30.70 % 26.833 MB 5007
0.301 s 50.70 % 26.833 MB 5007
0.330 s 50.70 % 26.833 MB 5007
0.366 s 50.70 % 26.833 MB 5007
0.403 s 59.20 % 26.833 MB 5007
0.453 s 59.20 % 26.849 MB 5007
0.478 s 59.20 % 26.849 MB 5007
0.479 s 59.20 % 26.849 MB 5007
```
16˙384 KiB of memory - {iterations:3, memory:16384, parallelism:1, variant:'id'} ↴
```
CPU Usage (avarage ± σ) CPU Usage Range (min … max)
----------------------- ---------------------------
5.58 % ± 2.81 % 0.70 % … 7.20 %
RAM Usage (avarage ± σ) RAM Usage Range (min … max)
----------------------- ---------------------------
34.916 MB ± 7.812 MB 21.385 MB … 39.432 MB
Execution time Sampling time Samples
-------------- ------------- ---------
0.071 s 0.13 s 4 samples
Instant CPU Usage RAM Usage PIDS
------- --------- --------- ----
0.033 s 0.70 % 21.385 MB 5040
0.083 s 7.20 % 39.416 MB 5040
0.116 s 7.20 % 39.432 MB 5040
0.130 s 7.20 % 39.432 MB 5040
```
65˙536 KiB of memory - {iterations:3, memory:65536, parallelism:1, variant:'id'} ↴
```
CPU Usage (avarage ± σ) CPU Usage Range (min … max)
----------------------- ---------------------------
21.92 % ± 17.48 % 0.60 % … 49.30 %
RAM Usage (avarage ± σ) RAM Usage Range (min … max)
----------------------- ---------------------------
75.683 MB ± 23.350 MB 20.980 MB … 89.358 MB
Execution time Sampling time Samples
-------------- ------------- ---------
0.205 s 0.258 s 8 samples
Instant CPU Usage RAM Usage PIDS
------- --------- --------- ----
0.025 s 0.60 % 20.980 MB 5055
0.075 s 0.60 % 55.775 MB 5055
0.106 s 18.90 % 81.981 MB 5055
0.143 s 18.90 % 89.342 MB 5055
0.164 s 18.90 % 89.342 MB 5055
0.194 s 18.90 % 89.342 MB 5055
0.225 s 49.30 % 89.342 MB 5055
0.258 s 49.30 % 89.358 MB 5055
```
262˙144 KiB of memory - {iterations:3, memory:262144, parallelism:1, variant:'id'} ↴
```
CPU Usage (avarage ± σ) CPU Usage Range (min … max)
----------------------- ---------------------------
64.37 % ± 28.91 % 0.60 % … 93.90 %
RAM Usage (avarage ± σ) RAM Usage Range (min … max)
----------------------- ---------------------------
216.095 MB ± 96.874 MB 21.332 MB … 291.025 MB
Execution time Sampling time Samples
-------------- ------------- ----------
0.885 s 0.933 s 31 samples
Instant CPU Usage RAM Usage PIDS
------- --------- ---------- ----
0.026 s 0.60 % 21.332 MB 5078
0.074 s 0.60 % 51.356 MB 5078
0.106 s 19.40 % 77.545 MB 5078
0.136 s 19.40 % 99.344 MB 5078
0.167 s 19.40 % 121.168 MB 5078
0.192 s 19.40 % 140.993 MB 5078
0.225 s 47.90 % 165.065 MB 5078
0.260 s 47.90 % 188.371 MB 5078
0.286 s 47.90 % 205.804 MB 5078
0.315 s 47.90 % 229.233 MB 5078
0.343 s 66.20 % 252.084 MB 5078
0.404 s 66.20 % 288.231 MB 5078
0.422 s 66.20 % 291.025 MB 5078
0.439 s 66.20 % 291.025 MB 5078
0.468 s 77.00 % 291.025 MB 5078
0.498 s 77.00 % 291.025 MB 5078
0.528 s 77.00 % 291.025 MB 5078
0.554 s 77.00 % 291.025 MB 5078
0.586 s 77.00 % 291.025 MB 5078
0.619 s 85.10 % 291.025 MB 5078
0.649 s 85.10 % 291.025 MB 5078
0.672 s 85.10 % 291.025 MB 5078
0.703 s 85.10 % 291.025 MB 5078
0.735 s 89.80 % 291.025 MB 5078
0.765 s 89.80 % 291.025 MB 5078
0.792 s 89.80 % 291.025 MB 5078
0.823 s 89.80 % 291.025 MB 5078
0.854 s 93.90 % 291.025 MB 5078
0.896 s 93.90 % 156.807 MB 5078
0.918 s 93.90 % 22.606 MB 5078
0.933 s 93.90 % 22.606 MB 5078
```
## API
#### TOC
-
hash(password, [options]) ⇒Promise.<string> -
Computes the hash string of the given password in the PHC format using argon2
package. -
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 argon2
package.
**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.variant] | number | id | Optinal variant of argon2 to use. Can be one of [`'d'`, `'i'`, `'id'`] for argon2d, argon2i and argon2id respectively. |
| [options.iterations] | number | 3 | Optional number of iterations to use. Must be an integer within the range (`1` <= `iterations` <= `2^32-1`). |
| [options.memory] | number | 4096 | Optional amount of memory to use in kibibytes. Must be an integer within the range (`8` <= `memory` <= `2^32-1`). |
| [options.parallelism] | number | 1 | Optional degree of parallelism to use. Must be an integer within the range (`1` <= `parallelism` <= `2^24-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`). |
### 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/scrypt][scrypt] -
🔒 Node.JS scrypt password hashing algorithm following the PHC string format.
- [@phc/bcrypt][bcrypt] -
🔒 Node.JS bcrypt password hashing algorithm following the PHC string format.
- [@phc/pbkdf2][pbkdf2] -
🔒 Node.JS PBKDF2 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][new issue].
## Authors
- **Simone Primarosa** - *Github* ([@simonepri][github:simonepri]) • *Twitter* ([@simoneprimarosa][twitter:simoneprimarosa])
See also the list of [contributors][contributors] who participated in this project.
## License
This project is licensed under the MIT License - see the [license][license] file for details.
[start]: https://github.com/simonepri/phc-argon2#start-of-content
[new issue]: https://github.com/simonepri/phc-argon2/issues/new
[contributors]: https://github.com/simonepri/phc-argon2/contributors
[license]: https://github.com/simonepri/phc-argon2/tree/master/license
[tvec]: https://github.com/simonepri/phc-argon2/tree/master/test/vectors.js
[scrypt]: https://github.com/simonepri/phc-scrypt
[bcrypt]: https://github.com/simonepri/phc-bcrypt
[pbkdf2]: https://github.com/simonepri/phc-pbkdf2
[github:simonepri]: https://github.com/simonepri
[twitter:simoneprimarosa]: http://twitter.com/intent/user?screen_name=simoneprimarosa
[gh:sympact]: https://github.com/simonepri/sympact
[specs:mcf]: https://github.com/ademarre/binary-mcf
[specs:phc]: https://github.com/P-H-C/phc-string-format/blob/master/phc-sf-spec.md
[specs:B64]: https://github.com/P-H-C/phc-string-format/blob/master/phc-sf-spec.md#b64
[specs:salt]: https://en.wikipedia.org/wiki/Salt_(cryptography)
[specs:a2var]: https://crypto.stackexchange.com/a/49969
[specs:Argon2]: https://en.wikipedia.org/wiki/Argon2
[paper]: https://tools.ietf.org/html/draft-irtf-cfrg-argon2-03
[paper:test]: https://tools.ietf.org/html/draft-irtf-cfrg-argon2-03#section-6