Skip to content
forked from ecies/js

Elliptic Curve Integrated Encryption Scheme for secp256k1 in TypeScript

License

Notifications You must be signed in to change notification settings

Hard265/ecies-rn

 
 

Repository files navigation

eciesjs

Codacy Badge License Npm Package CI Codecov

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.

Install

npm install eciesjs

We recommend using the latest Node runtime although it's still possible to install on old versions (but at least node 16).

Quick Start

import { PrivateKey, decrypt, encrypt } from "eciesjs";

const sk = new PrivateKey()
const data = Buffer.from("hello world🌍")
const decrypted = decrypt(sk.secret, encrypt(sk.publicKey.toHex(), data))
console.log(Buffer.from(decrypted).toString())

Run the example code above:

$ pnpm build && cd example && pnpm install && node index.js
hello world🌍

See Configuration to control with more granularity.

Browser Support

This library is browser-friendly, check the example/browser directory for details. Currently it's necessary to polyfill some node modules (like node:crypto, Buffer). From v0.5.0, it can run in browsers without polyfill.

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

API

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

Parameters:

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

Returns: Buffer

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

Parameters:

  • receiverRawSK - Receiver's private key, hex string or Uint8Array
  • 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:

Changelog

See CHANGELOG.md.

About

Elliptic Curve Integrated Encryption Scheme for secp256k1 in TypeScript

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • TypeScript 87.2%
  • JavaScript 8.1%
  • CSS 3.9%
  • HTML 0.8%