ecies-geth

This is a JavaScript Elliptic Curve Integrated Encryption Scheme (ECIES) library for use in both Browser and NodeJS apps. This module is a modified version of the eccrypto JavaScript library. It's also based off Geth's implementation (Ethereum's ecies Go module).

Motivation

We needed to have a JavaScript library fully compliant with the way the Go Ethereum ECIES module (ecies) was implemented. \ Parity has implemented ECIES encryption and decryption for arbitrary messages through its extended JSON RPC API and has started translating it into a JavaScript library (ecies-parity). But issues remain in the latter and needed a pass to correct them.

Implementation details

As with eccrypto, this library provides two implementations for Browser and NodeJS with the same API.

The ECIES implementation details mimic those introduced by both Geth and Parity, which are:

• Implements a SHA-256 Key Derivation Function (KDF);
• ECDH based only on the secp256k1 curve (to match common blockchain transaction signing);
• Uses AES-128-CTR based symmetric encryption (with a 128-bit shared key derived from ECDH).

Cryptography Warning

The ECIES implementation given here is solely based off Geth's and Parity's implementations. This module offers no guarantee as to the security or validity of the implementation. Furthermore, this project is being actively developed and as such should not be used for highly sensitive informations without further investigation on its robustness. Any feedback or concerns regarding its security would be greatly appreciated.

Usage

npm i ecies-geth

Although this module was primarily developed for ECIES encryption/decryption, extra elliptic curve functionalities are provided.

ECIES Encryption / Decryption

const crypto = require('crypto');
const ecies = require('ecies-geth');

const privateKeyA = crypto.randomBytes(32);
const publicKeyA = await ecies.getPublic(privateKeyA);
const privateKeyB = crypto.randomBytes(32);
const publicKeyB = await ecies.getPublic(privateKeyB);

// Encrypting the message for B.
ecies.encrypt(publicKeyB, Buffer.from('msg to b')).then(function(encrypted) {
  // B decrypting the message.
  ecies.decrypt(privateKeyB, encrypted).then(function(plaintext) {
    console.log('Message to part B', plaintext.toString());
  });
});

// Encrypting the message for A.
ecies.encrypt(publicKeyA, Buffer.from('msg to a')).then(function(encrypted) {
  // A decrypting the message.
  ecies.decrypt(privateKeyA, encrypted).then(function(plaintext) {
    console.log('Message to part A', plaintext.toString());
  });
});

ECDSA Signing

const crypto = require('crypto');
const ecies = require('ecies-geth');

// A new random 32-byte private key.
const privateKey = crypto.randomBytes(32)
// Corresponding uncompressed (65-byte) public key.
const publicKey = await ecies.getPublic(privateKey);

const str = 'message to sign';
// Always hash your message to sign!
const msg = crypto.createHash('sha256').update(str).digest();

ecies.sign(privateKey, msg).then(function(sig) {
  console.log('Signature in DER format:', sig);
  ecies.verify(publicKey, msg, sig).then(function() {
    console.log('Signature is OK');
  }).catch(function() {
    console.log('Signature is BAD');
  });
})

ECDH Derivation

const crypto = require('crypto');
const ecies = require('ecies-geth');

const privateKeyA = crypto.randomBytes(32);
const publicKeyA = await ecies.getPublic(privateKeyA);
const privateKeyB = crypto.randomBytes(32);
const publicKeyB = await ecies.getPublic(privateKeyB);

ecies.derive(privateKeyA, publicKeyB).then(function(sharedKey1) {
  ecies.derive(privateKeyB, publicKeyA).then(function(sharedKey2) {
    console.log('Both shared keys are equal', sharedKey1, sharedKey2);
  })
})

Dependencies

This library relies on the following dependencies:

• elliptic;
• secp256k1.

To run the tests, you would need to install live-server:

npm i -g live-server

Credits

Thanks to @Methrat0n for the initial work on this adaptation.

License

This module is distributed under a MIT license. \ See the LICENSE file.

CHANGELOG.md

1.7.5

Features:

• Remove browser field in package.json.

1.7.3 (2024-10-23)

Features:

• Remove support for ES3 to new default ES5.

1.7.0 (2023-11-05)

Features:

• Remove dependency to (vulnerable) live-server only used for testing purpose;

• Breaking change: Messages encrypted with ecies-geth could not be decrypted using go-ethereum due to an ecies: invalid message error. Upon analysis of the source code, a nuanced discrepancy was identified. Specifically, the issue lay in the padding of the shared key: go-ethereum pads the shared key with zeros when it's less than 32 bytes, a behavior not mirrored in ecies-geth. Follow the links for specific lines in the sources:

  https://github.com/ethereum/go-ethereum/blob/master/crypto/ecies/ecies.go#L134-L136 https://github.com/cyrildever/ecies-geth/blob/master/lib/src/typescript/node.ts#L171

  IMPORTANT: This fix introduces a breaking change. Messages encrypted by the older version of this library might not be decryptable after the update, and vice versa. Users will need to be aware of this incompatibility when considering an upgrade.

1.6.10 (2023-03-21)

Features:

• Add ignoreDeprecations in tsconfig.json at compilation to keep target at ES3.

1.5.0 (2021-03-26)

Features:

• Add KeyPath and Path types.

1.4.0 (2021-01-11)

Features:

• Latest secp256k1 lib.

1.3.0 (2020-11-26)

Features:

• Breaking change: verify() returns true (instead of null).

1.2.2 (2020-07-25)

Features:

• Add eslint support.

1.1.0 (2020-05-15)

Features:

• Fix message length.

1.0.0 (2019-12-23)

Features:

• Original production version.