@ecies/ciphers

Node/Pure JavaScript symmetric ciphers adapter.

On browsers (or React Native, deno), it’ll use @noble/ciphers’s implementation for compatibility.

On node (or bun), it’ll use node:crypto’s implementation for efficiency.

[!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 (Nov 2024), node:crypto’s chacha20-poly1305 is not supported on deno and bun, @noble/ciphers’s implementation is used on both platforms instead.
• deno does not support indirect conditional exports. If you use this library to build another library, client code of your library probably falls back to the node:crypto implementation and may not work properly, specifically aes-256-gcm (16 bytes nonce) and chacha20-poly1305.