sha-obj

SHAObj

SHAObj 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 Crypto.subtle method provided by modern browsers and node.js.

Optionally it possible to get multiple different digest methods with a little help of BaseEx. BaseEx also enables the feature to feed the Object with not just byte-like input but almost any type available in JavaScript.

Installation

GitHub

git clone https://github.com/UmamiAppearance/SHAObj.git

npm

nmp install sha-obj

Builds

You can find builds in dist. Builds include versions with BaseEx build in and without the library. Two types for both kinds are available (esm and iife), plus a minified version of each.

If you want to build it by yourself run:

npm run build

Builds with BaseEx (any desired input/several digest methods)

• sha-obj-bex.esm.js
• sha-obj-bex.esm.min.js
• sha-obj-bex.iife.js
• sha-obj-bex.iife.min.js

Builds without BaseEx (byte like input/hexdigest)

• sha-obj.esm.js
• sha-obj.esm.min.js
• sha-obj.iife.js
• sha-obj.iife.min.js

Usage

Importing

node.js

esm

import SHAObj from "sha-obj";

cjs

const SHAObj = require("sha-obj");

Browser

esm

import SHAObj from "./path/sha-obj-bex.esm.min.js";

esm from CDN (jsdelivr)

import SHAObj from "https://cdn.jsdelivr.net/npm/sha-obj@latest/dist/sha-obj-bex.esm.min.js"

iife script tag

<script src="./path/sha-obj-bex.iife.min.js"></script>

iife script tag from CDN (jsdelivr)

<script src="https://cdn.jsdelivr.net/npm/sha-obj@latest/dist/sha-obj-bex.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 ways available to create an instance:

the new operator

// default, SHA-256
const sha256 = new SHAObj();

// SHA-512
const sha512 = new SHAObj("SHA-512");

the new method

// default, SHA-256
const sha256 = await SHAObj.new();

// SHA-512
const sha512 = await SHAObj.new("SHA-512");

As the method is asynchronous it allows you to associate a message in one go.

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

Methods and Properties

Static

SHAObj.algorithmsAvailable()

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

SHAObj.algorithmsGuaranteed()

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

SHAObj.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.

SHAObj.baseEx [object]

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

MIT

Copyright (c) 2023, UmamiAppearance