Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/Caligatio/jsSHA

A JavaScript/TypeScript implementation of the complete Secure Hash Standard (SHA) family (SHA-1, SHA-224/256/384/512, SHA3-224/256/384/512, SHAKE128/256, cSHAKE128/256, and KMAC128/256) with HMAC.
https://github.com/Caligatio/jsSHA

cryptography cshake hash hmac javascript kmac sha sha-1 sha-2 sha-224 sha-256 sha-3 sha-384 sha-512 sha3-224 sha3-256 sha3-384 sha3-512 shake typescript

Last synced: 2 months ago
JSON representation

A JavaScript/TypeScript implementation of the complete Secure Hash Standard (SHA) family (SHA-1, SHA-224/256/384/512, SHA3-224/256/384/512, SHAKE128/256, cSHAKE128/256, and KMAC128/256) with HMAC.

Host: GitHub
URL: https://github.com/Caligatio/jsSHA
Owner: Caligatio
License: bsd-3-clause
Created: 2012-07-21T15:43:35.000Z (over 12 years ago)
Default Branch: master
Last Pushed: 2024-03-11T05:47:11.000Z (11 months ago)
Last Synced: 2024-10-29T15:06:53.847Z (3 months ago)
Topics: cryptography, cshake, hash, hmac, javascript, kmac, sha, sha-1, sha-2, sha-224, sha-256, sha-3, sha-384, sha-512, sha3-224, sha3-256, sha3-384, sha3-512, shake, typescript
Language: TypeScript
Homepage: https://caligatio.github.io/jsSHA/
Size: 1.86 MB
Stars: 2,237
Watchers: 71
Forks: 394
Open Issues: 2
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: SECURITY.md

Awesome Lists containing this project

README

        # jsSHA

A pure TypeScript/JavaScript streaming implementation of the complete Secure

Hash Standard (SHA) family (SHA-1, SHA-224/256/384/512, SHA3-224/256/384/512,

SHAKE128/256, cSHAKE128/256, and KMAC128/256) with HMAC.

