Board instructions

A change takes two different active board keys. Each member signs on their own machine: the cli commands read what the node holds in the wire form peers exchange, check it, show what the change sets, sign on this machine and hand the signed spork back in the same form. The board key never leaves the machine, and no message repeats it. The node checks the signatures as it checks those of a spork from a peer.

flowchart LR
    subgraph M["Machine of the board member"]
        K["Board key<br/>-k, --key-file or HEDGEHOG_BOARD_KEY"] --> C["hedgehog cli or util"]
    end
    C <-->|"sporks in wire form,<br/>never the key"| N["Node"]
    N <-->|"peer-to-peer"| P["Every other node"]

The key

The key comes from exactly one of three sources:

Source How
-k <hex>, --key <hex> The private board key on the command line, where other users of the machine can read it in the list of processes
--key-file <path> A regular file that only its owner can read and that holds the private board key in hex, or what hedgehog util key-generate writes, of which the public key is left aside; on a file system with POSIX permissions a file that a group or others hold any permission on is refused, with chmod 600 named as the remedy
$HEDGEHOG_BOARD_KEY The environment

A missing key, two sources at once, or a file that cannot be read as a key ends the command with exit code 2 and the usage, before the node is contacted. A key that is not a current board key ends it the same way, once the command has read the board keys of the node or of the file. On a network with keys of its own, --network-keys tells the command which public keys are the board’s.

Keep a key file readable by its owner only, and destroy a key once the board switches it off: together with enough other keys of an earlier board, it could still sign a chain of board keys that a freshly started node takes, see Changing the board keys.

The tasks 

flowchart TD
    Q{"What does the board want to do?"}
    Q -->|"change a value, such as the fee"| A["Changing a spork"]
    Q -->|"bring back sporks whose<br/>signer was switched off"| B["Renewing sporks"]
    Q -->|"sign a whole spork database,<br/>as at the launch"| C["Signing a spork database"]
    Q -->|"add a board key<br/>or switch one off"| D["Changing the board keys"]

A node of release 0.0.9 takes every type of spork but the storage, ledger and communication sporks, which it refuses unless it runs with the hidden --preview switch. Their gridspork-set and gridspork-get subcommands are hidden from --help, see Grid sporks.

What a spork holds, and how a node judges it, is on Grid sporks.

In the source

  • application/src/main/java/org/unigrid/hedgehog/model/option/BoardKeyOptions.java: the three sources of the board key and their messages

Table of contents