corruptible

README

Corruptible Conduit Framework

Corruptible Conduit Framework is an integration testing framework for Byzantine Fault Tolerant (BFT) setups. As shown by figure below, this framework is composed of Corruptible Conduits and Corruptible Conduit Factory. A Corruptible Conduit Factory (CCF) is configured on each node that is meant to play malicious during the test scenario. The CCF utilizes Corruptible Conduits (CC)s to connect the engines of its node to the networking adaptor. In contrast to the normal conduits, the CCs do not relay the events from their engine to the network adaptor. Instead, they relay the events from their engine to the CCF. On receiving an event from a CC, the CCF forwards the message to a remote attacker. The attacker is in charge of orchestrating specific attacks through its programmable attack vectors. The attacker controls the set of malicious nodes. All messages from engines of attacker-controlled corrupted nodes are directly wired to the attacker. The attacker runs its registered attack vectors on each received message from its corrupted nodes' engines. As the result of running the attack vectors, the attacker may ask CCF of some corrupted nodes to send some certain messages on its behalf. In this way, the Corruptible Conduit Framework empowers testing attack vectors by just replacing the default conduit factory of malicious nodes with a CCF, and without any further modification to the application-layer implementation of the node.

Documentation

Index

• type Conduit
  • func (c *Conduit) Close() error
  • func (c *Conduit) Multicast(event interface{}, num uint, targetIDs ...flow.Identifier) error
  • func (c *Conduit) Publish(event interface{}, targetIDs ...flow.Identifier) error
  • func (c *Conduit) Unicast(event interface{}, targetID flow.Identifier) error
• type ConduitFactory
  • func NewCorruptibleConduitFactory(logger zerolog.Logger, chainId flow.ChainID, me module.Local, ...) *ConduitFactory
  • func (c *ConduitFactory) EngineClosingChannel(channel network.Channel) error
  • func (c *ConduitFactory) HandleIncomingEvent(event interface{}, channel network.Channel, protocol insecure.Protocol, ...) error
  • func (c *ConduitFactory) NewConduit(ctx context.Context, channel network.Channel) (network.Conduit, error)
  • func (c *ConduitFactory) ProcessAttackerMessage(stream insecure.CorruptibleConduitFactory_ProcessAttackerMessageServer) error
  • func (c *ConduitFactory) RegisterAdapter(adapter network.Adapter) error
  • func (c *ConduitFactory) RegisterAttacker(_ context.Context, in *insecure.AttackerRegisterMessage) (*empty.Empty, error)
  • func (c ConduitFactory) ServerAddress() string

Types

type Conduit

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

Conduit implements a corruptible conduit that sends all incoming events to its registered controller (i.e., factory) without dispatching them to the networking layer.

func (*Conduit) Close

func (c *Conduit) Close() error

Close informs the conduit controller that the engine is not going to use this conduit anymore.

func (*Conduit) Multicast

func (c *Conduit) Multicast(event interface{}, num uint, targetIDs ...flow.Identifier) error

Multicast sends the incoming events as multicast events to the controller of this conduit (i.e., its factory) to handle.

func (*Conduit) Publish

func (c *Conduit) Publish(event interface{}, targetIDs ...flow.Identifier) error

Publish sends the incoming events as publish events to the controller of this conduit (i.e., its factory) to handle.

func (*Conduit) Unicast

func (c *Conduit) Unicast(event interface{}, targetID flow.Identifier) error

Unicast sends the incoming events as unicast events to the controller of this conduit (i.e., its factory) to handle.

type ConduitFactory

type ConduitFactory struct {
	component.Component
	// contains filtered or unexported fields
}

ConduitFactory implements a corruptible conduit factory, that creates corruptible conduits and acts as their master. A remote attacker can register itself to this conduit factory. Whenever any corruptible conduit generated by this factory receives an event from its engine, it relays the event to this factory, which in turn is relayed to the register attacker. The attacker can asynchronously dictate the conduit factory to send messages on behalf of the node this factory resides on.

func NewCorruptibleConduitFactory

func NewCorruptibleConduitFactory(
	logger zerolog.Logger,
	chainId flow.ChainID,
	me module.Local,
	codec network.Codec,
	address string) *ConduitFactory

func (*ConduitFactory) EngineClosingChannel

func (c *ConduitFactory) EngineClosingChannel(channel network.Channel) error

EngineClosingChannel is called by the slave conduits of this factory to let it know that the corresponding engine of the conduit is not going to use it anymore, so the channel can be closed safely.

func (*ConduitFactory) HandleIncomingEvent

func (c *ConduitFactory) HandleIncomingEvent(
	event interface{},
	channel network.Channel,
	protocol insecure.Protocol,
	num uint32,
	targetIds ...flow.Identifier) error

HandleIncomingEvent is called by the slave conduits of this factory to relay their incoming events. If there is an attacker registered to this factory, the event is dispatched to it. Otherwise, the factory follows the correct protocol path by sending the message down to the networking layer to deliver to its targets.

func (*ConduitFactory) NewConduit

func (c *ConduitFactory) NewConduit(ctx context.Context, channel network.Channel) (network.Conduit, error)

NewConduit creates a conduit on the specified channel. Prior to creating any conduit, the factory requires an Adapter to be registered with it.

func (*ConduitFactory) ProcessAttackerMessage

func (c *ConduitFactory) ProcessAttackerMessage(stream insecure.CorruptibleConduitFactory_ProcessAttackerMessageServer) error

func (*ConduitFactory) RegisterAdapter

func (c *ConduitFactory) RegisterAdapter(adapter network.Adapter) error

RegisterAdapter sets the Adapter component of the factory. The Adapter is a wrapper around the Network layer that only exposes the set of methods that are needed by a conduit.

func (*ConduitFactory) RegisterAttacker

func (c *ConduitFactory) RegisterAttacker(_ context.Context, in *insecure.AttackerRegisterMessage) (*empty.Empty, error)

RegisterAttacker is a gRPC end-point for this conduit factory that lets an attacker register itself to it, so that the attacker can control it. Registering an attacker on a conduit is an exactly-once immutable operation, any second attempt after a successful registration returns an error.

func (ConduitFactory) ServerAddress

func (c ConduitFactory) ServerAddress() string

ServerAddress returns address of the gRPC server that is running by this corrupted conduit factory.