eth-crypto-utils

eth-crypto-utils

Lightweight cryptographic utilities for Ethereum, built for easy integration with Web3 and Solidity contracts.

Tutorials

• Creating keys and use them for ethereum transactions

  In this tutorial we will create an ethereum-identity and use it to send transactions to the blockchain.

• Sign and validate data with solidity

  In this tutorial we will sign data in javascript and validate the signature inside of a smart-contract.

• Sending encrypted and signed data to other identities

  In this tutorial we will use the ethereum-identities and asymmetric cryptography to send an encrypted and signed message from Alice to Bob.

Using eth-crypto-utils

Install

  npm install eth-crypto-utils

// es6
import EthCrypto from 'eth-crypto-utils';

// node
const EthCrypto = require('eth-crypto-utils');

API

• createIdentity()
• publicKeyByPrivateKey()
• publicKey.toAddress()
• publicKey.compress()
• publicKey.decompress()
• sign()
• recover()
• recoverPublicKey()
• encryptWithPublicKey()
• decryptWithPrivateKey()
• cipher.stringify()
• cipher.parse()
• signTransaction()
• txDataByCompiled()
• calculateContractAddress()
• hex compress/decompress

createIdentity()

Creates a new ethereum-identity with privateKey, publicKey and address as hex-string.

  const identity = EthCrypto.createIdentity();
  /* > {
      address: '0x6E2E6791bBb53bC8949a61d567c404304c523273',
      privateKey: '0xdae34dac5d27f71ea91010eb6dda623490980e1ef4bc34e7a7bef7cc55680260',
      publicKey: '8abbf1cc3154b063a2b663a2337e554424dc22191941d9f4f50ea633c1d06ece...'
  } */

You can also create an identity by providing your own entropy-buffer. Use this with caution, a bad entropy can result in an unsecure private key.

  const entropy = Buffer.from('f2dacf...', 'utf-8'); // must contain at least 128 chars
  const identity = EthCrypto.createIdentity(entropy);
  /* > {
      address: '0x6E2E6791bBb53bC8949a61d567c404304c523273',
      privateKey: '0xdae34dac5d27f71ea91010eb6dda623490980e1ef4bc34e7a7bef7cc55680260',
      publicKey: '991ce4643653ef452327ee3d1a56af19c84599d340ffd427e784...'
  } */

publicKeyByPrivateKey()

Derives the publicKey from a privateKey and returns it as hex-string.

  const publicKey = EthCrypto.publicKeyByPrivateKey(
      '0xdae34dac5d27f71ea91010eb6dda623490980e1ef4bc34e7a7bef7cc55680260'
  );
  // > 'bf1cc3154424dc22191941d9f4f50b063a2b663a2337e5548abea633c1d06ece...'

publicKey.toAddress()

Derives the ethereum-address from the publicKey.

  const address = EthCrypto.publicKey.toAddress(
      'bf1cc3154424dc22191941d9f4f50b063a2b663a2337e5548abea633c1d06ece...'
  );
  // > '0x6E2E6791bBb53bC8949a61d567c404304c523273'

publicKey.compress()

Compresses an uncompressed publicKey.

  const address = EthCrypto.publicKey.compress(
      '04a34d6aef3eb42335fb3cacb59...'
  );
  // > '03a34d6aef3eb42335fb3cacb59478c0b44c0bbeb8bb4ca427dbc7044157a5d24b' // compressed keys start with '02' or '03'

publicKey.decompress()

Decompresses a compressed publicKey.

  const address = EthCrypto.publicKey.decompress(
      '03a34d6aef3eb42335fb3c...'
  );
  // > 'a34d6aef3eb42335fb3cacb5947' // non-compressed keys start with '04' or no prefix

sign()

Signs the hash with the privateKey. Returns the signature as hex-string.

  const message = 'foobar';
  const messageHash = EthCrypto.hash.keccak256(message);
  const signature = EthCrypto.sign(
      '0xdae34dac5d27f71ea91010eb6dda623490980e1ef4bc34e7a7bef7cc55680260', // privateKey
      messageHash // hash of message
  );
  // > '0xf34b809d8f3af6ff80c66b3428e866ff0d5..'

recover()

Recovers the signers address from the signature.

    const signer = EthCrypto.recover(
      '0xcafb241acc46ff80c44ba58e866f741d..',
      EthCrypto.hash.keccak256('foobar') // signed message hash
  );
  // > '0x6E2E6791bBb53bC8949a61d567c404304c523273'

recoverPublicKey()

Recovers the signers publicKey from the signature.

    const signer = EthCrypto.recoverPublicKey(
      '0xcafb241acc46ff80c44ba58e866f741d5..', // signature
      EthCrypto.hash.keccak256('foobar') // message hash
  );
  // > 'dae34dac5d27f71ea91010eb6dda623490980e1ef4bc34e7a7bef7cc55680260..'

encryptWithPublicKey()

Encrypts the message with the publicKey so that only the corresponding privateKey can decrypt it. Returns (async) the encrypted data as object with hex-strings.

    const encrypted = await EthCrypto.encryptWithPublicKey(
        'bf1cc3154424dc22191941d9f4f50b063a2b663a2337e5548abea633c1d06ece...', // publicKey
        'foobar' // message
    );
    /* >  {
            iv: 'a1eec54cb45283b427bd1a5028524aa1',
            ephemPublicKey: 'c0068d5fc48ee181f2fb10910444f19f41ea66615d7a6acf39ed83c30...',
            ciphertext: 'dbc39cfc4ce1a44ee19f7499965fbbcc',
            mac: '88958009fe3c7ef2a49a371d3a2040a2d2cb57f246ee38264a196490b293763f'
        } */

