BrowserSHAObj

BrowserSHAObj creates a SHA-(1/256/384/512) object. It is very closely related to pythons hashlib in its methods and features. It provides an easy access to the browsers Crypto.subtle method, and also makes it possible to get multiple different digest methods with a little help of BaseEx.

Installation

GitHub

1git clone https://github.com/UmamiAppearance/BrowserSHAObj.git

npm

1nmp install browser-sha-obj

Builds

You can find builds in dist. If you want to build by yourself run:

1npm run build

Two types are available (esm and iife), plus a minified version of each.

• BrowserSHAObj.esm.js
• BrowserSHAObj.esm.min.js
• BrowserSHAObj.iife.js
• BrowserSHAObj.iife.min.js

Usage

Importing

BrowserSHAObj is a ESM module and exported as default. Importing works as follows:

1// esm
2import BrowserSHAObj from "./path/BrowserSHAObj.esm.min.js";
3
4// esm from CDN (jsdelivr)
5import BrowseSHAObj from "https://cdn.jsdelivr.net/npm/browser-sha-obj@latest/dist/BrowserSHAObj.esm.min.js"

1<!-- script tag -->
2<script src="./path/BrowserSHAObj.iife.min.js"></script>
3
4<!-- script tag from CDN (jsdelivr)-->
5<script src="https://cdn.jsdelivr.net/npm/browser-sha-obj@latest/dist/BrowserSHAObj.iife.min.js"></script>

Creating an instance

The constructor takes one argument for the algorithm which is set to SHA-256 by default. Available options are:

• SHA-1
• SHA-256
• SHA-384
• SHA-512

There a two possible methods available to create an instance:

new operator

1// default, SHA-256
2const sha256 = new BrowserSHAObj();
3
4// SHA-512
5const sha512 = new BrowserSHAObj("SHA-512");

new method

1// default, SHA-256
2const sha256 = await BrowserSHAObj.new();
3
4// SHA-512
5const sha512 = await BrowserSHAObj.new("SHA-512");

The method is asynchronous to allow you to associate a message in one go.

1// SHA-512
2const sha512 = await BrowserSHAObj.new("SHA-512", "Hello World!");

Methods and Properties

Static

BrowserSHAObj.algorithmsAvailable()

A set containing the names of the hash algorithms that are available.

BrowserSHAObj.algorithmsGuaranteed()

Added for the sake of completeness in terms of compatibility with pythons hashlib. Here it is simply pointing to algorithmsAvailable.

BrowserSHAObj.new(algorithm, input)

Asynchronously creates a new instance. Optionally takes the algorithm as the first parameter, also an optional input which can be provided as the second parameter, and gets passed to the update method.

BrowserSHAObj.baseEx

A BaseEx Instance for the possibility to manually convert (byte) representations.

Instance

digestSize (property)

The size of the resulting hash in bytes.

blockSize (property)

The internal block size of the hash algorithm in bytes.

name (property)

The canonical name of this hash, always uppercase and always suitable as a parameter to create another hash of this type.

update(input[, replace=false])

Update the hash object with almost any input. The input gets converted to a Uint8Array. Unless replace is set to true, repeated calls are equivalent to a single call with the concatenation of all the arguments:
shaObj.update(a); shaObj.update(b) is in many occasions equivalent to shaObj.update(a+b).

(Note: The process is a concatenation of bytes. Take as an exception for instance shaObj.update(1); shaObj.update(2), which is not the same as shaObj.update(1+2))

replace(input)

Replace the the hash object with fresh input (the same as update(input, true)).

digest()

Return the digest of the data passed to the update method so far. This is an ArrayBuffer of size digestSize.

hexdigest()

Like digest except the digest is returned as a string of double length, containing only hexadecimal digits. This may be used (as one of many options) to exchange the value safely in non-binary environments.

basedigest (object)

Provides many different methods to covert the digest into different base representations. Take a look at the live-examples, to see it in action.
Every basedigest optionally takes additional BaseEx Parameters.

copy()

Async method to return a copy/clone of the hash object. This can be used to efficiently compute the digests of data sharing a common initial substring.

Examples

Here you can find many live-examples. To get a better idea of a possible use case, take a look at the Online SHA Checksum Calculator.

License

This work is licensed under GPL-3.0.