protocol

Documentation

Overview

Package protocol contains the functions and structure related to the save and retrieve protocol of the decenarch service.

The protocol has two messages:

• Announce which is sent from the root down the tree
• Reply which is sent back up to the root

A simple protocol uses four files: - struct.go defines the messages sent around - save.go defines the actions for each message related to the save process - utils.go defines the structures and functions of ExplicitNode and AnonNode used in the save process to reach consensus on an html tree without revealing the original tree itself.

Index

• Constants
• func GetExplicitSeenHash(en []ExplicitNode, seen []bool) ([]byte, error)
• func NewSaveProtocol(n *onet.TreeNodeInstance) (onet.ProtocolInstance, error)
• type AnonNode
  • func (n *AnonNode) AppendChild(c *AnonNode) error
  • func (n *AnonNode) IsIdenticalTo(that *AnonNode) bool
  • func (n *AnonNode) IsSimilarTo(that *AnonNode) bool
  • func (root *AnonNode) ListLeaves() []*AnonNode
  • func (root *AnonNode) ListPaths() [][]*AnonNode
  • func (n *AnonNode) RemoveChild(c *AnonNode) error
• type ExplicitNode
• type SaveAnnounce
• type SaveMessage
  • func (p *SaveMessage) AggregateErrors(reply []StructSaveReply)
  • func (p *SaveMessage) AggregateStructData(locTree *AnonNode, reply []StructSaveReply)
  • func (p *SaveMessage) AggregateUnstructData(locHash map[string]map[abstract.Point]crypto.SchnorrSig, ...)
  • func (p *SaveMessage) BuildConsensusHtmlPage() []byte
  • func (p *SaveMessage) GetLocalData() (*AnonNode, map[string]map[abstract.Point]crypto.SchnorrSig, error)
  • func (p *SaveMessage) HandleAnnounce(msg StructSaveAnnounce) error
  • func (p *SaveMessage) HandleReply(reply []StructSaveReply) error
  • func (p *SaveMessage) Start() error
• type SavePhase
• type SaveReply
• type StructSaveAnnounce
• type StructSaveReply

Constants

const Name = "Decenarch"

Name can be used from other packages to refer to this protocol.

const SaveName = Name + "Save"

Functions

func GetExplicitSeenHash

func GetExplicitSeenHash(en []ExplicitNode, seen []bool) ([]byte, error)

GetExplicitSeenHash take an explicit tree en and an array seen where seen[i] = true iff the conode has seen en[i] on its locally retrieved webdata else, seen[i] = false. It creates a hash of the tree represented as a byte array of the hashed data followed by the index of the children if the node is seen or a 0 if not.

func NewSaveProtocol

func NewSaveProtocol(n *onet.TreeNodeInstance) (onet.ProtocolInstance, error)

NewSaveProtocol initialises the structure for use in one round

Types

type AnonNode

type AnonNode struct {
	Parent, FirstChild, LastChild, PrevSibling, NextSibling *AnonNode

	HashedData string
	Seen       bool
}

AnonNode define the structure of an anonymised node. It is used to anonymise an html.Node from "golang.org/x/net/html" package

func (*AnonNode) AppendChild

func (n *AnonNode) AppendChild(c *AnonNode) error

AppendChild adds a node c as a child of p. If c already has a parent or siblings, it outputs an error and do nothing. Note : This code is identical to the eponym function of "golang.org/x/net/html"

func (*AnonNode) IsIdenticalTo

func (n *AnonNode) IsIdenticalTo(that *AnonNode) bool

IsIdenticalTo tests if two nodes are identical to each other.

 Example:
  R            R
 / \          /|\
A   A    and A B C
     \
      B

we have exhaustively that every node is identical with itself only.

func (*AnonNode) IsSimilarTo

func (n *AnonNode) IsSimilarTo(that *AnonNode) bool

IsSimilarTo tests if two nodes, usually from different trees, share a sufficiently high amount of things so that they can be swapped with no consequences for both of the tree. Note that the swap would involve the nodes only and not their parent/children/siblings.

 Example:
  R            R
 / \          /|\
A   A    and A B C
     \
      B

we have exhaustively :

• the Rs are similar
• all the As are similar

func (*AnonNode) ListLeaves

func (root *AnonNode) ListLeaves() []*AnonNode

ListLeaves takes the root of an AnonNode tree as input and outputs an array that contains all the leaves of the tree. The leaves are ordered from the most right one to the most left one.

Example:
             R
            /|\
the tree   A B C   will output [F,B,E,D]
          / \   \
         D   E   F

func (*AnonNode) ListPaths

func (root *AnonNode) ListPaths() [][]*AnonNode

ListPaths takes the root of an AnonNode tree as input and output an array of array. The latter is the list of all the paths from leaf to root of the tree. The paths are ordered from the most right path of the tree to the most left one.

Example:
             R
            / \
the tree   A   B   will output [ [F,B,R], [E,B,R], [D,B,R], [C,A,R] ]
          /   /|\
         C   D E F

func (*AnonNode) RemoveChild

func (n *AnonNode) RemoveChild(c *AnonNode) error

RemoveChild removes a node c that is a child of n. Afterwards, c will have no parent and no siblings.

It will panic if c's parent is not n. Note : This code is identical to the eponym function of "golang.org/x/net/html"

type ExplicitNode

type ExplicitNode struct {
	Children   []int64
	HashedData string
	Seen       bool
}

ExplicitNode always used as a part of an array permits to store a tree of AnonNode as an array that can be send through the network and from which the original tree can be deterministically reconstructed.

type SaveAnnounce

type SaveAnnounce struct {
	Phase         SavePhase
	Url           string
	MasterTree    []ExplicitNode
	MasterTreeSig crypto.SchnorrSig
	MasterHash    map[string]map[abstract.Point]crypto.SchnorrSig
}

