randhound

Documentation

Overview

Package randhound is a client/server protocol that allows a list of nodes to produce a public random string in an unbiasable and verifiable way given that a threshold of nodes is honest. The protocol is driven by a leader (= client) which scavenges the public randomness from its peers (= servers) over the course of four round-trips (= phases).

Index

• func NewRHSimulation(config string) (sda.Simulation, error)
• func NewRandHound(node *sda.TreeNodeInstance) (sda.ProtocolInstance, error)
• type Group
• type I1
• type I2
• type I3
• type I4
• type Leader
• type Peer
• type R1
• type R2
• type R3
• type R3Resp
• type R4
• type R4Share
• type RHSimulation
  • func (rhs *RHSimulation) Run(config *sda.SimulationConfig) error
  • func (rhs *RHSimulation) Setup(dir string, hosts []string) (*sda.SimulationConfig, error)
• type RandHound
  • func (rh *RandHound) Random() ([]byte, error)
  • func (rh *RandHound) Setup(nodes uint32, trustees uint32, purpose string) error
  • func (rh *RandHound) Shard(seed []byte, shards uint32) ([][]*network.Entity, error)
  • func (rh *RandHound) Start() error
• type Session
• type WI1
• type WI2
• type WI3
• type WI4
• type WR1
• type WR2
• type WR3
• type WR4

Functions

func NewRHSimulation

func NewRHSimulation(config string) (sda.Simulation, error)

NewRHSimulation creates a new RandHound simulation

func NewRandHound

func NewRandHound(node *sda.TreeNodeInstance) (sda.ProtocolInstance, error)

NewRandHound generates a new RandHound instance.

Types

type Group

type Group struct {
	N uint32 // Total number of nodes (peers + leader)
	F uint32 // Maximum number of Byzantine nodes tolerated (1/3)
	L uint32 // Minimum number of non-Byzantine nodes required (2/3)
	K uint32 // Total number of trustees (= shares generated per peer)
	R uint32 // Minimum number of signatures needed to certify a deal
	T uint32 // Minimum number of shares needed to reconstruct a secret
}

Group encapsulates all the configuration parameters of a list of RandHound nodes.

type I1

type I1 struct {
	SID     []byte   // Session identifier: hash of session info block
	Session *Session // Session parameters
	GID     []byte   // Group identifier: hash of group parameter block
	Group   *Group   // Group parameters
	HRc     []byte   // Client's trustee-randomness commit
}

I1 is the message sent by the leader to the peers in phase 1.

type I2

type I2 struct {
	SID []byte // Session identifier
	Rc  []byte // Leader's trustee-selection randomnes
}

I2 is the message sent by the leader to the peers in phase 2.

type I3

type I3 struct {
	SID []byte         // Session identifier
	R2s map[uint32]*R2 // Leaders's list of signed R2 messages; empty slices represent missing R2 messages
}

I3 is the message sent by the leader to the peers in phase 3.

type I4

type I4 struct {
	SID     []byte               // Session identifier
	Invalid map[uint32]*[]uint32 // Map to mark invalid responses
}

I4 is the message sent by the leader to the peers in phase 4.

type Leader

type Leader struct {
	Done chan bool // For signaling that a protocol run is finished
	// contains filtered or unexported fields
}

Leader (=client) refers to the node which initiates the RandHound protocol, moves it forward, and ultimately outputs the generated public randomness.

type Peer

type Peer struct {
	// contains filtered or unexported fields
}

Peer (=server) refers to a node which contributes to the generation of the public randomness.

type R1

type R1 struct {
	Src uint32 // Source of the message
	HI1 []byte // Hash of I1 message
	HRs []byte // Peer's trustee-randomness commit
}

R1 is the reply sent by the peers to the leader in phase 1.

type R2

type R2 struct {
	Src  uint32 // Source of the message
	HI2  []byte // Hash of I2 message
	Rs   []byte // Peers' trustee-selection randomness
	Deal []byte // Peer's secret-sharing to trustees
}

