// import * from '@noble/ciphers'; // Error: use sub-imports, to ensure small app sizeimport { xchacha20poly1305 } from '@noble/ciphers/chacha.js';import { randomBytes } from '@noble/ciphers/utils.js';const key = randomBytes(32);const nonce = randomBytes(24);const data = new TextEncoder().encode('hello noble');const ciphertext = xchacha20poly1305(key, nonce).encrypt(data);
import { xchacha20poly1305 } from '@noble/ciphers/chacha.js';import { hexToBytes, managedNonce } from '@noble/ciphers/utils.js';const key = hexToBytes('fa686bfdffd3758f6377abbc23bf3d9bdc1a0dda4a6e7f8dbdd579fa1ff6d7e1');const chacha = managedNonce(xchacha20poly1305)(key); // manages nonces for youconst data = new TextEncoder().encode('hello noble');const ciphertext = chacha.encrypt(data);const data_ = chacha.decrypt(ciphertext);
Reuse array for input and output
To avoid additional allocations, Uint8Array can be reused
between encryption and decryption calls.
[!NOTE]
Some ciphers don't support unaligned (byteOffset % 4 !== 0) Uint8Array as
destination. It can decrease performance, making the optimization pointless.
import { chacha20poly1305 } from '@noble/ciphers/chacha.js';import { randomBytes } from '@noble/ciphers/utils.js';const key = randomBytes(32);const nonce = randomBytes(12);const chacha = chacha20poly1305(key, nonce);const input = new TextEncoder().encode('hello noble'); // length == 12const inputLength = input.length;const tagLength = 16;const buf = new Uint8Array(inputLength + tagLength);const start = buf.subarray(0, inputLength);start.set(input); // copy input to bufchacha.encrypt(start, buf); // encrypt into `buf`chacha.decrypt(buf, start); // decrypt into `start`
xsalsa20poly1305 also supports this, but requires 32 additional bytes for encryption / decryption,
due to its inner workings.
Randomness generation
We provide userspace CSPRNG (cryptographically secure pseudorandom number generator).
It's best to limit their usage to non-production, non-critical cases: for example, test-only usage.
ChaCha-based CSPRNG does not have a specification, which makes it less secure.
The AES factories implement the no-derivation-function CTR_DRBG construction for AES-128 and
AES-256 only; derivation-function mode and an AES-192 factory are not provided.
It is not safe to convert password into Uint8Array.
Instead, KDF stretching function like PBKDF2 / Scrypt / Argon2id
should be applied to convert password to AES key.
Make sure to use salt (app-specific secret) in addition to password.
npm install @noble/hashes
import { xchacha20poly1305 } from '@noble/ciphers/chacha.js';import { managedNonce } from '@noble/ciphers/utils.js';import { scrypt } from '@noble/hashes/scrypt.js';// Convert password into 32-byte key using scryptconst PASSWORD = 'correct-horse-battery-staple';const APP_SPECIFIC_SECRET = 'salt-12345678-secret';const SECURITY_LEVEL = 2 ** 20; // requires 1GB of RAM to calculate// sync, but scryptAsync is also availableconst key = scrypt(PASSWORD, APP_SPECIFIC_SECRET, { N: SECURITY_LEVEL, r: 8, p: 1, dkLen: 32, maxmem: 2 ** 30 + 4096,});// Use random, managed nonceconst chacha = managedNonce(xchacha20poly1305)(key);const data = new TextEncoder().encode('hello noble');const ciphertext = chacha.encrypt(data);const data_ = chacha.decrypt(ciphertext);
We suggest to use XChaCha20-Poly1305 because it's very fast and allows random nonces.
AES-GCM-SIV is also a good idea, because it provides resistance against nonce reuse.
AES-GCM is a good option when those two are not available.
How to encrypt properly
Use unpredictable key with enough entropy
Random key must be using cryptographically secure random number generator (CSPRNG), not Math.random etc.
Non-random key generated from KDF is fine
Re-using key is fine, but be aware of rules for cryptographic key wear-out and encryption limits
Use new nonce every time and don't repeat it
Nonce (aka initialization vector / IV) must never repeat for the same key:
an attacker can XOR two ciphertexts encrypted under a repeating (key, nonce) pair
and break encryption
chacha and salsa20 are fine for sequential counters that never repeat: 01, 02...
But it's not always possible to store the current counter value:
e.g. in decentralized, unsyncable systems
Random nonces are risky for 96-bit / 12-byte nonces of ChaCha20 and AES-GCM:
chance of collision is too high. It's even higher for 64-bit nonces,
which GCM allows - don't use them
To safely use random nonces, utilize XSalsa20, XChaCha or AES-SIV:
192-bit nonces minimize the chance of collision.
When eXtended-nonce algorithms are not available, rotate keys often:
hkdf would work great for this case
AES-GCM should use 12-byte nonces: smaller nonces are security risk
Flipping bits or ciphertext substitution won't be detected in unauthenticated ciphers
Polynomial MACs are not perfect for every situation:
they lack Random Key Robustness: the MAC can be forged, and can't
be used in PAKE schemes. See
invisible salamanders attack.
To combat salamanders, hash(key) can be included in ciphertext,
however, this would violate ciphertext indistinguishability:
an attacker would know which key was used - so HKDF(key, i)
could be used instead.
Don't re-use keys between different protocols
For example, using ECDH key in AES can be bad
Use hkdf or, at least, a hash function to create sub-key instead
Encryption limits
A "protected message" would mean a probability of 2**-50 that a passive attacker
successfully distinguishes the ciphertext outputs of the AEAD scheme from the outputs
of a random function.
Max message size:
AES-GCM: ~68GB, 2**36-256
Salsa, ChaCha, XSalsa, XChaCha: ~256GB, 2**38-64
Max amount of protected messages, under same key:
AES-GCM: 2**32.5
Salsa, ChaCha: 2**46, but only integrity (MAC) is affected, not confidentiality (encryption)
XSalsa, XChaCha: 2**72
Max amount of protected messages, across all keys:
AES-GCM: 2**69/B where B is max blocks encrypted by a key. Meaning
2**59 for 1KB, 2**49 for 1MB, 2**39 for 1GB
Salsa, ChaCha, XSalsa, XChaCha: 2**100
Max amount of protected messages, under same key, using random nonce:
Relevant for 12-byte nonces with managedNonce: AES-GCM, ChaCha
2**23 (8M) messages for 2**-50 chance, 2**32.5 (4B) for 2**-32.5 chance
We've started regular AI-assisted self-audits in Apr 2026.
It is tested against property-based, cross-library and Wycheproof vectors,
and is being fuzzed in the separate repo.
If you see anything unusual: investigate and report.
Constant-timeness
We're targeting 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.
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, fast-check and typescript are used for code quality / test generation / ts compilation
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
utilize Grover's algorithm to break ciphers in 2^(n/2) operations, instead of 2^n.
This means AES128 should be replaced with AES256. Salsa and ChaCha are already safe.
Benchmarks measured on Apple M4.
If you need truly exemplar performance, switch to awasm-noble.
# 64Bxsalsa20poly1305 1470 nschacha20poly1305 1742 nsxchacha20poly1305 2306 nsaes-gcm-256 4605 nsaes-gcm-siv-256 5846 nsaes-siv-256 6772 ns## Unauthenticated encryptionchacha20 468 nsaes-cbc-256 1019 nsaes-ctr-256 953 ns## Random number generatorrngChacha8 479 ns# 1MBxsalsa20poly1305 x 341 mib/secchacha20poly1305 x 336 mib/secxchacha20poly1305 x 340 mib/secaes-gcm-256 x 94.8 mib/secaes-gcm-siv-256 x 91.4 mib/secaes-siv-256 x 78.7 mib/sec## Unauthenticated encryptionchacha20 x 808 mib/secaes-cbc-256 x 117 mib/secaes-ctr-256 x 130 mib/sec## Random number generatorrngChacha8 x 1.49 gib/sec## Wrapper over built-in webcryptowebcrypto ctr-256 x 6.91 gib/secwebcrypto cbc-256 x 1.87 gib/secwebcrypto gcm-256 x 5.67 gib/sec
The package is now ESM-only. ESM can finally be loaded from common.js on node v20.19+
.js extension must be used for all modules
Old: @noble/ciphers/aes
New: @noble/ciphers/aes.js
This simplifies working in browsers natively without transpilers
webcrypto: move randomBytes and managedNonce to utils.js
ghash, poly1305, polyval: only allow Uint8Array as hash inputs, prohibit string
utils: new abytes; remove ahash, toBytes
Remove modules _assert (use utils), _micro and crypto (use webcrypto)
Bump TS compilation target from es2020 to es2022
Massively improve error messages, make them more descriptive
Contributing & testing
npm install && npm run build && npm test will build the code and run tests.
Slow, multi-hour large-input tests are available separately: npm run test:slow.
See paulmillr.com/noble for useful resources, articles,
documentation and demos related to the library.