[![npm](https://img.shields.io/npm/v/jssha)](https://www.npmjs.com/package/jssha)

![main workflow](https://github.com/Caligatio/jsSHA/actions/workflows/main.yml/badge.svg)

[![NPM](https://img.shields.io/npm/l/jssha)](https://opensource.org/licenses/BSD-3-Clause)

## Usage

More complete documentation can be found on the

[jsSHA Wiki](https://github.com/Caligatio/jsSHA/wiki) but below are common

use-cases.

### Installation

#### Browser

Include the desired JavaScript file (sha.js, sha1.js, sha256.js, sha512.js, or

sha3.js) in your header:

```html

```

#### Node.js

jsSHA is available through NPM and be installed by simply doing

```console

npm install jssha

```

To use the module, first require it using:

```javascript

const jsSHA = require("jssha");

/* The limited variant files are also exported (sha1, sha256, sha512, and sha3)

 * using conditional subpath exports in Node.js v13+ or using --experimental-modules

 * in v12 */

const jsSHA1 = require("jssha/sha1");

/* For Node.js versions that don't support subpath exports, you can do the

 * following instead: */

const jsSHA1 = require("jssha/dist/sha1");

/* Alternatively, you can load it as an ESM (Node.js v13+ or using

 * --experimental-modules in v12) */

import jsSHA from "jssha";

```

### Hashing

Instantiate a new `jsSHA` object with the desired hash variant, input format,

and options as parameters. The hash variant can be one of SHA-1, SHA-224,

SHA3-224, SHA-256, SHA3-256, SHA-384, SHA3-384, SHA-512, SHA3-512, SHAKE128, or

SHAKE256. The input format can be one of HEX, TEXT, B64, BYTES, ARRAYBUFFER, or

UINT8ARRAY. You can then stream in input using the `update` object function,

calling it multiple times if needed. Finally, simply call `getHash` with the

output type as a parameter (B64, HEX, BYTES, ARRAYBUFFER, or UINT8ARRAY).

Example to calculate the SHA-512 of "This is a test":

```javascript

const shaObj = new jsSHA("SHA-512", "TEXT", { encoding: "UTF8" });

/* .update() can be chained */

shaObj.update("This is").update(" a ");

shaObj.update("test");

const hash = shaObj.getHash("HEX");

```

The constructor takes a hashmap as a optional third argument with defaults

`{"encoding" : "UTF8", "numRounds" : 1}`. `numRounds` controls the number of

hashing iterations/rounds performed and `encoding` specifies the encoding used

to encode TEXT-type inputs. Valid `encoding` values are "UTF8", "UTF16BE", and

"UTF16LE".

`getHash` also takes a hashmap as an optional second argument with defaults

`{"outputUpper" : false, "b64Pad" : "="}`. `outputUpper` is only used for "HEX"

outputs and `b64Pad` only for "B64" outputs.

**_Important_**: SHAKE128 and SHAKE256 require `outputLen` to be in the hashmap

where `outputLen` is the desired output length of the SHAKE algorithm in a

multiple of 8 bits.

### HMAC

Instantiate a new `jsSHA` object similiar to hashing but with the third argument

in the form of `{ "hmacKey": { "value": VALUE, "format": FORMAT } }`. FORMAT

takes the same values as the input format from hashing and the VALUE is then

either a `string`, `ArrayBuffer`, or `Uint8Array`. You can stream in the input

using the `update` object function just like hashing. Finally, get the HMAC by

calling the `getHash` function with the output type as its argument. Example to

calculate the SHA-512 HMAC of the string "This is a test" with the key "abc":

```javascript

const shaObj = new jsSHA("SHA-512", "TEXT", {

  hmacKey: { value: "abc", format: "TEXT" },

});

shaObj.update("This is a ");

shaObj.update("test");

const hmac = shaObj.getHash("HEX");

```

Note: You cannot specify `numRounds` with HMAC.

### cSHAKE

Instantiate a new `jsSHA` object similiar to HMAC but first argument being

either "CSHAKE128" or "CSHAKE256" and the third argument in the form of

`{ "customization"?: { "value": VALUE, "format": FORMAT }, "funcName"?: { "value": VALUE, "format": FORMAT } }`.

FORMAT takes the same values as the input format from hashing and the VALUE is

then either a `string`, `ArrayBuffer`, or `Uint8Array`. Per the NIST

specification, both `customization` and `funcName` are optional. You can stream

in the input using the `update` object function just like hashing. Finally, get

the hash by calling the `getHash` function with the output type and length as

arguments. Example to calculate the cSHAKE128 of the string "This is a test"

with the customization string "My Tagged Application" and an output size of

256-bits.

```javascript

const shaObj = new jsSHA("CSHAKE128", "TEXT", {

  customization: { value: "My Tagged Application", format: "TEXT" },

});

shaObj.update("This is a ");

shaObj.update("test");

const cshake = shaObj.getHash("HEX", { outputLen: 256 });

```

Note: You cannot specify `numRounds` with cSHAKE.

**_Important_**: `outputLen` is required to be in the hashmap where `outputLen`

is the desired output length of the cSHAKE algorithm in a multiple of 8 bits.

### KMAC

Instantiate a new `jsSHA` object similiar to cSHAKE but first argument being

either "KMAC128" or "KMAC256" and the third argument in the form of

`{ "customization"?: { "value": VALUE, "format": FORMAT }, "kmacKey?: { "value": VALUE, "format": FORMAT } }`.

FORMAT takes the same values as the input format from hashing and the VALUE is

then either a `string`, `ArrayBuffer`, or `Uint8Array`. Per the NIST

specification `customization` is optional whereas `kmacKey` is required. You can

stream in the input using the `update` object function just like hashing.

Finally, get the hash by calling the `getHash` function with the output type and

length as arguments. Example to calculate the KMAC128 of the string "This is a

test" with the customization string "My Tagged Application", key "abc", and an

output size of 256-bits.

```javascript

const shaObj = new jsSHA("KMAC128", "TEXT", {

  customization: { value: "My Tagged Application", format: "TEXT" },

  kmacKey: { value: "abc", format: "TEXT" },

});

shaObj.update("This is a ");

shaObj.update("test");

const kmac = shaObj.getHash("HEX", { outputLen: 256 });

```

Note: You cannot specify `numRounds` with KMAC.

**_Important_**: `outputLen` is required to be in the hashmap where `outputLen`

is the desired output length of the KMAC algorithm in a multiple of 8 bits.

## Files

- **dist/sha.js** - The minified ECMAScript 3 (ES3) compatible [Universal Module

  Definition (UMD)][umd] version of the library with support for all hash

  variants. Its accompanying source map can be found in dist/sha.js.map and its

  TypeScript declarations in dist/sha.d.ts.

- **dist/sha.mjs** - The minified ECMAScript 2015 (ES6) compatible ESM version

  of the library with support for all hash variants. Its accompanying source map

  can be found in dist/sha.mjs.map and its TypeScript declarations in

  dist/sha.d.ts.

- **dist/sha1.{js,mjs}** - The minified UMD and ESM versions of the library with

  support for only the SHA-1 hash variant. Its accompanying TypeScript

  declarations can be found in dist/sha1.d.ts.

- **dist/sha256.{js,mjs}** - The minified UMD and ESM versions of the library

  with support for only the SHA-224 and SHA-256 hash variants. Its accompanying

  TypeScript declarations can be found in dist/sha256.d.ts.

- **dist/sha512.{js,mjs}** - The minified UMD and ESM versions of the library

  with support for only the SHA-384 and SHA-512 hash variants. Its accompanying

  TypeScript declarations can be found in dist/sha513.d.ts.

- **dist/sha3.{js,mjs}** - The minified UMD and ESM versions of the library with

  support for only the SHA3-224, SHA3-256, SHA3-384, SHA3-512, SHAKE128,

  SHAKE256, cSHAKE128, cSHAKE256, KMAC128, and KMAC256 hash variants. Its

  accompanying TypeScript declarations can be found in dist/sha3.d.ts.

## Contact Info

The project's website is located at https://caligatio.github.io/jsSHA/

[umd]: https://github.com/umdjs/umd