argon2id - npm Package Compare versions

Comparing version 0.0.1-3 to 1.0.0

index.js

@@ -5,13 +5,7 @@ import setupWasm from './lib/setup.js';
 
-/**
- * Setup an `argon2id` instance, by loading the Wasm module that is used under the hood. The SIMD version is used as long as the platform supports it.
- * The loaded module is then cached across `argon2id` calls.
- * NB: the used Wasm memory is cleared across runs, but not de-allocated.
- * Re-loading is thus recommended in order to free the memory if multiple `argon2id` hashes are computed
- * and some of them require considerably more memory than the rest.
- * @returns argon2id function
- */
-export default async () => setupWasm(
+const loadWasm = async () => setupWasm(
   (instanceObject) => wasmSIMD(instanceObject),
   (instanceObject) => wasmNonSIMD(instanceObject),
 );
+
+export default loadWasm;

lib/argon2id.js

@@ -1,8 +0,3 @@
-// TODOs (possible perf gains):
-// - compute entire segment in wasm
-// - add parallelism
-
 import blake2b from "./blake2b.js"
-const SECRETBYTES_MAX = 32; // key (optional)
-const ADBYTES_MAX = 0xFFFFFFFF; // Math.pow(2, 32) - 1; // associated data (optional)
+const TYPE = 2;  // Argon2id
 const VERSION = 0x13;
@@ -13,9 +8,10 @@ const TAGBYTES_MAX = 0xFFFFFFFF; // Math.pow(2, 32) - 1;
 const SALTBYTES_MIN = 8;
-const PWDBYTES_MAX = 0xFFFFFFFF;// Math.pow(2, 32) - 1;
-const TYPE = 2;  // Argon2id 
+const passwordBYTES_MAX = 0xFFFFFFFF;// Math.pow(2, 32) - 1;
+const passwordBYTES_MIN = 8;
+const MEMBYTES_MAX = 0xFFFFFFFF;// Math.pow(2, 32) - 1;
+const ADBYTES_MAX = 0xFFFFFFFF; // Math.pow(2, 32) - 1; // associated data (optional)
+const SECRETBYTES_MAX = 32; // key (optional)
 
-// const SYNC_POINTS = 4 // Number of synchronization points between lanes per pass
 const ARGON2_BLOCK_SIZE = 1024;
 const ARGON2_PREHASH_DIGEST_LENGTH = 64;
-const ARGON2_PREHASH_SEED_LENGTH = 72;
 
@@ -161,9 +157,26 @@ const isLittleEndian = new Uint8Array(new Uint16Array([0xabcd]).buffer)[0] === 0xcd;
 
+function validateParams({ type, version, tagLength, password, salt, ad, secret, parallelism, memorySize, passes }) {
+  const assertLength = (name, value, min, max) => {
+    if (value < min || value > max) { throw new Error(`${name} size should be between ${min} and ${max} bytes`); }
+  }
+
+  if (type !== TYPE || version !== VERSION) throw new Error('Unsupported type or version');
+  assertLength('password', password, passwordBYTES_MIN, passwordBYTES_MAX);
+  assertLength('salt', salt, SALTBYTES_MIN, SALTBYTES_MAX);
+  assertLength('tag', tagLength, TAGBYTES_MIN, TAGBYTES_MAX);
+  assertLength('memory', memorySize, 8*parallelism, MEMBYTES_MAX);
+  // optional fields
+  ad && assertLength('associated data', ad, 0, ADBYTES_MAX);
+  secret && assertLength('secret', secret, 0, SECRETBYTES_MAX);
+
+  return { type, version, tagLength, password, salt, ad, secret, lanes: parallelism, memorySize, passes };
+}
+
 const KB = 1024;
 const WASM_PAGE_SIZE = 64 * KB;
 
-export default function argon2id(settings, { memory, instance: wasmInstance }) {
+export default function argon2id(params, { memory, instance: wasmInstance }) {
   if (!isLittleEndian) throw new Error('BigEndian system not supported'); // optmisations assume LE system
 
-  const ctx = { outlen: 32, ...settings, type: TYPE, version: VERSION }; // TODO validate (in calling fn)
+  const ctx = validateParams({ type: TYPE, version: VERSION, ...params });
 
@@ -178,3 +191,3 @@ const { G:wasmG, G2:wasmG2, xor:wasmXOR, getLZ:wasmLZ } = wasmInstance.exports;
   // The actual number of blocks is m', which is m rounded down to the nearest multiple of 4*p.
-  const m_ = 4 * ctx.lanes * Math.floor(ctx.m_cost / (4 * ctx.lanes));
+  const m_ = 4 * ctx.lanes * Math.floor(ctx.memorySize / (4 * ctx.lanes));
   const requiredMemory = m_ * ARGON2_BLOCK_SIZE + 10 * KB; // Additional KBs for utility references
@@ -198,3 +211,3 @@ if (memory.buffer.byteLength < requiredMemory) {
   const newBlock = new Uint8Array(memory.buffer, offset, ARGON2_BLOCK_SIZE); offset+=newBlock.length;
-  const blockMemory = new Uint8Array(memory.buffer, offset, ctx.m_cost * ARGON2_BLOCK_SIZE);
+  const blockMemory = new Uint8Array(memory.buffer, offset, ctx.memorySize * ARGON2_BLOCK_SIZE);
   const allocatedMemory = new Uint8Array(memory.buffer, 0, offset);
@@ -254,3 +267,3 @@
           if (pass === 0) initBlock(i, j);
-          G(wasmContext, prevBlock, B[l][z],  pass > 0 ? newBlock : B[i][j]);
+          G(wasmContext, prevBlock, B[l][z], pass > 0 ? newBlock : B[i][j]);
 
@@ -271,3 +284,3 @@ // 6. If the number of passes t is larger than 1, we repeat step 5. However, blocks are computed differently as the old value is XORed with the new one
 
-  const tag = H_(ctx.outlen, C, new Uint8Array(ctx.outlen));
+  const tag = H_(ctx.tagLength, C, new Uint8Array(ctx.tagLength));
   // clear memory since the module might be cached
@@ -286,4 +299,4 @@ allocatedMemory.fill(0) // clear sensitive contents
   LE32(params, ctx.lanes, 0);
-  LE32(params, ctx.outlen, 4);
-  LE32(params, ctx.m_cost, 8);
+  LE32(params, ctx.tagLength, 4);
+  LE32(params, ctx.memorySize, 8);
   LE32(params, ctx.passes, 12);
@@ -294,7 +307,7 @@ LE32(params, ctx.version, 16);
   const toHash = [params];
-  if (ctx.pwd) {
-    toHash.push(LE32(new Uint8Array(4), ctx.pwd.length, 0))
-    toHash.push(ctx.pwd)
+  if (ctx.password) {
+    toHash.push(LE32(new Uint8Array(4), ctx.password.length, 0))
+    toHash.push(ctx.password)
   } else {
-    toHash.push(ZERO32) // context.pwd.length
+    toHash.push(ZERO32) // context.password.length
   }
@@ -301,0 +314,0 @@

lib/blake2b.js

@@ -230,3 +230,3 @@ // Adapted from the reference implementation in RFC7693
   }
-} 
+}
 
@@ -233,0 +233,0 @@

lib/setup.js

@@ -19,9 +19,2 @@ import argon2id from "./argon2id.js";
 
-/**
- * Load Wasm module and return argon2id wrapper.
- * It is platform-independent and it uses the Wasm binary data returned by the two functions given in input.
- * @param {(importObject) => WebAssembly.Instance} getSIMD - function instantiating and returning the SIMD Wasm instance
- * @param {(importObject) => WebAssembly.Instance} getNonSIMD - function instantiating and returning the non-SIMD Wasm instance
- * @returns {computeHash}
- */
 export default async function setupWasm(getSIMD, getNonSIMD) {
@@ -39,5 +32,11 @@ const memory = new WebAssembly.Memory({
    * @callback computeHash
-   * @param {object} params
-   * @param {Uint8Array} params.pwd - password
+   * @param {Object} params
+   * @param {Uint8Array} params.password - password
    * @param {Uint8Array} params.salt - salt
+   * @param {Integer} params.parallelism
+   * @param {Integer} params.passes
+   * @param {Integer} params.memorySize - in kibibytes
+   * @param {Integer} params.tagLength - output tag length
+   * @param {Uint8Array} [params.ad] - associated data (optional)
+   * @param {Uint8Array} [params.secret] - secret data (optional)
    * @return {Uint8Array} argon2id hash
@@ -44,0 +43,0 @@ */

package.json

 {
   "name": "argon2id",
-  "version": "0.0.1-3",
+  "version": "1.0.0",
   "description": "Argon2id implementation in pure Javascript",
   "main": "index.js",
   "type": "module",
+  "types": "index.d.ts",
   "files": [
     "dist/",
-    "lib/"
+    "lib/",
+    "index.d.ts"
   ],
   "scripts": {
-    "test": "tape-es test/blake2b.spec.js | tap-spec && tape-es test/argon2id.spec.js | tap-spec",
-    "lint": "eslint index.js",
+    "test": "mocha --loader=ts-node/esm test/blake2b.spec.js test/argon2id.spec.ts",
+    "lint": "eslint index.js lib test",
     "build": "rm -rf dist && mkdir dist && ./build-wasm.sh",
@@ -29,5 +31,7 @@ "test-browser": "karma start karma.config.cjs",
   "devDependencies": {
-    "@typescript-eslint/eslint-plugin": "^5.38.0",
-    "@typescript-eslint/parser": "^5.38.0",
-    "base64-loader": "^1.0.0",
+    "@types/chai": "^4.3.4",
+    "@types/mocha": "^10.0.1",
+    "@typescript-eslint/eslint-plugin": "^5.51.0",
+    "@typescript-eslint/parser": "^5.51.0",
+    "chai": "^4.3.7",
     "eslint": "^8.32.0",
@@ -39,10 +43,11 @@ "eslint-plugin-import": "^2.27.5",
     "karma-firefox-launcher": "^2.1.2",
-    "karma-spec-reporter": "^0.0.36",
-    "karma-tape": "^0.0.1",
+    "karma-mocha": "^2.0.1",
+    "karma-mocha-reporter": "^2.2.5",
     "karma-webkit-launcher": "^2.1.0",
     "karma-webpack": "^5.0.0",
+    "mocha": "^10.2.0",
     "playwright": "^1.30.0",
     "string-replace-loader": "^3.1.0",
-    "tap-spec": "^5.0.0",
-    "tape-es": "^1.2.17",
+    "ts-loader": "^9.4.2",
+    "ts-node": "^10.9.1",
     "wasm-loader": "^1.3.0",
@@ -49,0 +54,0 @@ "webpack": "^5.75.0",

README.md

@@ -1,1 +0,73 @@
-WIP
+# Argon2id
+
+Fast, lightweight Argon2id implementation for both browser and Node:
+- optimized for bundle size (< 7KB minified and gizipped, with wasm inlined as base64)
+- SIMD support, with automatic fallback to non-SIMD binary if not supported (e.g. in Safari)
+- performance is comparable to or better than [argon2-browser](https://github.com/antelle/argon2-browser).
+
+We initially tried implementing a solution in pure JS (no Wasm) but the running time was unacceptable.
+We resorted to implement part of the module in Wasm, to take advantage of 64-bit multiplications and SIMD instructions. The Wasm binary remains small thanks to the fact that the memory is fully managed by the JS side, hence no memory management function gets included in the Wasm binary.
+
+## Install
+
+Install from npm (compiled wasm files included):
+
+```sh
+npm i argon2id
+```
+
+## Usage
+
+With bundlers like Rollup (through [plugin-wasm](https://www.npmjs.com/package/@rollup/plugin-wasm)) or Webpack (through [wasm-loader](https://www.npmjs.com/package/wasm-loader)), that automatically translate import statements like `import wasmModule from '*.wasm'` to a loader of type `wasmModule: (instanceOptions) => WebAssembly.WebAssemblyInstantiatedSource` (either sync or async), you can simply use the default export like so:
+
+```js
+import loadArgon2idWasm from 'argon2id';
+
+const argon2id = await loadArgon2idWasm();
+const hash = argon2id({
+  password: new Uint8Array(...),
+  salt: crypto.getRandomValues(new Uint8Array(32)),
+  parallelism: 4,
+  passes: 3,
+  memorySize: 2**16
+});
+```
+Refer to the [Argon2 RFC](https://www.rfc-editor.org/rfc/rfc9106.html#name-parameter-choice) for details about how to pick the parameters.
+
+**Note about memory usage:** every call to `loadArgon2idWasm` will instantiate and run a separate Wasm instance, with separate memory.
+The used Wasm memory is cleared after each call to `argon2id`, but it isn't deallocated (this is due to Wasm limitations).
+Re-loading the Wasm module is thus recommended in order to free the memory if multiple `argon2id` hashes are computed and some of them require considerably more memory than the rest.
+
+### Custom Wasm loaders
+
+The library does not require a particular toolchain. If the aforementioned bundlers are not an option, you can manually take care of setting up the Wasm modules.
+
+For instance, **in Node, the library can be used without bundlers**. You will need to pass two functions that instantiate the Wasm modules to `setupWasm` (first function is expected to take care of the SIMD binary, second one the non-SIMD one):
+
+```js
+import fs from 'fs';
+import setupWasm from 'argon2id/lib/setup.js';
+
+// point to compiled binaries
+const SIMD_FILENAME = 'argon2id/dist/simd.wasm';
+const NON_SIMD_FILENAME = 'argon2id/dist/no-simd.wasm';
+
+const argon2id = await setupWasm(
+  (importObject) => WebAssembly.instantiate(fs.readFileSync(SIMD_FILENAME), importObject),
+  (importObject) => WebAssembly.instantiate(fs.readFileSync(NON_SIMD_FILENAME), importObject),
+);
+```
+
+Using the same principle, for browsers you can use bundlers with simple base-64 file loaders. 
+
+## Compiling
+
+**The npm package already includes the compiled binaries.**<br>
+If you fork the repo, you'll have to manually compile wasm (Docker required):
+```sh
+npm run build
+```
+
+The resulting binaries will be under `dist/`.
+If you do not want to use docker, you can look into installing [emscripten](https://emscripten.org/); you'll find the compilation commands to use in `build_wasm.sh`.
+

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

56221

increased by11.22%

Number of package files

12

increased by20%

Lines of code

624

increased by7.96%

Number of low quality alerts

1

decreased by-50%

Number of lines in readme file

74

increased by7300%

Worsened metrics

Dev dependency count

23

increased by15%

No dependency changes