Nested Public Modules

    @phc/argon2

    1.0.9 • Public • Published

    phc-argon2

    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 Argon2 password hashing algorithm following the PHC string format.
    Coded with ❤️ by Simone Primarosa.

    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:

    $argon2<variant>$v=<version>$m=<memory>,t=<iterations>,p=<parallelism>$<salt>$<hash>

    Where:

    Field Type Description
    <variant> string The variant of the algorithm used to derive a key of the input password.
    <version> number The version of the argon2 algorithm used.
    <memory> number The amount of memory to consume in kibibytes.
    <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.
    <parallelism> number The degree of parallelism to use while computing the hash.
    <salt> string A sequence of bits, known as a cryptographic salt encoded in B64.
    <hash> string The computed derived key by the argon2 algorithm encoded in B64.

    For more details consult the Argon2 paper here.

    Install

    npm install --save @phc/argon2

    Usage

    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.

    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 - 🔒 Node.JS scrypt password hashing algorithm following the PHC string format.
    • @phc/bcrypt - 🔒 Node.JS bcrypt password hashing algorithm following the PHC string format.
    • @phc/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.

    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/argon2

    DownloadsWeekly Downloads

    1,198

    Version

    1.0.9

    License

    MIT

    Unpacked Size

    31.6 kB

    Total Files

    4

    Last publish

    Collaborators

    • simonepri