jsSHA Documentation

Depending on your environment, you can install or include jsSHA as follows:

Browser

Include the desired JavaScript file in your HTML header:

<script type="text/javascript" src="/path/to/sha.js"></script>

Node.js

Install via npm:

npm install jssha

To use it, you can require the full module or specific variants (using subpath exports in Node.js v13+):

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

// For older Node.js versions without subpath exports:
const jsSHA1 = require("jssha/dist/sha1");

// Using ESM (Node.js v13+):
import jsSHA from "jssha";

Deno

Use the npm: import specifier:

import jsSHA from "npm:jssha";
import jsSHA1 from "npm:jssha/sha1";

When providing input to jsSHA functions, you can specify the data format and encoding using the GenericInputType structure. This allows you to pass strings (with optional encoding), encoded strings (HEX, B64, BYTES), or raw binary data (ArrayBuffer or Uint8Array).

Supported Encodings

• UTF8
• UTF16BE
• UTF16LE

Supported Formats

• TEXT: For raw strings. Requires an optional encoding.
• B64: Base64 encoded strings.
• HEX: Hexadecimal strings.
• BYTES: Byte strings.
• ARRAYBUFFER: Raw ArrayBuffer objects.
• UINT8ARRAY: Raw Uint8Array objects.

To calculate KMAC, use the variants KMAC128 or KMAC256. The third argument accepts an options object containing an optional customization and a required kmacKey. Both require a value and a format.

Important:

• outputLen is required in the getHash options object (the desired output length in multiples of 8 bits).
• You cannot specify numRounds with KMAC.

Example:

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 });

To calculate cSHAKE, use the variants CSHAKE128 or CSHAKE256. The third argument accepts an options object containing optional customization and funcName objects. Both require a value and a format.

Important:

• outputLen is required in the getHash options object (the desired output length in multiples of 8 bits).
• You cannot specify numRounds with cSHAKE.

Example:

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 });

To calculate an HMAC, instantiate jsSHA with a hash variant and input format, then provide an hmacKey in the third argument. The key object requires a value (string, ArrayBuffer, or Uint8Array) and a format (matching the supported input formats).

Note: You cannot specify numRounds when using HMAC.

Example:

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");

The EncodingType defines the character encoding used when processing TEXT format inputs.

export type EncodingType = "UTF8" | "UTF16BE" | "UTF16LE";

The FormatType determines how the value in a GenericInputType is interpreted.

export type FormatNoTextType = "HEX" | "B64" | "BYTES" | "ARRAYBUFFER" | "UINT8ARRAY";
export type FormatType = "TEXT" | FormatNoTextType;

jsSHA provides specific option interfaces for SHAKE, cSHAKE, and KMAC algorithms. Most interfaces support an optional encoding property to handle text-based inputs.

// SHAKE Options
export interface SHAKEOptionsNoEncodingType {
  numRounds?: number;
}

// cSHAKE Options
export interface CSHAKEOptionsNoEncodingType {
  customization?: GenericInputType;
  funcName?: GenericInputType;
}

// KMAC Options
export interface KMACOptionsNoEncodingType {
  kmacKey: GenericInputType;
  customization?: GenericInputType;
}