@jscrypto/chacha20

Migration Notice

@jscrypto/chacha20 is a legacy standalone package. It remains installable with @jscrypto/core up to 0.9.1, but new integrations should use the component package listed below.

Starting with @jscrypto 0.9.0, the ChaCha20 family components moved into the new component architecture:

• Node / bundlers: use @jscrypto/ciphers
• Browser bundle: use @jscrypto/ciphers/chacha20/browser
• Registry preset: use chacha20Preset from @jscrypto/ciphers/chacha20

This package now declares @jscrypto/core as >=0.7.0 <=0.9.1 for compatibility with transition releases. Prefer the new @jscrypto/ciphers component layout for 0.9.x projects.

ChaCha20 family stream cipher and AEAD components for @jscrypto/core.

This package provides:

• ChaCha20 and XChaCha20 stream ciphers (IETF / extended-nonce layouts)
• ChaCha20-Poly1305 and XChaCha20-Poly1305 AEAD constructions
• chacha20Preset for registry registration

Poly1305 is a MAC, not a mode. This package does not support arbitrary cipher + mac composition such as createCipher({ cipher: 'ChaCha20', mac: 'Poly1305' }). Use the named AEAD constructions instead.

Use ChaCha20-Poly1305 or XChaCha20-Poly1305 for authenticated encryption. Raw ChaCha20 only encrypts bytes and does not detect tampering.

Never reuse a nonce with the same key for ChaCha20-Poly1305 or XChaCha20-Poly1305.

Algorithm primitives come from @noble/ciphers.

Supported Components

| Cipher | Type | Nonce | Authentication | Notes | | --- | --- | --- | --- | --- | | ChaCha20 | Stream cipher | 12 bytes | No | IETF ChaCha20. counter defaults to 0. | | XChaCha20 | Stream cipher | 24 bytes | No | Extended-nonce ChaCha20. counter defaults to 0. | | ChaCha20-Poly1305 | AEAD | 12 bytes | 16-byte tag | Returns ciphertext with the tag appended. | | XChaCha20-Poly1305 | AEAD | 24 bytes | 16-byte tag | Extended-nonce AEAD. Returns ciphertext with the tag appended. |

Demo

ChaCha20 Encrypt Online
ChaCha20 Decrypt Online
ChaCha20-Poly1305 Encrypt Online
ChaCha20-Poly1305 Decrypt Online

Install

npm install @jscrypto/chacha20 @jscrypto/core

Optional classic registry for composition tests and apps already using classic:

npm install @jscrypto/classic

Quick Start

import { registry } from '@jscrypto/classic';
import { chacha20Preset } from '@jscrypto/chacha20';

registry.use(chacha20Preset);

const cipher = registry.createCipher({
  cipher: 'ChaCha20-Poly1305',
  key,
});

const sealed = cipher.encrypt(plaintext, {
  nonce, // 12 bytes
  aad,
});

const opened = cipher.decrypt(sealed, {
  nonce,
  aad,
});

Encryption returns ciphertext with a 16-byte authentication tag appended. Decryption also accepts a detached tag:

const opened = cipher.decrypt(ciphertext, {
  nonce,
  aad,
  tag, // 16 bytes
});

AEAD transforms accept chunked input, but ChaCha20-Poly1305 and XChaCha20-Poly1305 currently output from finalize(). Raw ChaCha20 and XChaCha20 stream ciphers output from process().

Stream Ciphers

Raw stream ciphers encrypt and decrypt with the same operation. They output bytes from process() and can be used for true chunked streaming.

const chacha20 = registry.createCipher({
  cipher: 'ChaCha20',
  key,
  nonce, // 12 bytes
});

const ciphertext = chacha20.encrypt(plaintext);
const decrypted = chacha20.decrypt(ciphertext);

const xchacha20 = registry.createCipher({
  cipher: 'XChaCha20',
  key,
  nonce: xnonce, // 24 bytes
});

AEAD Ciphers

AEAD ciphers encrypt and authenticate data. They do not use mode or padding.

const chacha20Poly1305 = registry.createCipher({
  cipher: 'ChaCha20-Poly1305',
  key,
});

const sealed = chacha20Poly1305.encrypt(plaintext, {
  nonce, // 12 bytes
  aad,
});

const opened = chacha20Poly1305.decrypt(sealed, {
  nonce,
  aad,
});

const xchacha20Poly1305 = registry.createCipher({
  cipher: 'XChaCha20-Poly1305',
  key,
});

const xsealed = xchacha20Poly1305.encrypt(plaintext, {
  nonce: xnonce, // 24 bytes
  aad,
});

XChaCha20 and XChaCha20-Poly1305 use a 24-byte nonce. Internally the construction derives a subkey with HChaCha20 from the first 16 nonce bytes, then runs IETF ChaCha20 with a 12-byte nonce formed as 4 zero bytes followed by the last 8 nonce bytes.

Browser

Browser builds depend on @jscrypto/core. Load core first, then this package:

<script src="node_modules/@jscrypto/core/dist/jscrypto-core.iife.min.js"></script>
<script src="node_modules/@jscrypto/chacha20/dist/jscrypto-chacha20.iife.min.js"></script>
<script>
  const registry = jscryptoCore.createRegistry();
  registry.use(jscryptoChacha20.chacha20Preset);
</script>

Package export paths:

• @jscrypto/chacha20/browser
• @jscrypto/chacha20/umd

License

MIT