eth-crypto

Cryptographic javascript-functions for ethereum and tutorials on how to use them together with web3js and solidity.

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.

Sponsored by

The JavaScript Database

Using eth-crypto

Install

1  npm install eth-crypto --save

1// es6
2import EthCrypto from 'eth-crypto';
3
4// node
5const EthCrypto = require('eth-crypto');

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.

1  const identity = EthCrypto.createIdentity();
2  /* > {
3      address: '0x3f243FdacE01Cfd9719f7359c94BA11361f32471',
4      privateKey: '0x107be946709e41b7895eea9f2dacf998a0a9124acbb786f0fd1a826101581a07',
5      publicKey: 'bf1cc3154424dc22191941d9f4f50b063a2b663a2337e5548abea633c1d06ece...'
6  } */

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.

1  const entropy = Buffer.from('f2dacf...', 'utf-8'); // must contain at least 128 chars
2  const identity = EthCrypto.createIdentity(entropy);
3  /* > {
4      address: '0x59c8d4d645B0a3b230DE368d815ebDE372d37Ea8',
5      privateKey: '0x18cea40e44624867ddfd775b2898cdb2da29b4be92ee072b9eb02d43b6f2473a',
6      publicKey: '991ce4643653ef452327ee3d1a56af19c84599d340ffd427e784...'
7  } */

publicKeyByPrivateKey()

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

1  const publicKey = EthCrypto.publicKeyByPrivateKey(
2      '0x107be946709e41b7895eea9f2dacf998a0a9124acbb786f0fd1a826101581a07'
3  );
4  // > 'bf1cc3154424dc22191941d9f4f50b063a2b663a2337e5548abea633c1d06ece...'

publicKey.toAddress()

Derives the ethereum-address from the publicKey.

1  const address = EthCrypto.publicKey.toAddress(
2      'bf1cc3154424dc22191941d9f4f50b063a2b663a2337e5548abea633c1d06ece...'
3  );
4  // > '0x3f243FdacE01Cfd9719f7359c94BA11361f32471'

publicKey.compress()

Compresses an uncompressed publicKey.

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

publicKey.decompress()

Decompresses a compressed publicKey.

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

sign()

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

1  const message = 'foobar';
2  const messageHash = EthCrypto.hash.keccak256(message);
3  const signature = EthCrypto.sign(
4      '0x107be946709e41b7895eea9f2dacf998a0a9124acbb786f0fd1a826101581a07', // privateKey
5      messageHash // hash of message
6  );
7  // > '0xc04b809d8f33c46ff80c44ba58e866ff0d5..'

recover()

Recovers the signers address from the signature.

1    const signer = EthCrypto.recover(
2      '0xc04b809d8f33c46ff80c44ba58e866ff0d5..',
3      EthCrypto.hash.keccak256('foobar') // signed message hash
4  );
5  // > '0x3f243FdacE01Cfd9719f7359c94BA11361f32471'

recoverPublicKey()

Recovers the signers publicKey from the signature.

1    const signer = EthCrypto.recoverPublicKey(
2      '0xc04b809d8f33c46ff80c44ba58e866ff0d5..', // signature
3      EthCrypto.hash.keccak256('foobar') // message hash
4  );
5  // > 'bf1cc3154424dc22191941d9f4f50b063a2b663a2337e5548abea633c1d06ece..'

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.

1    const encrypted = await EthCrypto.encryptWithPublicKey(
2        'bf1cc3154424dc22191941d9f4f50b063a2b663a2337e5548abea633c1d06ece...', // publicKey
3        'foobar' // message
4    );
5    /* >  {
6            iv: '02aeac54cb45283b427bd1a5028552c1',
7            ephemPublicKey: '044acf39ed83c304f19f41ea66615d7a6c0068d5fc48ee181f2fb1091...',
8            ciphertext: '5fbbcc1a44ee19f7499dbc39cfc4ce96',
9            mac: '96490b293763f49a371d3a2040a2d2cb57f246ee88958009fe3c7ef2a38264a1'
10        } */

decryptWithPrivateKey()

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

