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.
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.
aes-256-gcm
- Both 16 bytes and 12 bytes nonce are supported.
aes-256-cbc
- Only for legacy applications. You should use
xchacha20-poly1305
oraes-256-gcm
as possible. - Nonce is always 16 bytes.
- Only for legacy applications. You should use
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.
xchacha20-poly1305
is implemented with pure JShchacha20
function andnode:crypto
'schacha20-poly1305
on node.- Currently (Mar 2025),
node:crypto
'schacha20-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 thenode:crypto
implementation and not work properly, specificallyaes-256-gcm
(16 bytes nonce) andchacha20-poly1305
. If you found such a problem, upgrade deno to the latest version.