noble-ciphers

The noble-ciphers library has undergone multiple audits to ensure security:

• Version 2.2.0 (Apr 2026): Self-audited by the maintainers. Scope: everything.
• Version 1.0.0 (Sep 2024): Independently audited by cure53. Scope: everything.

Security Considerations

• Constant-timeness: The library targets algorithmic constant time. However, due to the nature of JavaScript (JIT compilers and Garbage Collection), absolute constant-time resistance is difficult to achieve in a scripting language. For absolute security requirements, use low-level languages/libraries instead of JS.
• AES Implementation: The library uses T-tables for AES to maintain performance, which can leak access timings. This is a common trade-off also seen in OpenSSL and Go.
• Randomness: The library relies on the built-in crypto.getRandomValues (CSPRNG).
• Quantum Resistance: To protect against Grover's algorithm, it is recommended to use AES-256 instead of AES-128. Salsa and ChaCha are considered safe.

A nonce (Initialization Vector) must be unique for every encryption performed with the same key. If a (key, nonce) pair is repeated, the encryption can be broken.

Strategies for Nonce Uniqueness

1. Counters: Increment a value (e.g., 0, 1, 2...) for each message. This is safe for chacha20 and salsa20 but difficult in decentralized or unsynchronized systems where state cannot be easily stored.
2. Random Nonces: Generate a random value for each encryption.
   • Risk: Small nonces (like the 96-bit/12-byte nonces used in AES-GCM and ChaCha20) have a high collision probability. For example, using random 12-byte nonces with AES-GCM limits you to approximately 2**23 (8 million) messages before the chance of a collision reaches a significant level.
   • Solution: Use XChaCha or XSalsa20, which use 192-bit nonces, making random generation safe.

Summary of Nonce Safety

To ensure cryptographic security when using noble-ciphers, follow these best practices:

1. Key Management

• Entropy: Use unpredictable keys with sufficient entropy. Keys must be generated using a Cryptographically Secure Random Number Generator (CSPRNG), not Math.random().
• Derivation: Non-random keys generated via a Key Derivation Function (KDF) are acceptable.
• Isolation: Do not re-use keys across different protocols (e.g., do not use an ECDH key directly in AES). Use hkdf or a hash function to derive sub-keys for specific purposes.

2. Nonce Management

• Uniqueness: Use a new nonce for every encryption operation with the same key. Repeating a (key, nonce) pair allows attackers to decrypt data.
• Counter vs. Random:
  • Counters: Safe for chacha20 and salsa20 if they never repeat (e.g., 01, 02...).
  • Random Nonces: Use xchacha or xsalsa20 for random nonces, as their 192-bit nonce length minimizes collision risks. Avoid using random 96-bit (12-byte) nonces with AES-GCM or ChaCha20 for large numbers of messages due to collision probability.

3. Use Authenticated Encryption (AEAD)

• Recommended: chacha20poly1305, GCM, GCM-SIV, ChaCha+HMAC, CTR+HMAC, CBC+HMAC.
• Avoid: chacha20, raw CTR, or raw CBC, as these do not detect ciphertext tampering.

Never convert a password directly into a Uint8Array for use as a key. Instead, use a Key Derivation Function (KDF) like scrypt (from @noble/hashes) to stretch the password into a high-entropy key. Always use a salt (an application-specific secret) during this process.

import { xchacha20poly1305 } from '@noble/ciphers/chacha.js';
import { managedNonce } from '@noble/ciphers/utils.js';
import { scrypt } from '@noble/hashes/scrypt.js';

const PASSWORD = 'correct-horse-battery-staple';
const APP_SPECIFIC_SECRET = 'salt-12345678-secret';
const SECURITY_LEVEL = 2 ** 20; // requires 1GB of RAM to calculate

// Convert password into 32-byte key using scrypt
const key = scrypt(PASSWORD, APP_SPECIFIC_SECRET, {
  N: SECURITY_LEVEL,
  r: 8,
  p: 1,
  dkLen: 32,
  maxmem: 2 ** 30 + 4096,
});

// Use random, managed nonce
const chacha = managedNonce(xchacha20poly1305)(key);
const data = new TextEncoder().encode('hello noble');
const ciphertext = chacha.encrypt(data);
const data_ = chacha.decrypt(ciphertext);

To optimize performance and avoid extra memory allocations, you can pass existing Uint8Array buffers to encrypt and decrypt.

Note: Some ciphers may not support unaligned Uint8Arrays (where byteOffset % 4 !== 0) as destination buffers, which can negate performance benefits.

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');
const inputLength = input.length;
const tagLength = 16;

const buf = new Uint8Array(inputLength + tagLength);
const start = buf.subarray(0, inputLength);
start.set(input); // copy input to buf

// Encrypt into `buf` using `start` as input
chacha.encrypt(start, buf); 
// Decrypt from `buf` into `start`
chacha.decrypt(buf, start);