1    const message = await EthCrypto.decryptWithPrivateKey(
2        '0x107be946709e41b7895eea9f2dacf998a0a9124acbb786f0fd1a826101581a07', // privateKey
3        {
4            iv: '02aeac54cb45283b427bd1a5028552c1',
5            ephemPublicKey: '044acf39ed83c304f19f41ea66615d7a6c0068d5fc48ee181f2fb1091...',
6            ciphertext: '5fbbcc1a44ee19f7499dbc39cfc4ce96',
7            mac: '96490b293763f49a371d3a2040a2d2cb57f246ee88958009fe3c7ef2a38264a1'
8        } // encrypted-data
9    );
10    // 'foobar'

cipher.stringify()

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

1const str = EthCrypto.cipher.stringify({
2    iv: '02aeac54cb45283b427bd1a5028552c1',
3    ephemPublicKey: '044acf39ed83c304f19f41ea66615d7a6c0068d5fc48ee181f2fb1091...',
4    ciphertext: '5fbbcc1a44ee19f7499dbc39cfc4ce96',
5    mac: '96490b293763f49a371d3a2040a2d2cb57f246ee88958009fe3c7ef2a38264a1'
6});
7// > '59ab06532fc965b0107977f43e69e5a4038db32099dab281c8f5aece2852...'

cipher.parse()

Parses the string-representation back into the encrypted object.

1const str = EthCrypto.cipher.parse('59ab06532fc965b0107977f43e69e5a4038db32099dab281c8f5aece2852...');
2/* >  {
3        iv: '02aeac54cb45283b427bd1a5028552c1',
4        ephemPublicKey: '044acf39ed83c304f19f41ea66615d7a6c0068d5fc48ee181f2fb1091...',
5        ciphertext: '5fbbcc1a44ee19f7499dbc39cfc4ce96',
6        mac: '96490b293763f49a371d3a2040a2d2cb57f246ee88958009fe3c7ef2a38264a1'
7    } */

signTransaction()

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

1const identity = EthCrypto.createIdentity();
2const rawTx = {
3    from: identity.address,
4    to: '0x86Fa049857E0209aa7D9e616F7eb3b3B78ECfdb0',
5    value: new BN('1000000000000000000'),
6    gasPrice: 5000000000,
7    nonce: 0,
8    gasLimit: 21000
9};
10const signedTx = await EthCrypto.signTransaction(
11    rawTx,
12    identity.privateKey
13);
14console.log(signedTx);
15// > '071d3a2040a2d2cb...'
16
17// you can now send the tx to the node
18const receipt = await web3.eth.sendSignedTransaction(signedTx);

txDataByCompiled()

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

1const SolidityCli = require('solidity-cli');
2
3// create compiled solidity-code
4const compiled = await SolidityCli.compileCode(
5    'contract ExampleContract {...'
6)[':ExampleContract'];
7
8const createCode = EthCrypto.txDataByCompiled(
9    compiled.interface, // abi
10    compiled.bytecode, // bytecode
11    [identity.address] // constructor-arguments
12);
13
14// now you can submit this to the blockchain
15const serializedTx = await EthCrypto.signTransaction(
16    {
17        from: identity.address,
18        nonce: 0,
19        gasLimit: 5000000,
20        gasPrice: 5000000000,
21        data: createCode
22    },
23    identity.privateKey
24);
25const 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.

1// pre-calculate address
2const calculatedAddress = EthCrypto.calculateContractAddress(
3    account.address, // address of the sender
4    3 // nonce with which the contract will be deployed
5);
6
7const rawTx = {
8    from: account.address,
9    gasPrice: parseInt(gasPrice),
10    nonce: 3,
11    data: compiled.code
12};
13const receipt = await state.web3.eth.sendTransaction(rawTx);
14
15console.log(receipt.contractAddress === calculatedAddress);
16// > 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.

1const hexString = '0x107be946709e41b7895eea9f2dacf998a0a9124acbb786f0fd1a826101581a07'; // 66 chars
2
3const utf16 = EthCrypto.hex.compress(hexString); // compress to utf16
4// > 'ၻ炞䆷襞ⶬ輦ꂩቊ쮷蛰ﴚ艡Řᨇ' // 16 chars
5
6const base64 = EthCrypto.hex.compress(hexString, true); // compress to base64
7// > 'EHvpRnCeQbeJXuqfLaz5mKCpEkrLt4bw/RqCYQFYGgc=' // 44 chars
8
9EthCrypto.hex.decompress(utf16); // decompress from utf16
10// > '0x107be946709e41b7895eea9f2d...'
11
12EthCrypto.hex.decompress(base64, true); // decompress from base64
13// > '0x107be946709e41b7895eea9f2d...'
14