SaveAnnounce is used to pass a message to all children when the protocol called is DecenarchSave

Phase : the phase the protocol is currently
Url : the url of the webpage the conodes will reach consensus on
MasterTree : the tree representing structured data with its signatures
MasterHash : the hash representing unstructured data with its signatures

type SaveMessage

type SaveMessage struct {
	*onet.TreeNodeInstance
	Phase       SavePhase
	Errs        []error
	Url         string
	ContentType string
	Threshold   int32

	MasterTree    *AnonNode
	MasterTreeSig crypto.SchnorrSig
	LocSeen       []bool
	LocSig        crypto.SchnorrSig
	SeenMap       map[string][]bool
	SeenSig       map[string]crypto.SchnorrSig

	MasterHash map[string]map[abstract.Point]crypto.SchnorrSig

	PlainNodes map[string]html.Node
	PlainData  map[string][]byte

	MsgToSign  chan []byte
	StringChan chan string

	RefTreeChan chan []ExplicitNode
	SeenMapChan chan map[string][]byte
	SeenSigChan chan map[string]crypto.SchnorrSig
}

SaveMessage just holds a message that is passed to all children. It also defines a channel that will receive the number of children. Only the root-node will write to the channel.

func (*SaveMessage) AggregateErrors

func (p *SaveMessage) AggregateErrors(reply []StructSaveReply)

AggregateErrors put all the errors contained in the children reply inside the SaveMessage p field p.Errs. It allows the current protocol to transmit the errors from its children to its parent.

func (*SaveMessage) AggregateStructData

func (p *SaveMessage) AggregateStructData(locTree *AnonNode, reply []StructSaveReply)

AggregateStructData take locTree the tree computed locally by the node and reply the replies of the node's children. It add the localTree signatures and the children's tree signatures inside the master tree that will be send to the node's parent.

func (*SaveMessage) AggregateUnstructData

func (p *SaveMessage) AggregateUnstructData(locHash map[string]map[abstract.Point]crypto.SchnorrSig, reply []StructSaveReply)

AggregateUnstructData take locHash, the hash of the data signed by the current node and reply the replies of the node's children. It verifies and signs the p.MasterHash with the signatures of both the nodes and its chidren.

func (*SaveMessage) BuildConsensusHtmlPage

func (p *SaveMessage) BuildConsensusHtmlPage() []byte

BuildConsensusHtmlPage takes the p.MasterTree made of *AnonNode and combine this data with the p.PlainNodes in order to create an *html.Node tree. From there, it creates a valid html page and outputs it.

func (*SaveMessage) GetLocalData

func (p *SaveMessage) GetLocalData() (*AnonNode, map[string]map[abstract.Point]crypto.SchnorrSig, error)

GetLocalData retrieve the data from the p.Url and handle it to make it either a AnonNodes tree or a signed hash. If the returned *AnonNode tree is not nil, then the map is. Else, it is the other way around. If both returned value are nil, then an error occured.

func (*SaveMessage) HandleAnnounce

func (p *SaveMessage) HandleAnnounce(msg StructSaveAnnounce) error

HandleAnnounce is the first message and is used to send an ID that is stored in all nodes.

Note: this function must be read as multiple functions with a common begining and end but each time a different 'case'. Each one can be considered as an independant function.

func (*SaveMessage) HandleReply

func (p *SaveMessage) HandleReply(reply []StructSaveReply) error

HandleReply is the message going up the tree and holding a counter to verify the number of nodes.

Note: this function must be read as multiple functions with a common begining and end but each time a different 'case'. Each one can be considered as an independant function.

func (*SaveMessage) Start

func (p *SaveMessage) Start() error

Start sends the Announce-message to all children

type SavePhase

type SavePhase int32

SavePhase is an indicator of the behaviour to have for a child of the root in the protocol.

const (
	NilPhase SavePhase = iota
	Consensus
	RequestMissingData
	CoSigning
	SkipchainSaving
	End
)

type SaveReply

type SaveReply struct {
	Phase         SavePhase
	Url           string
	Errs          []error
	MasterTree    []ExplicitNode //*AnonNode
	MasterTreeSig crypto.SchnorrSig
	MasterHash    map[string]map[abstract.Point]crypto.SchnorrSig

	SeenMap map[string][]byte
	SigMap  map[string]crypto.SchnorrSig

	RequestedNode map[string]html.Node
	RequestedData map[string][]byte
}

SaveReply return the protocol status, the consensus data and the errors of the conode that executed a save request.

Phase : the phase the protocol is currently
Url : the url of the webpage the conodes will reach consensus on
Errs : the errors that happends during the protocol
MasterTree : the tree representing structured data anonymised
MasterTreeSig : the signature of the root of the tree, creator of MasterTree
MasterHash : the hash representing unstructured data with its signatures

SeenMap : the map of the Seen field of each service of each conode. the
          keys are the public keys of the conode.
SigMap : the map of the signature associatied with the Seen field of each
         conodes. For a given public key (abstract.Point) both SigMap and
         SeenMap must have an entry

RequestedNode : the map linking the hash of an AnonNode's data with its
                plaintext html data.
RequestedData : the map linking the hash of an unstructured data with
                its plaintext data.

type StructSaveAnnounce

type StructSaveAnnounce struct {
	*onet.TreeNode
	SaveAnnounce
}

StructSaveAnnounce just contains SaveAnnounce and the data necessary to identify and process the message in the sda framework.

type StructSaveReply

type StructSaveReply struct {
	*onet.TreeNode
	SaveReply
}

StructSaveReply just contains StructSaveReply and the data necessary to identify and process the message in the sda framework.