ecies-lite

A lightweight ECIES tool implemented in pure Node.JS

Motivation

First of all, eccrypto is a great tool that supports many EC crypto functions. However, it was developed years ago, and the crypto library has evolved a lot since then. It seems that ECIES (Elliptic Curve Integrated Encryption Scheme) can be implemented in pure Node.JS, so I re-implemented it with the help of the latest crypto module released with Node.JS 10.x (according to my test, it runs pretty well with any node version after 6.x).

* Multiple Curves, KDF: SHA-256 (default & customizable), HMAC: MAC-WITH-SHA-256 (default & customizable), Multiple Cipher Algorithms

API

``config(curveName, cipherAlgorithm, hmacAlgorithm, ivSize, cipherKeyGen, hmacKeyGen)`

Config the default parameters for ecies-lite
* @param curveName: string | object - the elliptic curve to use | the config object contains config items
* @param cipherAlgorithm?: string - the cipher algorithm to use
* @param hmacAlgorithm?: string - the hmac algorithm to use
* @param ivSize?: number - the size (in bytes) of initialization vector (for cipher)
* @param cipherKeyGen?: (Buffer) -> Buffer - the cipher key generator
* @param hmacKeyGen?: (Buffer) -> Buffer - the hmac key generator
* @return none

`encrypt(pk, msg, opts)`

Encrypt a message using the recepient's public key
* @param pk: Buffer - The recipient's public key
* @param msg: Buffer - The message to encrypt
* @param opts?: the same structure as the config object - you can use it to specify advanced options
* @return {epk: Buffer, iv: Buffer, ct: Buffer, mac: Buffer} - the ecies-lite structured object with fields correspondingly stands for ephemeral public key, initialization vector, cipher text, mac code for above data, etc.

`decrypt(sk, body, opts)`

Decrypt a message in ecies-lite defined format using the recipient's private key
* @param sk: Buffer - the recepient's private key
* @param body: ecies-lite structured object - the ecies-lite body (seen format in encrypt) to decrypt
* @param opts?: the same structure as the config object - you can use it to specify advanced options
* @return Buffer - the plain text decrypted from the Ecies-lite body
* @throws when mac value is unmatched, it throws 'Corrupted Ecies-lite body: unmatched authentication code' error

Usage

`js
const crypto = require('crypto'),
ecies = require('ecies-lite');

let ecdh = crypto.createECDH('secp256k1');
ecdh.generateKeys();
let publicKey = ecdh.getPublicKey();
let body = ecies.encrypt(publicKey, Buffer.from('This message is for demo purpose'));
/** structure of ECIES body
epk: ephemeral public key;
iv: initialization vector for the cipher algorithm;
ct: cipher text with the derived encrypt key;
mac: MAC value of the above fields using the derived MAC key;
**/
for (let [k, v] of Object.entries(body)) {
console.log(${k}(${v.length}B):, v.toString('base64'));
}

let plain = ecies.decrypt(ecdh.getPrivateKey(), body);
console.log('Decrypted plain text:', plain.toString('utf-8'));

const curveName = 'prime256v1';
ecdh = crypto.createECDH(curveName);
ecdh.generateKeys();
const ephemEcdh = crypto.createECDH(curveName);
ephemEcdh.generateKeys();
const macKeyGen = (bytes) => {
let buf = Buffer.from(bytes);
for (let [index, value] of buf.entries()) {
buf[index] = value ^ index;
}
return buf;
}
ecies.config({curveName, macKeyGen});
body = ecies.encrypt(recEcdh.getPublicKey(), Buffer.from('This message is to demo advanced usage'), {esk: ephemEcdh.getPrivateKey()});
console.log(ecies.decrypt(recEcdh.getPrivateKey(), body).toString('utf-8'));
`

Dependencies


crypto` module shipped with Node later than 6.x

License

ISC
Written in 2018 by tibetty