@ecies/ciphers

@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, you need to upgrade deno and run with --conditions deno (>=2.4.0) or --unstable-node-conditions deno(>=2.3.6,<2.4.0).