A pure JavaScript implementation of the Keccak family of cryptographic hashing algorithms, most notably including Keccak and SHA3.
💡 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 theSHA3
orKeccak
objects instead, which provide the SHA-3 and Keccak hashing algorithms, respectively.
Via npm
:
$ npm install sha3
Via yarn
:
$ yarn add sha3
You can use this library from Node.js, from web browsers, and/or using ES6 imports.
// Standard FIPS 202 SHA-3 implementation
const { SHA3 } = require('sha3');
// The Keccak hash function is also available
const { Keccak } = require('sha3');
// Standard FIPS 202 SHA-3 implementation
import { SHA3 } from 'sha3';
// The Keccak hash function is also available
import { Keccak } from 'sha3';
FIPS-compatible interfaces for the following algorithms:
SHA3
: The SHA3 algorithm.Keccak
: The Keccak algorithm.
💡 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.
import { SHA3 } from 'sha3';
const hash = new SHA3(512);
hash.update('foo');
hash.digest('hex');
import { Keccak } from 'sha3';
const hash = new Keccak(256);
hash.update('foo');
hash.digest('hex');
All hash implementations provided by this library conform to the following API specification.
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 of224
,256
,384
, or512
. Defaults to512
.
// Construct a new Keccak hash of size 256
const hash = new Keccak(256);
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 givendata
, if of typestring
. Defaults to'utf8'
.
💡 See Buffers and Character Encodings for a list of allowed encodings.
const hash = new Keccak(256);
hash.update('hello');
hash.update('we can also chain these').update('together');
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
.
💡 See Buffers and Character Encodings for a list of allowed encodings.
const hash = new Keccak(256);
hash.update('hello');
hash.digest('hex');
// => hash of 'hello' as a hex-encoded string
hash.update('we can keep reading data even after digesting');
hash.digest();
// => hash of everything so far as a Buffer object
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.
const hash = new Keccak(256);
hash.update('hello');
hash.digest();
// => hash of 'hello'
hash.reset();
hash.update('world');
hash.digest();
// => hash of 'world'
Run yarn test
for the full test suite.
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.
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.