R2 is the reply sent by the peers to the leader in phase 2.

type R3

type R3 struct {
	Src       uint32   // Source of the message
	HI3       []byte   // Hash of I3 message
	Responses []R3Resp // Responses to dealt secret-shares
}

R3 is the reply sent by the peers to the leader in phase 3.

type R3Resp

type R3Resp struct {
	DealerIdx uint32 // Dealer's index in the peer list
	ShareIdx  uint32 // Share's index in deal we are validating
	Resp      []byte // Encoded response to dealer's deal
}

R3Resp encapsulates a peer's response together with some metadata.

type R4

type R4 struct {
	Src    uint32              // Source of the message
	HI4    []byte              // Hash of I4 message
	Shares map[uint32]*R4Share // Revealed secret-shares
}

R4 is the reply sent by the peers to the leader in phase 4.

type R4Share

type R4Share struct {
	DealerIdx uint32          // Dealer's index in the peer list
	ShareIdx  uint32          // Share's index in dealer's deal
	Share     abstract.Secret // Decrypted share dealt to this server
}

R4Share encapsulates a peer's share together with some metadata.

type RHSimulation

type RHSimulation struct {
	sda.SimulationBFTree
	Trustees uint32
	Purpose  string
	Shards   uint32
}

RHSimulation implements a RandHound simulation

func (*RHSimulation) Run

func (rhs *RHSimulation) Run(config *sda.SimulationConfig) error

Run initiates a RandHound simulation

func (*RHSimulation) Setup

func (rhs *RHSimulation) Setup(dir string, hosts []string) (*sda.SimulationConfig, error)

Setup configures a RandHound simulation with certain parameters

type RandHound

type RandHound struct {
	*sda.TreeNodeInstance
	GID     []byte   // Group ID
	Group   *Group   // Group parameters
	SID     []byte   // Session ID
	Session *Session // Session parameters
	Leader  *Leader  // Protocol leader
	Peer    *Peer    // Current peer
}

RandHound is the main protocol struct and implements the sda.ProtocolInstance interface.

func (*RandHound) Random

func (rh *RandHound) Random() ([]byte, error)

Random returns the public random string produced by RandHound

func (*RandHound) Setup

func (rh *RandHound) Setup(nodes uint32, trustees uint32, purpose string) error

Setup configures a RandHound instance by creating group and session parameters of the protocol. Needs to be called before Start.

func (*RandHound) Shard

func (rh *RandHound) Shard(seed []byte, shards uint32) ([][]*network.Entity, error)

Shard produces a pseudorandom sharding of the network entity list based on a seed and a number of requested shards.

func (*RandHound) Start

func (rh *RandHound) Start() error

Start initiates the RandHound protocol. The leader chooses its trustee-selection randomness, forms the message I1 and sends it to its children.

type Session

type Session struct {
	Fingerprint []byte    // Fingerprint of a public key (usually of the leader)
	Purpose     string    // Purpose of randomness
	Time        time.Time // Scheduled initiation time
}

Session encapsulates some metadata of a RandHound protocol run.

type WI1

type WI1 struct {
	*sda.TreeNode
	I1
}

WI1 is a SDA-wrapper around I1

type WI2

type WI2 struct {
	*sda.TreeNode
	I2
}

WI2 is a SDA-wrapper around I2

type WI3

type WI3 struct {
	*sda.TreeNode
	I3
}

WI3 is a SDA-wrapper around I3

type WI4

type WI4 struct {
	*sda.TreeNode
	I4
}

WI4 is a SDA-wrapper around I4

type WR1

type WR1 struct {
	*sda.TreeNode
	R1
}

WR1 is a SDA-wrapper around R1

type WR2

type WR2 struct {
	*sda.TreeNode
	R2
}

WR2 is a SDA-wrapper around R2

type WR3

type WR3 struct {
	*sda.TreeNode
	R3
}

WR3 is a SDA-wrapper around R3

type WR4

type WR4 struct {
	*sda.TreeNode
	R4
}

WR4 is a SDA-wrapper around R4