@ecies/ciphers

Node/Pure JavaScript symmetric ciphers adapter.

If native implementations are available on some platforms (e.g. node, deno, bun), it'll use node:crypto for efficiency.

Otherwise (e.g. browser, react native), it'll use @noble/ciphers for compatibility.

| | aes | chacha | | ------------ | ---------------- | ---------------- | | Node | node:crypto ⚡ | node:crypto ⚡ | | Bun | node:crypto ⚡ | @noble/ciphers | | Deno | node:crypto ⚡ | @noble/ciphers | | Browser | @noble/ciphers | @noble/ciphers | | React Native | @noble/ciphers | @noble/ciphers |

[!NOTE] You may need to polyfill crypto.getRandomValues for React Native.

There are some limitations, see Known limitations below.

This library is tree-shakeable, unused code will be excluded by bundlers.

Check the example folder for bun/deno usage.

Quick start

import { aes256gcm } from "@ecies/ciphers/aes";
import { randomBytes } from "@noble/ciphers/webcrypto";

const TEXT = "hello world🌍!";
const encoder = new TextEncoder();
const decoder = new TextDecoder();
const msg = encoder.encode(TEXT);

const key = randomBytes();
const nonce = randomBytes(16);
const cipher = aes256gcm(key, nonce);
console.log("decrypted:", decoder.decode(cipher.decrypt(cipher.encrypt(msg))));

The API follows @noble/ciphers's API for ease of use, you can check their examples as well.

Supported ciphers

• aes-256-gcm
  • Both 16 bytes and 12 bytes nonce are supported.
• aes-256-cbc
  • Only for legacy applications. You should use xchacha20-poly1305 or aes-256-gcm as possible.
  • Nonce is always 16 bytes.
• chacha20-poly1305
  • Nonce is always 12 bytes.
• xchacha20-poly1305
  • Nonce is always 24 bytes.

If key is fixed and nonce is less than 16 bytes, avoid randomly generated nonce.

Known limitations

• xchacha20-poly1305 is implemented with pure JS hchacha20 function and node:crypto's chacha20-poly1305 on node.
• Currently (Mar 2025), node:crypto's chacha20-poly1305 is not supported on deno and bun, @noble/ciphers's implementation is used on both platforms instead.
• Some old versions of deno do not support indirect conditional exports. If you use this library to build another library, client code of your library may fall back to the node:crypto implementation and not work properly, specifically aes-256-gcm (16 bytes nonce) and chacha20-poly1305. If you found such a problem, upgrade deno to the latest version.

Release Notes

0.2.3

• Use node:crypto's aes implementation on deno
• Bump dependencies
• Revamp documentation

0.2.2

• Add chacha20-poly1305 support
• Bump dependencies
• Add minimum supported node (16.0.0) runtime check in CI

0.2.1

• Add React Native package exports

0.2.0

• Add xchacha20-poly1305 support

0.1.0

• First beta version release with aes-256-gcm and aes-256-cbc support