Repository files navigation

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

More complete documentation can be found on thejsSHA Wiki but below are commonuse-cases.

Include the desired JavaScript file (sha.js, sha1.js, sha256.js, sha512.js, orsha3.js) in your header:

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

jsSHA is available through NPM and be installed by simply doing

npm install jssha

To use the module, first require it using:

constjsSHA=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 */constjsSHA1=require("jssha/sha1");/* For Node.js versions that don't support subpath exports, you can do the * following instead: */constjsSHA1=require("jssha/dist/sha1");/* Alternatively, you can load it as an ESM (Node.js v13+ or using * --experimental-modules in v12) */importjsSHAfrom"jssha";

Instantiate a newjsSHA 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, orSHAKE256. The input format can be one of HEX, TEXT, B64, BYTES, ARRAYBUFFER, orUINT8ARRAY. You can then stream in input using theupdate object function,calling it multiple times if needed. Finally, simply callgetHash with theoutput type as a parameter (B64, HEX, BYTES, ARRAYBUFFER, or UINT8ARRAY).Example to calculate the SHA-512 of "This is a test":

constshaObj=newjsSHA("SHA-512","TEXT",{encoding:"UTF8"});/* .update() can be chained */shaObj.update("This is").update(" a ");shaObj.update("test");consthash=shaObj.getHash("HEX");

The constructor takes a hashmap as a optional third argument with defaults{"encoding" : "UTF8", "numRounds" : 1}.numRounds controls the number ofhashing iterations/rounds performed andencoding specifies the encoding usedto encode TEXT-type inputs. Validencoding 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 andb64Pad only for "B64" outputs.

Important: SHAKE128 and SHAKE256 requireoutputLen to be in the hashmapwhereoutputLen is the desired output length of the SHAKE algorithm in amultiple of 8 bits.

Instantiate a newjsSHA object similiar to hashing but with the third argumentin the form of{ "hmacKey": { "value": VALUE, "format": FORMAT } }. FORMATtakes the same values as the input format from hashing and the VALUE is theneither astring,ArrayBuffer, orUint8Array. You can stream in the inputusing theupdate object function just like hashing. Finally, get the HMAC bycalling thegetHash function with the output type as its argument. Example tocalculate the SHA-512 HMAC of the string "This is a test" with the key "abc":

constshaObj=newjsSHA("SHA-512","TEXT",{hmacKey:{value:"abc",format:"TEXT"},});shaObj.update("This is a ");shaObj.update("test");consthmac=shaObj.getHash("HEX");

Note: You cannot specifynumRounds with HMAC.

Instantiate a newjsSHA object similiar to HMAC but first argument beingeither "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 isthen either astring,ArrayBuffer, orUint8Array. Per the NISTspecification, bothcustomization andfuncName are optional. You can streamin the input using theupdate object function just like hashing. Finally, getthe hash by calling thegetHash function with the output type and length asarguments. Example to calculate the cSHAKE128 of the string "This is a test"with the customization string "My Tagged Application" and an output size of256-bits.

constshaObj=newjsSHA("CSHAKE128","TEXT",{customization:{value:"My Tagged Application",format:"TEXT"},});shaObj.update("This is a ");shaObj.update("test");constcshake=shaObj.getHash("HEX",{outputLen:256});

Note: You cannot specifynumRounds with cSHAKE.

Important:outputLen is required to be in the hashmap whereoutputLenis the desired output length of the cSHAKE algorithm in a multiple of 8 bits.

Instantiate a newjsSHA object similiar to cSHAKE but first argument beingeither "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 isthen either astring,ArrayBuffer, orUint8Array. Per the NISTspecificationcustomization is optional whereaskmacKey is required. You canstream in the input using theupdate object function just like hashing.Finally, get the hash by calling thegetHash function with the output type andlength as arguments. Example to calculate the KMAC128 of the string "This is atest" with the customization string "My Tagged Application", key "abc", and anoutput size of 256-bits.

constshaObj=newjsSHA("KMAC128","TEXT",{customization:{value:"My Tagged Application",format:"TEXT"},kmacKey:{value:"abc",format:"TEXT"},});shaObj.update("This is a ");shaObj.update("test");constkmac=shaObj.getHash("HEX",{outputLen:256});

Note: You cannot specifynumRounds with KMAC.

Important:outputLen is required to be in the hashmap whereoutputLenis the desired output length of the KMAC algorithm in a multiple of 8 bits.

• dist/sha.js - The minified ECMAScript 3 (ES3) compatibleUniversal ModuleDefinition (UMD) version of the library with support for all hashvariants. Its accompanying source map can be found in dist/sha.js.map and itsTypeScript declarations in dist/sha.d.ts.
• dist/sha.mjs - The minified ECMAScript 2015 (ES6) compatible ESM versionof the library with support for all hash variants. Its accompanying source mapcan be found in dist/sha.mjs.map and its TypeScript declarations indist/sha.d.ts.
• dist/sha1.{js,mjs} - The minified UMD and ESM versions of the library withsupport for only the SHA-1 hash variant. Its accompanying TypeScriptdeclarations can be found in dist/sha1.d.ts.
• dist/sha256.{js,mjs} - The minified UMD and ESM versions of the librarywith support for only the SHA-224 and SHA-256 hash variants. Its accompanyingTypeScript declarations can be found in dist/sha256.d.ts.
• dist/sha512.{js,mjs} - The minified UMD and ESM versions of the librarywith support for only the SHA-384 and SHA-512 hash variants. Its accompanyingTypeScript declarations can be found in dist/sha513.d.ts.
• dist/sha3.{js,mjs} - The minified UMD and ESM versions of the library withsupport for only the SHA3-224, SHA3-256, SHA3-384, SHA3-512, SHAKE128,SHAKE256, cSHAKE128, cSHAKE256, KMAC128, and KMAC256 hash variants. Itsaccompanying TypeScript declarations can be found in dist/sha3.d.ts.

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