Skip to content

Latest commit

 

History

History
148 lines (107 loc) · 6.55 KB

README.md

File metadata and controls

148 lines (107 loc) · 6.55 KB

ReBlockStorer

A tool for Hyperledger Iroha.

Does one of the following things with some existing blockstore:

  • Regeneration of all the key pairs (accounts' and peers' keys)
  • Regeneration of a part of keys, preserving known keypairs
  • Assigning new addresses to peers
  • Recalculation of block signatures only without re-creation of any keys

and... then you are provided with a blockstore that Iroha nodes can start up with.

Written in Python 3.

Installation

It is recommended to do the following steps being in some newly created python virtual environment.

  1. Download the sources
  2. pip3 install .

Docker

  1. Download the sources
  2. docker build -t reblockstorer .
  3. docker run reblockstorer --help

Use Cases and Usage Examples

Debugging Foreign Network

Target audience: Hyperledger Iroha maintainers.

Problem statement: someone has complained about a bug in Iroha and ready to provide a dump of blockstore but not the keys.

Resolution: use ReBlockStorer to re-create all the keys, re-sign transactions, re-link transaction batches, re-sign blocks and assign to peers new addresses. A blockstore generated by the tool can be used as an existing blockstore for Iroha peers to reproduce the issue and debug Iroha instance locally.

reblockstore -b /path/to/source/blockstore -o /path/to/new/blockstore -p /path/to/peers/list -k /path/to/store/new/keys/and/mappings

Peers list file should contain new peers addresses with internal ports (used as argument of AddPeer command) one by line. File contents example:

localhost:10001
localhost:10002

As a result, a new blockstore will be produced with the same contents as the source blockstore, but all the keys and signatures will be regenerated and you will be able to run the network for tests or just continue the work with the new version of blockstore when old keys were lost.

Lost Keys

Target audience: Hyperledger Iroha users.

Problem statement: there is a network that cannot be re-started from the scratch for some reason and the key of one of admin account is lost.

Resolution: use ReBlockStorer to re-create only admin's key and preserve all the rest keys.

Applying ReBlockStorer here will require all the rest keypairs (including private keys) in order to correctly sign all the existing transactions.

Note: if you are going use this example in your production environment, then you definitely have to review the blockchain concept. All the security benefits get immediately lost when users of a network have to show you own private keys.

reblockstore -b /path/to/source/blockstore -o /path/to/new/blockstore -k /path/to/store/new/keys/and/mappings -e /path/to/existing/keypairs

A keypair is a couple of files with the same name but different extensions: .priv and .pub. Each file contains a string without any trailing characters with hex representation of the corresponding key part.

Applying the command above will result in substitution of a single key (if all the rest keys were placed inside /path/to/existing/keypairs) in a whole blockstore. The resulting blockstore can be used in the network further. The users' keys will remain valid but COMPROMISED.

Genesis Block Modification

Target audience: Hyperledger Iroha users.

Problem statement: there is a network that cannot be re-started from the scratch for some reason and the genesis block has to be slightly modified (for example, for adding newly created permission to an existing role).

Resolution: use ReBlockStorer to recalculate blocks signatures only. All the keys and peers addresses has to remain the same. This case does NOT require users' keypairs. This case does require peers keypairs.

All the block hashes will be re-calculated due to the changes in the genesis block. The content of users' transactions woud not be changed, thus users' keys are not required (their transactions are not going to be re-signed).

reblockstore -b /path/to/source/blockstore -o /path/to/new/blockstore -k /path/to/store/new/keys/and/mappings -e /path/to/existing/keypairs -r

or with docker.

docker run \
    -v /path/to/source/blockstore:/in/blockstore \
    -v /path/to/new/blockstore:/out/blockstore  \
    -v /path/to/store/new/keys/and/mappings:/out/key \
    -v /path/to/existing/keypairs:/in/key
    soramitsu/reblockstorer -b /in/blockstore -o /out/blockstore -k /out/key -e /in/key -r

In this case, you have to put all the peers keypairs to /path/to/existing/keypairs.

ReBlockStorer Help Page Printout

$ reblockstore -h

or

$ docker run soramitsu/reblockstorer -h
usage: reblockstore [-h] [-b BLOCKSTORE] [-o OUTBLOCKSTORE] [-p PEERS]
                    [-k KEYDIR] [-e EXISTINGKEYS] [-r] [-f]

The tool for keys regeneration for Hyperledger Iroha blockstore

optional arguments:
  -h, --help            show this help message and exit
  -b BLOCKSTORE, --blockstore BLOCKSTORE
                        Path to source blockstore directory.
  -o OUTBLOCKSTORE, --outblockstore OUTBLOCKSTORE
                        Path to save the new blockstore. Will try to create
                        the path if not exists.
  -p PEERS, --peers PEERS
                        [OPTIONAL] A file that specifies peers addresses to
                        put to AddPeer commands. Each peer address should be
                        placed on its own line. If omitted, then peers
                        addresses will remain unmodified.
  -k KEYDIR, --keydir KEYDIR
                        [OPTIONAL] Path to save the new keys. Will try to
                        create the path if not exists. The keys will be saved
                        to OUTBLOCKSTORE directory if not specified.
  -e EXISTINGKEYS, --existingkeys EXISTINGKEYS
                        [OPTIONAL] Path to a folder with existing key pairs
                        which should not be recreated and overwritten. A
                        keypair is represented by a couple of files with the
                        same name but different extensions: .priv and .pub.
                        Each file contains a string without any trailing
                        characters with hex representation of the key.
  -r, --resignblocksonly
                        [OPTIONAL] Prevents users' keys recreation and user'
                        transactions re-signing. Only block signatures are get
                        recalculated. This option can be used only when peers'
                        keypairs are known and specified via existing keys
                        parameter -e.
  -f, --force           [OPTIONAL] Forces overwrite of outblockstore and
                        keydir directories.