Move all hash parameters into options argument

Author: ranisalt

benchmark/crypto/argon2.js

@@ -11,20 +11,20 @@ const {
 const bench = common.createBenchmark(main, {
   mode: ['sync', 'async'],
   algorithm: ['argon2d', 'argon2i', 'argon2id'],
-  iterations: [1, 3],
+  passes: [1, 3],
   parallelism: [2, 4, 8],
   memory: [2 ** 11, 2 ** 16, 2 ** 21],
   n: [50],
 });
 
-function measureSync(n, pass, salt, options) {
+function measureSync(n, message, nonce, options) {
   bench.start();
   for (let i = 0; i < n; ++i)
-    argon2Sync(pass, salt, 64, options);
+    argon2Sync({ ...options, message, nonce, tagLength: 64 });
   bench.end(n);
 }
 
-function measureAsync(n, pass, salt, options) {
+function measureAsync(n, message, nonce, options) {
   let remaining = n;
   function done(err) {
     assert.ifError(err);
@@ -33,15 +33,15 @@ function measureAsync(n, pass, salt, options) {
   }
   bench.start();
   for (let i = 0; i < n; ++i)
-    argon2(pass, salt, 64, options, done);
+    argon2({ ...options, message, nonce, tagLength: 64 }, done);
 }
 
 function main({ n, mode, ...options }) {
-  // Pass, salt, secret, ad & output length does not affect performance
-  const pass = randomBytes(32);
-  const salt = randomBytes(16);
+  // Message, nonce, secret, associated data & tag length do not affect performance
+  const message = randomBytes(32);
+  const nonce = randomBytes(16);
   if (mode === 'sync')
-    measureSync(n, pass, salt, options);
+    measureSync(n, message, nonce, options);
   else
-    measureAsync(n, pass, salt, options);
+    measureAsync(n, message, nonce, options);
 }

deps/ncrypto/ncrypto.cc

@@ -1861,14 +1861,14 @@ DataPointer pbkdf2(const Digest& md,
 #ifndef OPENSSL_NO_ARGON2
 DataPointer argon2(const Buffer<const char>& pass,
                    const Buffer<const unsigned char>& salt,
-                   const Buffer<const unsigned char>& secret,
-                   const Buffer<const unsigned char>& ad,
-                   Argon2Type type,
-                   uint32_t iter,
                    uint32_t lanes,
+                   size_t length,
                    uint32_t memcost,
+                   uint32_t iter,
                    uint32_t version,
-                   size_t length) {
+                   const Buffer<const unsigned char>& secret,
+                   const Buffer<const unsigned char>& ad,
+                   Argon2Type type) {
   ClearErrorOnReturn clearErrorOnReturn;
 
   std::string_view algorithm;
@@ -1917,12 +1917,12 @@ DataPointer argon2(const Buffer<const char>& pass,
       OSSL_KDF_PARAM_PASSWORD, const_cast<char*>(pass.data), pass.len));
   params.push_back(OSSL_PARAM_construct_octet_string(
       OSSL_KDF_PARAM_SALT, const_cast<unsigned char*>(salt.data), salt.len));
-  params.push_back(OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_ITER, &iter));
   params.push_back(OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_THREADS, &lanes));
   params.push_back(
       OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_ARGON2_LANES, &lanes));
   params.push_back(
       OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_ARGON2_MEMCOST, &memcost));
+  params.push_back(OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_ITER, &iter));
 
   if (ad.len != 0) {
     params.push_back(OSSL_PARAM_construct_octet_string(

deps/ncrypto/ncrypto.h

@@ -1544,14 +1544,14 @@ enum class Argon2Type { ARGON2I, ARGON2D, ARGON2ID };
 
 DataPointer argon2(const Buffer<const char>& pass,
                    const Buffer<const unsigned char>& salt,
-                   const Buffer<const unsigned char>& secret,
-                   const Buffer<const unsigned char>& ad,
-                   Argon2Type type,
-                   uint32_t iter,
                    uint32_t lanes,
+                   size_t length,
                    uint32_t memcost,
+                   uint32_t iter,
                    uint32_t version,
-                   size_t length);
+                   const Buffer<const unsigned char>& secret,
+                   const Buffer<const unsigned char>& ad,
+                   Argon2Type type);
 #endif  // !OPENSSL_NO_ARGON2
 
 // ============================================================================

doc/api/crypto.md

@@ -2949,35 +2949,34 @@ Does not perform any other validation checks on the certificate.
 
 ## `node:crypto` module methods and properties
 
-### `crypto.argon2(password, salt, keylen, options, callback)`
+### `crypto.argon2(options, callback)`
 
 <!-- YAML
 added: REPLACEME
 -->
 
 > Stability: 1.2 - Release candidate
 
-* `password` {string|ArrayBuffer|Buffer|TypedArray|DataView}
-* `salt` {string|ArrayBuffer|Buffer|TypedArray|DataView} The salt value. Must be at
-  least 8 bytes long.
-* `keylen` {number} The length of the key to generate. Must be greater than 4 and less
-  than `2**32-1`.
 * `options` {Object}
-  * `algorithm` {string} Variant of Argon2, one of `"argon2d"`, `"argon2i"` or
-    `"argon2id"`.
-  * `iterations` {number} Number of iterations (passes). Must be greater than 1 and
-    less than `2**32-1`.
+  * `message` {string|ArrayBuffer|Buffer|TypedArray|DataView}
+  * `nonce` {string|ArrayBuffer|Buffer|TypedArray|DataView} The salt value. Must be at
+    least 8 bytes long.
   * `parallelism` {number} Parallelization parameter (number of lanes and threads).
     Must be greater than 1 and less than `2**24-1`.
+  * `tagLength` {number} The length of the key to generate. Must be greater than 4 and
+    less than `2**32-1`.
   * `memory` {number} Memory cost in 1KiB blocks. Must be greater than
     `8 * parallelism` and less than `2**32-1`. The actual number of blocks is rounded
     down to the nearest multiple of `4 * parallelism`.
+  * `passes` {number} Number of passes (iterations). Must be greater than 1 and less
+    than `2**32-1`.
   * `secret` {string|ArrayBuffer|Buffer|TypedArray|DataView} Random additional input,
     similar to the salt, that should **NOT** be stored with the derived key. Also known
     as a pepper. If used, must have a length not greater than `2**32-1` bytes.
   * `associatedData` {string|ArrayBuffer|Buffer|TypedArray|DataView} Additional data to
     be added to the hash, functionally equivalent to salt or secret, but meant for
     non-random data. If used, must have a length not greater than `2**32-1` bytes.
+  * `type` {string} Variant of Argon2, one of `"argon2d"`, `"argon2i"` or `"argon2id"`.
 * `callback` {Function}
   * `err` {Error}
   * `derivedKey` {Buffer}
@@ -2986,10 +2985,10 @@ Provides an asynchronous [argon2][] implementation. Argon2 is a password-based
 key derivation function that is designed to be expensive computationally and
 memory-wise in order to make brute-force attacks unrewarding.
 
-The `salt` should be as unique as possible. It is recommended that a salt is
+The `nonce` should be as unique as possible. It is recommended that a nonce is
 random and at least 16 bytes long. See [NIST SP 800-132][] for details.
 
-When passing strings for `password`, `salt`, `secret` or `associatedData`, please
+When passing strings for `message`, `nonce`, `secret` or `associatedData`, please
 consider [caveats when using strings as inputs to cryptographic APIs][].
 
 The `callback` function is called with two arguments: `err` and `derivedKey`.
@@ -3005,8 +3004,8 @@ const {
   randomBytes,
 } = await import('node:crypto');
 
-const salt = randomBytes(16);
-argon2('password', salt, 64, { iterations: 3, parallelism: 4, memory: 65536 }, (err, derivedKey) => {
+const nonce = randomBytes(16);
+argon2({ message: 'password', nonce, parallelism: 4, tagLength: 64,  memory: 65536, passes: 3 }, (err, derivedKey) => {
   if (err) throw err;
   console.log(derivedKey.toString('hex'));  // '0de3036...22afcc5'
 });
@@ -3018,9 +3017,9 @@ const {
   randomBytes,
 } = require('node:crypto');
 
-randomBytes(16, (err, salt) => {
+randomBytes(16, (err, nonce) => {
   if (err) throw err;
-  argon2('password', salt, 64, { iterations: 3, parallelism: 4, memory: 65536 }, (err, derivedKey) => {
+  argon2({ message: 'password', nonce, parallelism: 4, tagLength: 64,  memory: 65536, passes: 3 }, (err, derivedKey) => {
     if (err) throw err;
     console.log(derivedKey.toString('hex'));  // '0de3036...22afcc5'
   });
@@ -3035,37 +3034,36 @@ added: REPLACEME
 
 > Stability: 1.2 - Release candidate
 
-* `password` {string|Buffer|TypedArray|DataView}
-* `salt` {string|ArrayBuffer|Buffer|TypedArray|DataView} The salt value. Must be at
-  least 8 bytes long.
-* `keylen` {number} The length of the key to generate. Must be greater than 4 and less
-  than `2**32-1`.
 * `options` {Object}
-  * `algorithm` {string} Variant of Argon2, one of `"argon2d"`, `"argon2i"` or
-    `"argon2id"`.
-  * `iterations` {number} Number of iterations (passes). Must be greater than 1 and
-    less than `2**32-1`.
+  * `message` {string|ArrayBuffer|Buffer|TypedArray|DataView}
+  * `nonce` {string|ArrayBuffer|Buffer|TypedArray|DataView} The salt value. Must be at
+    least 8 bytes long.
   * `parallelism` {number} Parallelization parameter (number of lanes and threads).
     Must be greater than 1 and less than `2**24-1`.
+  * `tagLength` {number} The length of the key to generate. Must be greater than 4 and
+    less than `2**32-1`.
   * `memory` {number} Memory cost in 1KiB blocks. Must be greater than
     `8 * parallelism` and less than `2**32-1`. The actual number of blocks is rounded
     down to the nearest multiple of `4 * parallelism`.
+  * `passes` {number} Number of passes (iterations). Must be greater than 1 and less
+    than `2**32-1`.
   * `secret` {string|ArrayBuffer|Buffer|TypedArray|DataView} Random additional input,
     similar to the salt, that should **NOT** be stored with the derived key. Also known
     as a pepper. If used, must have a length not greater than `2**32-1` bytes.
   * `associatedData` {string|ArrayBuffer|Buffer|TypedArray|DataView} Additional data to
     be added to the hash, functionally equivalent to salt or secret, but meant for
     non-random data. If used, must have a length not greater than `2**32-1` bytes.
+  * `type` {string} Variant of Argon2, one of `"argon2d"`, `"argon2i"` or `"argon2id"`.
 * Returns: {Buffer}
 
 Provides a synchronous [argon2][] implementation. Argon2 is a password-based
 key derivation function that is designed to be expensive computationally and
 memory-wise in order to make brute-force attacks unrewarding.
 
-The `salt` should be as unique as possible. It is recommended that a salt is
+The `nonce` should be as unique as possible. It is recommended that a nonce is
 random and at least 16 bytes long. See [NIST SP 800-132][] for details.
 
-When passing strings for `password`, `salt`, `secret` or `associatedData`, please
+When passing strings for `message`, `nonce`, `secret` or `associatedData`, please
 consider [caveats when using strings as inputs to cryptographic APIs][].
 
 An exception is thrown when key derivation fails, otherwise the derived key is
@@ -3079,10 +3077,9 @@ const {
   argon2Sync,
   randomBytes,
 } = await import('node:crypto');
-// Using the factory defaults.
 
-const salt = randomBytes(16);
-const key = argon2Sync('password', salt, 64, { iterations: 3, parallelism: 4, memory: 65536 });
+const nonce = randomBytes(16);
+const key = argon2Sync({ message: 'password', nonce, parallelism: 4, tagLength: 64,  memory: 65536, passes: 3 });
 console.log(key.toString('hex'));  // '3745e48...08d59ae'
 ```
 
@@ -3091,10 +3088,9 @@ const {
   argon2Sync,
   randomBytes,
 } = require('node:crypto');
-// Using the factory defaults.
 
-const salt = randomBytes(16);
-const key = argon2Sync('password', salt, 64, { iterations: 3, parallelism: 4, memory: 65536 });
+const nonce = randomBytes(16);
+const key = argon2Sync({ message: 'password', nonce, parallelism: 4, tagLength: 64,  memory: 65536, passes: 3 });
 console.log(key.toString('hex'));  // '3745e48...08d59ae'
 ```