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
.
npm install eciesjs
We recommend using the latest Node runtime although it's still possible to install on old versions.
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.
Parameters:
- receiverRawPK - Receiver's public key, hex string or buffer
- msg - Data to encrypt
Returns: Buffer
Parameters:
- receiverRawSK - Receiver's private key, hex string or buffer
- msg - Data to decrypt
Returns: Buffer
- 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;
- 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;
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();
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.
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)
.
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
.
Following dependencies are audited:
See CHANGELOG.md.