What is sha3?
The sha3 npm package provides implementations of the SHA-3 (Secure Hash Algorithm 3) cryptographic hash functions. It allows you to generate hash digests for data, which can be used for data integrity checks, digital signatures, and other cryptographic applications.
What are sha3's main functionalities?
Generate SHA-3 Hash
This feature allows you to generate a SHA-3 hash for a given input string. In this example, a SHA-3 hash with a 256-bit output is generated for the string 'hello world'.
const { SHA3 } = require('sha3');
const hash = new SHA3(256);
hash.update('hello world');
console.log(hash.digest('hex'));
Generate SHAKE128 Hash
This feature allows you to generate a SHAKE128 hash, which is an extendable-output function (XOF) variant of SHA-3. In this example, a SHAKE128 hash is generated for the string 'hello world' with a 128-bit output.
const { SHAKE } = require('sha3');
const hash = new SHAKE(128);
hash.update('hello world');
console.log(hash.digest({ buffer: Buffer.alloc(16) }).toString('hex'));
Generate SHAKE256 Hash
This feature allows you to generate a SHAKE256 hash, another XOF variant of SHA-3. In this example, a SHAKE256 hash is generated for the string 'hello world' with a 256-bit output.
const { SHAKE } = require('sha3');
const hash = new SHAKE(256);
hash.update('hello world');
console.log(hash.digest({ buffer: Buffer.alloc(32) }).toString('hex'));
Other packages similar to sha3
js-sha3
The js-sha3 package provides a fast and simple implementation of SHA-3 hash functions in JavaScript. It supports various SHA-3 hash lengths and SHAKE functions. Compared to sha3, js-sha3 is known for its performance and ease of use.
crypto-js
The crypto-js package is a widely-used library that provides a variety of cryptographic algorithms, including SHA-3. It offers a comprehensive set of features for cryptographic operations beyond just SHA-3, making it a versatile choice for developers.
hash.js
The hash.js package is a cryptographic library that supports multiple hash algorithms, including SHA-3. It is designed to be fast and efficient, and it provides a consistent API for various hash functions. Compared to sha3, hash.js offers a broader range of hash algorithms.
SHA-3 for JavaScript
A pure JavaScript implementation of the Keccak family of cryptographic hashing algorithms, most notably including Keccak and SHA3.
:bulb: Legacy Note: In previous versions of this library, the SHA3Hash
object provided a Keccak hash, not what we
currently know as a SHA-3 hash. For backwards-compatibility, this object is still exported. However, users are encouraged to
switch to using the SHA3
or Keccak
objects instead, which provide the SHA-3 and Keccak hashing algorithms, respectively.
Installation
Via npm
:
$ npm install sha3
Via yarn
:
$ yarn add sha3
Usage
You can use this library from Node.js, from web browsers, and/or using ES6 imports.
Node.js (CommonJS style)
const { SHA3 } = require('sha3');
const { Keccak } = require('sha3');
ES6
import { SHA3 } from 'sha3';
import { Keccak } from 'sha3';
What's in the box
FIPS-compatible interfaces for the following algorithms:
SHA3
: The SHA3 algorithm.Keccak
: The Keccak algorithm.SHAKE
: The SHAKE XOF algorithm.
:bulb: Legacy Note: Savvy inspectors may notice that SHA3Hash
is also provided. Prior to v2.0.0,
this library only implemented an early version of the SHA3 algorithm. Since then, SHA3 has diverged from
Keccak and is using a different padding scheme, but for compatibility, this alias is sticking around
for a bit longer.
Examples
Generating a SHA3-512 hash
import { SHA3 } from 'sha3';
const hash = new SHA3(512);
hash.update('foo');
hash.digest('hex');
Generating a Keccak-256 hash
import { Keccak } from 'sha3';
const hash = new Keccak(256);
hash.update('foo');
hash.digest('hex');
Generating a SHAKE128 hash with 2048 bytes
import { SHAKE } from 'sha3';
const hash = new SHAKE(128);
hash.update('foo');
hash.digest({ buffer: Buffer.alloc(2048), format: 'hex' });
API Reference
All hash implementations provided by this library conform to the following API specification.
#constructor([size=512])
The constructor for each hash (e.g: Keccak
, SHA3
), expects the following parameters:
size
(Number): Optional. The size of the hash to create, in bits. If provided, this must be one of 224
, 256
, 384
, or 512
. Defaults to 512
.
Example
const hash = new Keccak(256);
#update(data, [encoding='utf8'])
Updates the hash content with the given data. Returns the hash object itself.
data
(Buffer|string): Required. The data to read into the hash.encoding
(string): Optional. The encoding of the given data
, if of type string
. Defaults to 'utf8'
.
:bulb: See Buffers and Character Encodings for a list of allowed encodings.
Example
const hash = new Keccak(256);
hash.update('hello');
hash.update('we can also chain these').update('together');
#digest([encoding='binary'])
Digests the hash and returns the result. After calling this function, the hash may continue to receive input.
encoding
(string): Optional. The encoding to use for the returned digest. Defaults to 'binary'
.
If an encoding
is provided and is a value other than 'binary'
, then this function returns a string
.
Otherwise, it returns a Buffer
.
:bulb: See Buffers and Character Encodings for a list of allowed encodings.
Example
const hash = new Keccak(256);
hash.update('hello');
hash.digest('hex');
#digest([options={}])
Digests the hash and returns the result. After calling this function, the hash may continue to receive input.
Options include:
buffer
(Buffer): Optional. A pre-allocated buffer to fill with output bytes. This is how XOF algorithms like SHAKE can be used to obtain an arbitrary number of hash bytes.format
(string): Optional. The encoding to use for the returned digest. Defaults to 'binary'
. If buffer
is also provided, this value will passed directly into Buffer#toString()
on the given buffer.padding
(byte): Optional. Override the padding used to pad the input bytes to the algorithm's block size. Typically this should be omitted, but may be required if building additional cryptographic algorithms on top of this library.
If a format
is provided and is a value other than 'binary'
, then this function returns a string
.
Otherwise, it returns a Buffer
.
Example
const hash = new Keccak(256);
hash.update('hello');
hash.digest({ buffer: Buffer.alloc(32), format: 'hex' });
#reset()
Resets a hash to its initial state.
- All input buffers are cleared from memory.
- The hash object can safely be reused to compute another hash.
Example
const hash = new Keccak(256);
hash.update('hello');
hash.digest();
hash.reset();
hash.update('world');
hash.digest();
Testing
Run yarn test
for the full test suite.
Disclaimer
Cryptographic hashes provide integrity, but do not provide authenticity or confidentiality.
Hash functions are one part of the cryptographic ecosystem, alongside other primitives like ciphers and
MACs. If considering this library for the purpose of protecting passwords, you may actually be looking
for a key derivation function, which can provide much better security guarantees for this use case.
Special Thanks
The following resources were invaluable to this implementation and deserve special thanks
for work well done:
-
Keccak pseudocode: The Keccak team's excellent pseudo-code and technical descriptions.
-
mjosaarinen/tiny_sha3: Markku-Juhani O. Saarinen's compact, legible, and hackable implementation.
-
Phusion: For the initial release and maintenance of this project, and gracious hand-off to Twuni for continued development and maintenance.