decryptWithPrivateKey()

Decrypts the encrypted data with the privateKey. Returns (async) the message as string.

    const message = await EthCrypto.decryptWithPrivateKey(
        '0xdae34dac5d27f71ea91010eb6dda623490980e1ef4bc34e7a7bef7cc55680260', // privateKey
        {
            iv: 'a1eec54cb45283b427bd1a5028524aa1',
            ephemPublicKey: 'c0068d5fc48ee181f2fb10910444f19f41ea66615d7a6acf39ed83c30...',
            ciphertext: 'dbc39cfc4ce1a44ee19f7499965fbbcc',
            mac: '88958009fe3c7ef2a49a371d3a2040a2d2cb57f246ee38264a196490b293763f'
        } // encrypted-data
    );
    // 'foobar'

cipher.stringify()

Transforms the object with the encrypted data into a smaller string-representation.

const str = EthCrypto.cipher.stringify({
    iv: 'a1eec54cb45283b427bd1a5028524aa1',
    ephemPublicKey: 'c0068d5fc48ee181f2fb10910444f19f41ea66615d7a6acf39ed83c30...',
    ciphertext: 'dbc39cfc4ce1a44ee19f7499965fbbcc',
    mac: '88958009fe3c7ef2a49a371d3a2040a2d2cb57f246ee38264a196490b293763f'
});
// > '8db32099dab281c8f5aece2852577f43e69e5a4039ab06532fc965b01079...'

cipher.parse()

Parses the string-representation back into the encrypted object.

const str = EthCrypto.cipher.parse('59ab06532fc965b0107977f43e69e5a4038db32099dab281c8f5aece2852...');
/* >  {
        iv: 'a1eec54cb45283b427bd1a5028524aa1',
        ephemPublicKey: 'c0068d5fc48ee181f2fb10910444f19f41ea66615d7a6acf39ed83c30...',
        ciphertext: 'dbc39cfc4ce1a44ee19f7499965fbbcc',
        mac: '88958009fe3c7ef2a49a371d3a2040a2d2cb57f246ee38264a196490b293763f'
    } */

signTransaction()

Signs a raw transaction with the privateKey. Returns a Promise that resolves a serialized tx-string which can be submitted to the node.

const identity = EthCrypto.createIdentity();
const rawTx = {
    from: identity.address,
    to: '0x86Fa049857E0209aa7D9e616F7eb3b3B78ECfdb0',
    value: new BN('1000000000000000000'),
    gasPrice: 5000000000,
    nonce: 0,
    gasLimit: 21000
};
const signedTx = await EthCrypto.signTransaction(
    rawTx,
    identity.privateKey
);
console.log(signedTx);
// > '2040a2071d3ad2cb...'

// you can now send the tx to the node
const receipt = await web3.eth.sendSignedTransaction(signedTx);

txDataByCompiled()

Creates the data-string which must be submitted with an transaction to create a contract-instance.

const SolidityCli = require('solidity-cli');

// create compiled solidity-code
const compiled = await SolidityCli.compileCode(
    'contract ExampleContract {...'
)[':ExampleContract'];

const createCode = EthCrypto.txDataByCompiled(
    compiled.interface, // abi
    compiled.bytecode, // bytecode
    [identity.address] // constructor-arguments
);

// now you can submit this to the blockchain
const serializedTx = await EthCrypto.signTransaction(
    {
        from: identity.address,
        nonce: 0,
        gasLimit: 5000000,
        gasPrice: 5000000000,
        data: createCode
    },
    identity.privateKey
);
const receipt = await web3.eth.sendSignedTransaction(serializedTx);

calculateContractAddress()

Calculates the address for the contract from the senders address and the nonce, without deploying it to the blockchain.

// pre-calculate address
const calculatedAddress = EthCrypto.calculateContractAddress(
    account.address, // address of the sender
    3 // nonce with which the contract will be deployed
);

const rawTx = {
    from: account.address,
    gasPrice: parseInt(gasPrice),
    nonce: 3,
    data: compiled.code
};
const receipt = await state.web3.eth.sendTransaction(rawTx);

console.log(receipt.contractAddress === calculatedAddress);
// > true

hex compress/decompress

"Compress" or "decompress" a hex-string to make it smaller. You can either compress to utf16 which reduces the size to about 1/4, or to base64 which reduces the size to about 4/5. This is not a real compression, it just make your string smaller when you have to store it in utf-16 anyways.

const hexString = '0xdae34dac5d27f71ea91010eb6dda623490980e1ef4bc34e7a7bef7cc55680260'; // 66 chars

const utf16 = EthCrypto.hex.compress(hexString); // compress to utf16
// > 'ﴚ艡䆷襞ၻ炞蛰ⶬ輦ꂩቊ쮷Řᨇ' // 16 chars

const base64 = EthCrypto.hex.compress(hexString, true); // compress to base64
// > 'qfLaz5mKCpEkrLtEHvpRnCeQbeJXu4bw/RqCYQFYGgc=' // 44 chars

EthCrypto.hex.decompress(utf16); // decompress from utf16
// > '0x41b7895e107be946709eea9f2d...'

EthCrypto.hex.decompress(base64, true); // decompress from base64
// > '0x41b7895e107be946709eea9f2d...'