🪶 4.8KB (gzipped) - 10-25x smaller than similar libraries
The module is a sister project of noble-curves.
Use noble-secp256k1 if you need smaller attack surface & better auditability.
Switch to noble-curves (drop-in) if you need features like MSM, DER encoding, custom point precomputes.
Only async methods are available by default, to keep the library dependency-free.
To enable sync methods:
npm install @noble/hashes
import * as secp from '@noble/secp256k1';import { hmac } from '@noble/hashes/hmac.js';import { sha256 } from '@noble/hashes/sha2.js';secp.hashes.hmacSha256 = (key, msg) => hmac(sha256, key, msg);secp.hashes.sha256 = sha256;
React Native: polyfill getRandomValues and sha256
React Native does not provide secure getRandomValues by default.
This can't be securely polyfilled from our end, so one will need a RN-specific compile-time dep.
import 'react-native-get-random-values';import * as secp from '@noble/secp256k1';import { hmac } from '@noble/hashes/hmac.js';import { sha256 } from '@noble/hashes/sha2.js';secp.hashes.hmacSha256 = (key, msg) => hmac(sha256, key, msg);secp.hashes.sha256 = sha256;secp.hashes.hmacSha256Async = async (key, msg) => hmac(sha256, key, msg);secp.hashes.sha256Async = async (msg) => sha256(msg);
API
There are 4 main methods, which accept Uint8Array-s:
keygen()
getPublicKey(secretKey)
sign(messageHash, secretKey) and signAsync(messageHash, secretKey)
verify(signature, messageHash, publicKey) and verifyAsync(signature, messageHash, publicKey)
keygen
import * as secp from '@noble/secp256k1';(async () => { const keys = secp.keygen(); const { secretKey, publicKey } = keys;})();
Message will be hashed with sha256. If you want to use a different hash function,
make sure to use { prehash: false }.
extraEntropy: true enables hedged signatures. They incorporate
extra randomness into RFC6979 (described in section 3.6),
to provide additional protection against fault attacks.
Check out blog post Deterministic signatures are not your friends.
Even if their RNG is broken, they will fall back to determinism.
Default behavior lowS: true prohibits signatures which have (sig.s >= CURVE.n/2n) and is compatible with BTC/ETH. Setting lowS: false allows to create malleable signatures, which is default openssl behavior. Non-malleable signatures can still be successfully verified in openssl.
verify
import * as secp from '@noble/secp256k1';import { hmac } from '@noble/hashes/hmac.js';import { sha256 } from '@noble/hashes/sha2.js';import { keccak_256 } from '@noble/hashes/sha3.js';secp.hashes.hmacSha256 = (key, msg) => hmac(sha256, key, msg);secp.hashes.sha256 = sha256;const { secretKey, publicKey } = secp.keygen();const msg = new TextEncoder().encode('hello noble');const sig = secp.sign(msg, secretKey);const isValid = secp.verify(sig, msg, publicKey);const sigH = secp.sign(keccak_256(msg), secretKey, { prehash: false });
Verifies ECDSA signature.
Message will be hashed with sha256. If you want to use a different hash function,
make sure to use { prehash: false }.
Default behavior lowS: true prohibits malleable signatures which have (sig.s >= CURVE.n/2n) and
is compatible with BTC / ETH.
Setting lowS: false allows to create signatures, which is default openssl behavior.
getSharedSecret
import * as secp from '@noble/secp256k1';const alice = secp.keygen();const bob = secp.keygen();const shared33b = secp.getSharedSecret(alice.secretKey, bob.publicKey);const shared65b = secp.getSharedSecret(bob.secretKey, alice.publicKey, false);const sharedPoint = secp.Point.fromBytes(bob.publicKey).multiply( secp.etc.secretKeyToScalar(alice.secretKey));
Computes ECDH (Elliptic Curve Diffie-Hellman) shared secret between
key A and different key B.
We cross-test against sister project noble-curves, which was audited and provides improved security.
The current version has not been independently audited. It is a rewrite of v1, which has been audited by cure53 in Apr 2021:
PDF (funded by Umbra.cash & community).
We're targetting algorithmic constant time. JIT-compiler and Garbage Collector make "constant time"
extremely hard to achieve timing attack resistance
in a scripting language. Which means any other JS library can't have
constant-timeness. Even statically typed Rust, a language without GC,
makes it harder to achieve constant-time
for some cases. If your goal is absolute security, don't use any JS lib — including bindings to native ones.
Use low-level libraries & languages.
Supply chain security
Commits are signed with PGP keys to prevent forgery. Be sure to verify the commit signatures
Releases are made transparently through token-less GitHub CI and Trusted Publishing. Be sure to verify the provenance logs for authenticity.
Rare releasing is practiced to minimize the need for re-audits by end-users.
Dependencies are minimized and strictly pinned to reduce supply-chain risk.
We use as few dependencies as possible.
Version ranges are locked, and changes are checked with npm-diff.
Dev dependencies are excluded from end-user installs; they’re only used for development and build steps.
For this package, there are 0 dependencies; and a few dev dependencies:
jsbt is used for benchmarking / testing / build tooling and developed by the same author
prettier and typescript are used for code quality / ts compilation; @paulmillr/jsbt for property-based tests
Randomness
We rely on the built-in
crypto.getRandomValues,
which is considered a cryptographically secure PRNG.
Browsers have had weaknesses in the past - and could again - but implementing a userspace CSPRNG is even worse, as there’s no reliable userspace source of high-quality entropy.
Quantum computers
Cryptographically relevant quantum computer, if built, will allow to
break elliptic curve cryptography (both ECDSA / EdDSA & ECDH) using Shor's algorithm.
Consider switching to newer / hybrid algorithms, such as SPHINCS+. They are available in
noble-post-quantum.
NIST prohibits classical cryptography (RSA, DSA, ECDSA, ECDH) after 2035. Australian ASD prohibits it after 2030.
Upgrading
v2 to v3
v3 brings the package closer to noble-curves v2.
Add Schnorr signatures
Most methods now expect Uint8Array, string hex inputs are prohibited
Add keygen, keygenAsync method
sign, verify: Switch to prehashed messages. Instead of
messageHash, the methods now expect unhashed message.
To bring back old behavior, use option {prehash: false}
sign, verify: Switch to Uint8Array signatures (format: 'compact') by default.
verify: der format must be explicitly specified in {format: 'der'}.
This reduces malleability
verify: prohibit Signature-instance signature. User must now always do
signature.toBytes()
Node v20.19 is now the minimum required version
Various small changes for types
etc: hashes are now set in hashes object. Also sha256 needs to be set now for prehash: true: