hash-wasm

All algorithms in hash-wasm depend on the binary representation of the input string. Because different Unicode sequences can represent the same character (e.g., \u00fc vs u\u0308), you should normalize your strings before hashing to ensure consistent results.

It is highly recommended to use the built-in String.prototype.normalize() method, specifically with the "NFKC" form, before encoding with TextEncoder.

// Example of normalization
const te = new TextEncoder();
const str1 = "u\u0308";
const str2 = "\u00fc";

// Without normalization, these might produce different hashes
te.encode(str1.normalize("NFKC"));
te.encode(str2.normalize("NFKC"));

To use hash-wasm in a Node.js, Deno, or a bundled web project, install it using npm:

npm i hash-wasm

You can use hash-wasm directly in the browser without a bundler by loading it via jsDelivr.

To load all algorithms into the global hashwasm variable, use the main bundle. To load specific algorithms to keep the footprint small, load the individual UMD files.

<!-- load all algortihms into the global `hashwasm` variable -->
<script src="https://cdn.jsdelivr.net/npm/hash-wasm@4"></script>

<!-- load individual algortihms into the global `hashwasm` variable -->
<script src="https://cdn.jsdelivr.net/npm/hash-wasm@4/dist/md5.umd.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/hash-wasm@4/dist/hmac.umd.min.js"></script>

The shorthand form is the easiest and fastest way to calculate hashes when the input buffer is already in memory. It reuses the same WASM instance and state to perform multiple calculations, making it more efficient than creating new instances for every call.

Supported shorthand functions include md5, sha1, sha512, and sha3 (which accepts a bit length as a second argument). These functions accept strings or typed arrays (e.g., Uint8Array, Uint32Array) as input.

import { md5, sha1, sha512, sha3 } from "hash-wasm";

async function run() {
  console.log("MD5:", await md5("demo"));

  const int8Buffer = new Uint8Array([0, 1, 2, 3]);
  console.log("SHA1:", await sha1(int8Buffer));
  console.log("SHA512:", await sha512(int8Buffer));

  const int32Buffer = new Uint32Array([1056, 641]);
  console.log("SHA3-256:", await sha3(int32Buffer, 256));
}

run();

HMAC can be calculated using any supported hash function. To optimize performance, create the hash function instance once and reuse it by calling .init() between different inputs.

Workflow:

1. Create a hash function instance using createXXXX().
2. Create an HMAC instance using await createHMAC(hashFunc, "key").
3. For each input, call hmac.init(), hmac.update(data), and hmac.digest().

import { createHMAC, createSHA3 } from "hash-wasm";

async function run() {
  const hashFunc = createSHA3(224); // SHA3-224
  const hmac = await createHMAC(hashFunc, "key");

  const fruits = ["apple", "raspberry", "watermelon"];
  console.log("Input:", fruits);

  const codes = fruits.map((data) => {
    hmac.init();
    hmac.update(data);
    return hmac.digest();
  });

  console.log("HMAC:", codes);
}

run();

Use the pbkdf2 function to derive keys. It requires a hash function instance created via createXXXX().

Parameters for pbkdf2:

• password: The input string.
• salt: A Uint8Array.
• iterations: Number of iterations.
• hashLength: Desired output size in bytes.
• hashFunction: An instance of a hash function (e.g., from createSHA1()).
• outputType: The desired output format (e.g., "hex").

import { pbkdf2, createSHA1 } from "hash-wasm";

async function run() {
  const salt = new Uint8Array(16);
  window.crypto.getRandomValues(salt);

  const key = await pbkdf2({
    password: "password",
    salt,
    iterations: 1000,
    hashLength: 32,
    hashFunction: createSHA1(),
    outputType: "hex",
  });

  console.log("Derived key:", key);
}

run();

For key derivation, use pbkdf2 or scrypt.

pbkdf2 options:

• password: Password/message.
• salt: Salt.
• iterations: Number of iterations.
• hashLength: Output size in bytes.
• hashFunction: A Promise<IHasher> (e.g., createSHA1()).
• outputType: 'hex' | 'binary' (default 'hex').

scrypt options:

• password: Password/message.
• salt: Salt.
• costFactor: CPU/memory cost (must be a power of 2, e.g., 1024).
• blockSize: Block size parameter (8 is common).
• parallelism: Degree of parallelism.
• hashLength: Output size in bytes.
• outputType: 'hex' | 'binary' (default 'hex').

Argon2 is a memory-hard password hashing function. You can use argon2i, argon2d, or argon2id variants.

Options (IArgon2Options):

• password: The password/message to hash.
• salt: Random salt.
• secret: (Optional) Secret for keyed hashing.
• iterations: Number of iterations.
• parallelism: Degree of parallelism.
• memorySize: Memory to use in kibibytes (e.g., 1024).
• hashLength: Output size in bytes.
• outputType: 'hex' | 'binary' | 'encoded' (default 'hex').

To verify a password against an encoded hash, use argon2Verify.

const hash = await argon2id({
  password: 'password',
  salt: 'salt',
  iterations: 2,
  memorySize: 1024,
  parallelism: 1,
  hashLength: 32
});

const isValid = await argon2Verify({
  password: 'password',
  hash: hash // the encoded string
});

Bcrypt is a password hashing function based on the Blowfish cipher. Use bcrypt to create a hash and bcryptVerify to check it.

bcrypt options:

• password: The password to hash.
• salt: 16-byte salt.
• costFactor: Number of iterations (4 - 31).
• outputType: 'hex' | 'binary' | 'encoded' (default 'encoded').

bcryptVerify options:

• password: The password to check.
• hash: The encoded hash string.

const hash = await bcrypt({
  password: 'my-password',
  salt: 'random-salt-16b',
  costFactor: 10
});

const isValid = await bcryptVerify({
  password: 'my-password',
  hash: hash
});