@noble/hashes
Advanced tools
Audited & minimal 0-dependency JS implementation of SHA2, SHA3, RIPEMD, BLAKE2/3, HMAC, HKDF, PBKDF2, Scrypt
The @noble/hashes npm package provides a collection of cryptographic hash functions implemented in pure JavaScript with a focus on security and performance. It is part of the noble family of packages, which are designed to be secure, efficient, and easy to use.
SHA-256 Hashing
This feature allows you to compute the SHA-256 hash of an input. The code sample demonstrates how to hash a Uint8Array of bytes and print the resulting hash as a hex string.
"use strict";
const { sha256 } = require('@noble/hashes/sha256');
const hash = sha256(new Uint8Array([1, 2, 3]));
console.log(Buffer.from(hash).toString('hex'));SHA-1 Hashing
This feature enables SHA-1 hashing. The code sample shows how to hash a Uint8Array and output the hash in hexadecimal format.
"use strict";
const { sha1 } = require('@noble/hashes/sha1');
const hash = sha1(new Uint8Array([1, 2, 3]));
console.log(Buffer.from(hash).toString('hex'));RIPEMD-160 Hashing
This feature provides RIPEMD-160 hashing capability. The code sample illustrates hashing a byte array and converting the hash to a hex string.
"use strict";
const { ripemd160 } = require('@noble/hashes/ripemd160');
const hash = ripemd160(new Uint8Array([1, 2, 3]));
console.log(Buffer.from(hash).toString('hex'));HMAC
This feature allows for the creation of HMACs (Hash-based Message Authentication Codes) using a specified hash function. The code sample demonstrates creating an HMAC with SHA-256.
"use strict";
const { hmac } = require('@noble/hashes/hmac');
const { sha256 } = require('@noble/hashes/sha256');
const key = new Uint8Array([1, 2, 3, 4, 5]);
const message = new Uint8Array([6, 7, 8, 9, 0]);
const signature = hmac(sha256, key, message);
console.log(Buffer.from(signature).toString('hex'));Crypto-js is a popular package that provides a variety of cryptographic algorithms including hash functions, HMAC, and encryption. It is similar to @noble/hashes but has a broader scope, including encryption and decryption methods.
Hash.js is a lightweight library of hash functions that includes implementations of SHA-1, SHA-256, and RIPEMD. It is similar to @noble/hashes in providing hash functions but is not as focused on security and performance.
Sha.js is a simple module that only implements SHA hash functions. It is similar to @noble/hashes in providing SHA hashing but does not include other hash functions like RIPEMD-160 or HMAC capabilities.
Audited & minimal JS implementation of SHA2, SHA3, RIPEMD, BLAKE2/3, HMAC, HKDF, PBKDF2 & Scrypt.
N: 2**22, while other implementations are limited to 2**20The library's initial development was funded by Ethereum Foundation.
noble-crypto — high-security, easily auditable set of contained cryptographic libraries and tools.
Use NPM in node.js / browser, or include single file from GitHub's releases page:
npm install @noble/hashes
The library does not have an entry point. It allows you to select specific primitives and drop everything else. If you only want to use sha256, just use the library with rollup or other bundlers. This is done to make your bundles tiny.
// Common.js and ECMAScript Modules (ESM)
import { sha256 } from '@noble/hashes/sha256';
console.log(sha256(new Uint8Array([1, 2, 3])));
// Uint8Array(32) [3, 144, 88, 198, 242, 192, 203, 73, ...]
// you could also pass strings that will be UTF8-encoded to Uint8Array
console.log(sha256('abc'))); // == sha256(new TextEncoder().encode('abc'))
// sha384 is here, because it uses same internals as sha512
const { sha512, sha512_256, sha384 } = require('@noble/hashes/sha512');
// prettier-ignore
const {
sha3_224, sha3_256, sha3_384, sha3_512,
keccak_224, keccak_256, keccak_384, keccak_512,
shake128, shake256
} = require('@noble/hashes/sha3');
// prettier-ignore
const {
cshake128, cshake256, kmac128, kmac256,
k12, m14,
tuplehash256, parallelhash256, keccakprg
} = require('@noble/hashes/sha3-addons');
const { ripemd160 } = require('@noble/hashes/ripemd160');
const { blake3 } = require('@noble/hashes/blake3');
const { blake2b } = require('@noble/hashes/blake2b');
const { blake2s } = require('@noble/hashes/blake2s');
const { hmac } = require('@noble/hashes/hmac');
const { hkdf } = require('@noble/hashes/hkdf');
const { pbkdf2, pbkdf2Async } = require('@noble/hashes/pbkdf2');
const { scrypt, scryptAsync } = require('@noble/hashes/scrypt');
// legacy, still relevant for HMAC
const { sha1 } = require('@noble/hashes/sha1');
// small utility method that converts bytes to hex
const { bytesToHex as toHex } = require('@noble/hashes/utils');
console.log(toHex(sha256('abc')));
// ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
All hash functions:
Uint8Array.Uint8Arraystring, which is automatically converted to Uint8Array
via utf8 encoding (not hex)function hash(message: Uint8Array | string): Uint8Array;
hash(new Uint8Array([1, 3]));
hash('string') == hash(new TextEncoder().encode('string'));
All hash functions can be constructed via hash.create() method:
Hash subclass instance, which has update() and digest() methodsdigest() finalizes the hash and makes it no longer usablehash
.create()
.update(new Uint8Array([1, 3]))
.digest();
Some hash functions can also receive options object, which can be either passed as a:
blake3('abc', { key: 'd', dkLen: 32 })blake3.create({ context: 'e', dkLen: 32 })import { sha256 } from '@noble/hashes/sha256';
const h1a = sha256('abc');
const h1b = sha256
.create()
.update(Uint8Array.from([1, 2, 3]))
.digest();
import { sha512 } from '@noble/hashes/sha512';
const h2a = sha512('abc');
const h2b = sha512
.create()
.update(Uint8Array.from([1, 2, 3]))
.digest();
// SHA512/256 variant
import { sha512_256 } from '@noble/hashes/sha512';
const h3a = sha512_256('abc');
const h3b = sha512_256
.create()
.update(Uint8Array.from([1, 2, 3]))
.digest();
// SHA384
import { sha384 } from '@noble/hashes/sha512';
const h4a = sha384('abc');
const h4b = sha384
.create()
.update(Uint8Array.from([1, 2, 3]))
.digest();
See RFC 4634 and the paper on SHA512/256.
import {
sha3_224,
sha3_256,
sha3_384,
sha3_512,
keccak_224,
keccak_256,
keccak_384,
keccak_512,
shake128,
shake256,
} from '@noble/hashes/sha3';
const h5a = sha3_256('abc');
const h5b = sha3_256
.create()
.update(Uint8Array.from([1, 2, 3]))
.digest();
const h6a = keccak_256('abc');
const h7a = shake128('abc', { dkLen: 512 });
const h7b = shake256('abc', { dkLen: 512 });
See (FIPS PUB 202, Website).
Check out the differences between SHA-3 and Keccak
import {
cshake128,
cshake256,
kmac128,
kmac256,
k12,
m14,
tuplehash128,
tuplehash256,
parallelhash128,
parallelhash256,
keccakprg,
} from '@noble/hashes/sha3-addons';
const h7c = cshake128('abc', { personalization: 'def' });
const h7d = cshake256('abc', { personalization: 'def' });
const h7e = kmac128('key', 'message');
const h7f = kmac256('key', 'message');
const h7h = k12('abc');
const h7g = m14('abc');
const h7i = tuplehash128(['ab', 'c']); // tuplehash(['ab', 'c']) !== tuplehash(['a', 'bc']) !== tuplehash(['abc'])
// Same as k12/blake3, but without reduced number of rounds. Doesn't speedup anything due lack of SIMD and threading,
// added for compatibility.
const h7j = parallelhash128('abc', { blockLen: 8 });
// pseudo-random generator, first argument is capacity. XKCP recommends 254 bits capacity for 128-bit security strength.
// * with a capacity of 254 bits.
const p = keccakprg(254);
p.feed('test');
const rand1b = p.fetch(1);
import { ripemd160 } from '@noble/hashes/ripemd160';
// function ripemd160(data: Uint8Array): Uint8Array;
const hash8 = ripemd160('abc');
const hash9 = ripemd160()
.create()
.update(Uint8Array.from([1, 2, 3]))
.digest();
import { blake2b } from '@noble/hashes/blake2b';
import { blake2s } from '@noble/hashes/blake2s';
const h10a = blake2s('abc');
const b2params = { key: new Uint8Array([1]), personalization: t, salt: t, dkLen: 32 };
const h10b = blake2s('abc', b2params);
const h10c = blake2s
.create(b2params)
.update(Uint8Array.from([1, 2, 3]))
.digest();
import { blake3 } from '@noble/hashes/blake3';
// All params are optional
const h11 = blake3('abc', { dkLen: 256, key: 'def', context: 'fji' });
SHA1 was cryptographically broken, however, it was not broken for cases like HMAC.
See RFC4226 B.2.
Don't use it for a new protocol.
import { sha1 } from '@noble/hashes/sha1';
const h12 = sha1('def');
import { hmac } from '@noble/hashes/hmac';
import { sha256 } from '@noble/hashes/sha256';
const mac1 = hmac(sha256, 'key', 'message');
const mac2 = hmac.create(sha256, Uint8Array.from([1, 2, 3])).update(Uint8Array.from([4, 5, 6])).digest();
Matches RFC 2104.
import { hkdf } from '@noble/hashes/hkdf';
import { sha256 } from '@noble/hashes/sha256';
import { randomBytes } from '@noble/hashes/utils';
const inputKey = randomBytes(32);
const salt = randomBytes(32);
const info = 'abc';
const dkLen = 32;
const hk1 = hkdf(sha256, inputKey, salt, info, dkLen);
// == same as
import * as hkdf from '@noble/hashes/hkdf';
import { sha256 } from '@noble/hashes/sha256';
const prk = hkdf.extract(sha256, inputKey, salt);
const hk2 = hkdf.expand(sha256, prk, info, dkLen);
Matches RFC 5869.
import { pbkdf2, pbkdf2Async } from '@noble/hashes/pbkdf2';
import { sha256 } from '@noble/hashes/sha256';
const pbkey1 = pbkdf2(sha256, 'password', 'salt', { c: 32, dkLen: 32 });
const pbkey2 = await pbkdf2Async(sha256, 'password', 'salt', { c: 32, dkLen: 32 });
const pbkey3 = await pbkdf2Async(sha256, Uint8Array.from([1, 2, 3]), Uint8Array.from([4, 5, 6]), {
c: 32,
dkLen: 32,
});
Matches RFC 2898.
import { scrypt, scryptAsync } from '@noble/hashes/scrypt';
const scr1 = scrypt('password', 'salt', { N: 2 ** 16, r: 8, p: 1, dkLen: 32 });
const scr2 = await scryptAsync('password', 'salt', { N: 2 ** 16, r: 8, p: 1, dkLen: 32 });
const scr3 = await scryptAsync(Uint8Array.from([1, 2, 3]), Uint8Array.from([4, 5, 6]), {
N: 2 ** 22,
r: 8,
p: 1,
dkLen: 32,
onProgress(percentage) {
console.log('progress', percentage);
},
maxmem: 2 ** 32 + 128 * 8 * 1, // N * r * p * 128 + (128*r*p)
});
N, r, p are work factors. To understand them, see the blog post.dkLen is the length of output bytes2**10 to 2**22 and {r: 8, p: 1, dkLen: 32}onProgress can be used with async version of the function to report progress to a user.Memory usage of scrypt is calculated with the formula N * r * p * 128 + (128 * r * p), which means
{N: 2 ** 22, r: 8, p: 1} will use 4GB + 1KB of memory. To prevent DoS, we limit scrypt to 1GB + 1KB of RAM used,
which corresponds to {N: 2 ** 20, r: 8, p: 1}. If you want to use higher values, increase maxmem using the formula above.
Note: noble supports 2**22 (4GB RAM) which is the highest amount amongst JS libs. Many other implementations don't support it.
We cannot support 2**23, because there is a limitation in JS engines that makes allocating
arrays bigger than 4GB impossible, but we're looking into other possible solutions.
A tiny stretched KDF for various applications like AES key-gen. Takes >= 2 seconds to execute.
Takes following params:
username - username, email, or identifier, min: 8 characters, should have enough entropypassword - min: 8 characters, should have enough entropyProduces ESKDF instance that has deriveChildKey(protocol, accountId[, options]) function.
protocol - 3-15 character protocol nameaccountId - numeric identifier of accountoptions - keyLength: 32 with specified key length (default is 32),
or modulus: 2n ** 221n - 17n with specified modulus. It will fetch modulus + 64 bits of
data, execute modular division. The result will have negligible bias as per FIPS 186 B.4.1.
Can be used to generate, for example, elliptic curve keys.Takes username and password, then takes protocol name and account id.
import { eskdf } from '@noble/hashes/eskdf';
const kdf = await eskdf('example@university', 'beginning-new-example');
console.log(kdf.fingerprint);
const key = kdf.deriveChildKey('aes', 0);
const key = kdf.deriveChildKey('aes', 0, { keyLength: 16 });
const ecc = kdf.deriveChildKey('ecc', 0, { modulus: 2n ** 252n - 27742317777372353535851937790883648493n })
kdf.expire();
import { bytesToHex as toHex, randomBytes } from '@noble/hashes/scrypt';
console.log(toHex(randomBytes(32)));
bytesToHex will convert Uint8Array to a hex stringrandomBytes(bytes) will produce cryptographically secure random Uint8Array of length bytesNoble is production-ready.
blake3, sha3-addons and sha1 have not been audited. See changes since audit.scrypt(password, salt) where password and salt are stringsawait anything() will always write all internal variables (including numbers) to memory. With async functions / Promises there are no guarantees when the code chunk would be executed. Which means attacker can have plenty of time to read data from memoryWe consider infrastructure attacks like rogue NPM modules very important; that's why it's crucial to minimize the amount of 3rd-party dependencies & native bindings. If your app uses 500 dependencies, any dep could get hacked and you'll be downloading malware with every npm install. Our goal is to minimize this attack vector.
Benchmarks measured on Apple M1 with macOS 12.
Note that PBKDF2 and Scrypt are tested with extremely high work factor.
To run benchmarks, execute npm run bench:install and then npm run bench
SHA256 32B x 1,126,126 ops/sec @ 888ns/op
SHA384 32B x 463,606 ops/sec @ 2μs/op
SHA512 32B x 467,945 ops/sec @ 2μs/op
SHA3-256, keccak256, shake256 32B x 192,049 ops/sec @ 5μs/op
Kangaroo12 32B x 318,066 ops/sec @ 3μs/op
Marsupilami14 32B x 283,929 ops/sec @ 3μs/op
BLAKE2b 32B x 352,112 ops/sec @ 2μs/op
BLAKE2s 32B x 511,770 ops/sec @ 1μs/op
BLAKE3 32B x 582,072 ops/sec @ 1μs/op
RIPEMD160 32B x 1,230,012 ops/sec @ 813ns/op
HMAC-SHA256 32B x 238,663 ops/sec @ 4μs/op
HKDF-SHA256 32B x 108,377 ops/sec @ 9μs/op
PBKDF2-HMAC-SHA256 262144 x 3 ops/sec @ 326ms/op
PBKDF2-HMAC-SHA512 262144 x 1 ops/sec @ 970ms/op
Scrypt r: 8, p: 1, n: 262144 x 1 ops/sec @ 616ms/op
Compare to native node.js implementation that uses C bindings instead of pure-js code:
SHA256 32B native x 1,164,144 ops/sec @ 859ns/op
SHA384 32B native x 938,086 ops/sec @ 1μs/op
SHA512 32B native x 946,969 ops/sec @ 1μs/op
SHA3 32B native x 879,507 ops/sec @ 1μs/op
keccak, k12, m14 are not implemented
BLAKE2b 32B native x 879,507 ops/sec @ 1μs/op
BLAKE2s 32B native x 977,517 ops/sec @ 1μs/op
BLAKE3 is not implemented
RIPEMD160 32B native x 913,242 ops/sec @ 1μs/op
HMAC-SHA256 32B native x 755,287 ops/sec @ 1μs/op
HKDF-SHA256 32B native x 207,856 ops/sec @ 4μs/op
PBKDF2-HMAC-SHA256 262144 native x 23 ops/sec @ 42ms/op
Scrypt 262144 native x 1 ops/sec @ 564ms/op
Scrypt 262144 scrypt.js x 0 ops/sec @ 1678ms/op
It is possible to make this library 4x+ faster by doing code generation of full loop unrolls. We've decided against it. Reasons:
The current performance is good enough when compared to other projects; SHA256 takes only 900 nanoseconds to run.
npm install to install build dependencies like TypeScriptnpm run build to compile TypeScript codenpm run test will execute all main tests. See our approach to testingnpm run test:dos will test against DoS; by measuring function complexity. Takes ~20 minutesnpm run test:big will execute hashing on 4GB inputs,
scrypt with 1024 different N, r, p combinations, etc. Takes several hours. Using 8-32+ core CPU helps.The MIT License (MIT)
Copyright (c) 2022 Paul Miller (https://paulmillr.com)
See LICENSE file.
FAQs
Audited & minimal 0-dependency JS implementation of SHA, RIPEMD, BLAKE, HMAC, HKDF, PBKDF & Scrypt
We found that @noble/hashes demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Elastic’s return to open source with the AGPL license has been met with skepticism, as many developers see it as a strategic move rather than a genuine effort to restore user trust and freedoms.
Security News
A new "revival hijack" supply chain attack targets deleted Python packages, with an estimated 22K packages at risk. Socket can detect and block hijacked packages that have added malicious code.
Product
We're introducing a new Analytics feature in the Socket dashboard so you can view changes in your organization's and repositories' alerts over time.