Skip to content

Latest commit

 

History

History
62 lines (46 loc) · 3.06 KB

README.md

File metadata and controls

62 lines (46 loc) · 3.06 KB
Raw

@ecies/ciphers

License NPM Package NPM Downloads Install size CI Codecov

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.