sha-obj
v1.0.7
Published
JavaScript implementation of SHA-(1/256/384/512) checksum calculation for the browser and node. [Crypto.subtle]
Downloads
22
Maintainers
Readme
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)
Builds without BaseEx (byte like input/hexdigest)
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
Copyright (c) 2023, UmamiAppearance