eciesjs

eciesjs

Elliptic Curve Integrated Encryption Scheme for secp256k1/curve25519 in TypeScript.

This is the JavaScript/TypeScript version of eciespy with a built-in class-like secp256k1/curve25519 API, you may go there for detailed documentation and learn the mechanism under the hood.

If you want a WASM version to run directly in modern browsers or on some blockchains, check ecies-wasm.

Install

npm install eciesjs

We recommend using the latest Node runtime although it's still possible to install on old versions.

Quick Start

Run the code below with npx ts-node.

> import { encrypt, decrypt, PrivateKey } from 'eciesjs'
> const sk = new PrivateKey()
> const data = Buffer.from('hello world🌍')
> decrypt(sk.secret, encrypt(sk.publicKey.toHex(), data)).toString()
'hello world🌍'

See Configuration to control with more granularity.

API

encrypt(receiverRawPK: string | Uint8Array, msg: Uint8Array): Buffer

Parameters:

• receiverRawPK - Receiver's public key, hex string or buffer
• msg - Data to encrypt

Returns: Buffer

decrypt(receiverRawSK: string | Uint8Array, msg: Uint8Array): Buffer

Parameters:

• receiverRawSK - Receiver's private key, hex string or buffer
• msg - Data to decrypt

Returns: Buffer

PrivateKey

• Methods

static fromHex(hex: string): PrivateKey;
constructor(secret?: Uint8Array);
toHex(): string;
encapsulate(pk: PublicKey): Uint8Array;
multiply(pk: PublicKey, compressed?: boolean): Uint8Array;
equals(other: PrivateKey): boolean;

• Properties

get secret(): Buffer;
readonly publicKey: PublicKey;
private readonly data;

PublicKey

• Methods

static fromHex(hex: string): PublicKey;
constructor(data: Uint8Array);
toHex(compressed?: boolean): string;
decapsulate(sk: PrivateKey): Uint8Array;
equals(other: PublicKey): boolean;

• Properties

get uncompressed(): Buffer;
get compressed(): Buffer;
private readonly data;

Configuration

Following configurations are available.

• Elliptic curve: secp256k1 or curve25519 (x25519/ed25519)
• Ephemeral key format in the payload: compressed or uncompressed (only for secp256k1)
• Shared elliptic curve key format in the key derivation: compressed or uncompressed (only for secp256k1)
• Symmetric cipher algorithm: AES-256-GCM or XChaCha20-Poly1305
• Symmetric nonce length: 12 or 16 bytes (only for AES-256-GCM)

For compatibility, make sure different applications share the same configuration.

export type EllipticCurve = "secp256k1" | "x25519" | "ed25519";
export type SymmetricAlgorithm = "aes-256-gcm" | "xchacha20";
export type NonceLength = 12 | 16;

class Config {
  ellipticCurve: EllipticCurve = "secp256k1";
  isEphemeralKeyCompressed: boolean = false;
  isHkdfKeyCompressed: boolean = false;
  symmetricAlgorithm: SymmetricAlgorithm = "aes-256-gcm";
  symmetricNonceLength: NonceLength = 16;
}

export const ECIES_CONFIG = new Config();

Elliptic curve configuration

On ellipticCurve = "x25519" or ellipticCurve = "ed25519", x25519 (key exchange function on curve25519) or ed25519 (signature algorithm on curve25519) will be used for key exchange instead of secp256k1.

In this case, the payload would always be: 32 Bytes + Ciphered regardless of isEphemeralKeyCompressed.

If you don't know how to choose between x25519 and ed25519, just use the dedicated key exchange function x25519 for efficiency.

Secp256k1-specific configuration

On isEphemeralKeyCompressed = true, the payload would be: 33 Bytes + Ciphered instead of 65 Bytes + Ciphered.

On isHkdfKeyCompressed = true, the hkdf key would be derived from ephemeral public key (compressed) + shared public key (compressed) instead of ephemeral public key (uncompressed) + shared public key (uncompressed).

Symmetric cipher configuration

On symmetricAlgorithm = "xchacha20", plaintext data would be encrypted with XChaCha20-Poly1305.

On symmetricNonceLength = 12, the nonce of AES-256-GCM would be 12 bytes. XChaCha20-Poly1305's nonce is always 24 bytes regardless of symmetricNonceLength.

Security Audit

Following dependencies are audited:

• noble-curves
• noble-hashes

Changelog

See CHANGELOG.md.