browserHash

A lightweight wrapper to make digests from the Web Crypto API a little more pleasant to use. Hash strings, ArrayBuffers, and TypedArrays directly in the browser with zero dependencies or other overhead.

[!WARNING]

This library is not a security tool!

Browser-hash is not intended for cryptographic purposes and should not be used as a substitute for proper security system design. Learn more about non-cryptographic use of Web Crypto's digest method on MDN.

Table of Contents

• Installation
• Usage
  • browserHash
  • isBuffer
  • stringToBuffer
  • bufferToHex
  • bufferHash
• Compatibility
• Tests
• License

Installation

npm install --save browser-hash

Usage

browserHash

import browserHash from "browser-hash";

let name = "Ishmael";

browserHash(name).then(console.log);
// 1aa0fcc1147088ab255380f60b7d1b6394fd447a33ef5a067c188b79f9b81d94

browserHash(strOrBuffer, [algo="SHA-256"])

Parameters:

• strOrBuffer - The value to hash. Can be a string, an ArrayBuffer, or a TypedArray (Uint8Array, Uint16Array, etc). Throws an error if passed any other type of value.
• algo (optional) - The name of the hashing algorithm to use. Supported values are:
  • "SHA-1"
  • "SHA-256" (default)
  • "SHA-384"
  • "SHA-512"

Returns:

• A Promise that resolves to the specified hash, formatted as a hexadecimal string.

A lightweight wrapper around SubtleCrypto.digest, browserHash asynchronously hashes a string or buffer. All resulting digests are formatted as hexadecimal strings for convenience.

If you wish to use a different algorithm than the default SHA-256, specify the name of the algorithm as the second parameter.

let name = "Ishmael";

browserHash(name, "SHA-1").then(console.log);
// 5cf59925a1926d4907a6bf56f42f0355b34a5812

ArrayBuffers and TypedArrays can hashed the same way as strings.

let data = Uint8Array.from([80, 101, 113, 117, 111, 100]);

browserHash(data).then(console.log);
// 01c66c73fdc47f95e37e12bdbd637c07d6ce116eb5409d188b6baa4c23ab0e3a

isBuffer

import { isBuffer } from "browser-hash";

let name = "Ishmael";
let data = Uint8Array.from([80, 101, 113, 117, 111, 100]);

console.log(isBuffer(name));
// false

console.log(isBuffer(data));
// true

console.log(isBuffer([1, 2, 3]));
// false

isBuffer(val)

Parameters:

• val - The value to check.

Returns:

• A boolean. Returns true if the value is an ArrayBuffer or TypedArray, false otherwise.

In addition to the default browserHash function, some of the utilities used internally by this library are provided as named exports for convenience.

The isBuffer function simply checks if a value is an ArrayBuffer or TypedArray.

stringToBuffer

import { stringToBuffer } from "browser-hash";

let data = stringToBuffer("Pequod");

console.log(data);
// Uint8Array(6) [80, 101, 113, 117, 111, 100]

stringToBuffer(str)

Parameters:

• str - The string to convert to a Uint8Array. Throws an error if passed a non-string value.

Returns:

• A UTF-8 encoded Uint8Array.

stringToBuffer is a very thin wrapper around TextEncoder.encode.

bufferToHex

import { bufferToHex } from "browser-hash";

let data = Uint8Array.from([80, 101, 113, 117, 111, 100]);

console.log(bufferToHex(data));
// 506571756f64

bufferToHex(buffer)

Parameters:

• buffer - An ArrayBuffer or TypedArray to convert into a hex string.

Returns:

• The binary data from the buffer, formatted as a hexadecimal string.

Convert buffers to hex strings for readability and portability.

bufferHash

import { bufferHash } from "browser-hash";

let name = "Ishmael";

bufferHash(name).then(console.log);
// Uint8Array(32) [26, 160, 252, 193, 20, 112, 136, ...]

bufferHash(strOrBuffer, [algo="SHA-256"])

Parameters:

• strOrBuffer - The value to hash. Can be a string, an ArrayBuffer, or a TypedArray (Uint8Array, Uint16Array, etc). Throws an error if passed any other type of value.
• algo (optional) - The name of the hashing algorithm to use. Supported values are:
  • "SHA-1"
  • "SHA-256" (default)
  • "SHA-384"
  • "SHA-512"

Returns:

• A Promise that resolves to the specified hash, formatted as a Uint8Array.

Identical to the default browserHash function, but skips converting the digest to a hex string, instead returning a Uint8Array directly. Useful if you want to do further binary operations on the digest.

Compatibility

Compatible with any browser that supports Web Crypto, TextEncoder, and JavaScript modules. Basically all modern browsers and not Internet Explorer.

Tests

This repo includes some units tests of the basic functionality in the spec/ directory. To run the tests, first clone this repo and install the dev dependencies:

git clone https://github.com/delventhalz/browser-hash.git
cd browser-hash
npm install

Then run the tests:

npm test

The repo is also linted using ESLint and a modified version of the AirBnB Style Guide. To run the linter:

npm run lint

License

MIT Licensed