protocol

Documentation

Overview

Package protocol holds the SporeDB mycelium protocol.

Paquet format: - 1 byte for function selection - n bytes for data length specification (uvarint) - remaining bytes containing data

Index

• Constants
• Variables
• type Call
  • func (c *Call) Pack() (data []byte, err error)
  • func (c *Call) Unpack(in InputStream) error
• type Function
  • func (f Function) String() string
• type Gossip
  • func (*Gossip) Descriptor() ([]byte, []int)
  • func (m *Gossip) GetRequest() bool
  • func (m *Gossip) GetSpores() []string
  • func (*Gossip) ProtoMessage()
  • func (m *Gossip) Reset()
  • func (m *Gossip) String() string
• type Hello
  • func (*Hello) Descriptor() ([]byte, []int)
  • func (m *Hello) GetIdentity() string
  • func (m *Hello) GetPublicKey() []byte
  • func (m *Hello) GetSignature() []byte
  • func (m *Hello) GetTimestamp() *google_protobuf.Timestamp
  • func (m *Hello) GetVersion() uint64
  • func (*Hello) ProtoMessage()
  • func (m *Hello) Reset()
  • func (m *Hello) String() string
• type InputStream
• type Node
  • func (*Node) Descriptor() ([]byte, []int)
  • func (n Node) Equals(n2 Node) bool
  • func (m *Node) GetAddress() string
  • func (m *Node) GetIdentity() string
  • func (*Node) ProtoMessage()
  • func (m *Node) Reset()
  • func (m *Node) String() string
  • func (n Node) Zero() bool
• type Nodes
  • func (*Nodes) Descriptor() ([]byte, []int)
  • func (m *Nodes) GetNodes() []*Node
  • func (*Nodes) ProtoMessage()
  • func (m *Nodes) Reset()
  • func (m *Nodes) String() string
• type Raw
  • func (*Raw) Descriptor() ([]byte, []int)
  • func (m *Raw) GetData() []byte
  • func (m *Raw) GetKey() string
  • func (r Raw) GetMessage() []byte
  • func (m *Raw) GetSignature() []byte
  • func (m *Raw) GetVersion() *version.V
  • func (*Raw) ProtoMessage()
  • func (m *Raw) Reset()
  • func (m *Raw) String() string
• type Session
  • func NewECDHESession(kr sec.KeyRing, identity string) Session
• type Transport
  • func NewLocalTransport() (a, b Transport)

Constants

const (
	FnHELLO          Function = 0x01
	FnSPORE                   = 0x02
	FnENDORSE                 = 0x03
	FnRECOVERREQUEST          = 0x04
	FnRAW                     = 0x05
	FnGOSSIP                  = 0x06
	FnNODES                   = 0x07
	FnCATALOG                 = 0x08
)

Function values.

const Version uint64 = 1

Version is the current version of the protocol. Two different versions are not supposed to be able to communicate.

Variables

var (
	ErrOldTimestamp     = errors.New("session timestamp too old")
	ErrInvalidPublicKey = errors.New("invalid public key")
)

Errors for session management.

Types

type Call

type Call struct {
	F Function
	M proto.Message
}

Call represents a package that can be sent across the mycelium network.

func (*Call) Pack

func (c *Call) Pack() (data []byte, err error)

Pack generates a ready-to-send package for the Call.

func (*Call) Unpack

func (c *Call) Unpack(in InputStream) error

Unpack retrieves one Call from raw stream.

type Function

type Function byte

Function represents the content of a package.

func (Function) String

func (f Function) String() string

type Gossip

type Gossip struct {
	Spores  []string `protobuf:"bytes,1,rep,name=spores" json:"spores,omitempty"`
	Request bool     `protobuf:"varint,2,opt,name=request" json:"request,omitempty"`
}

func (*Gossip) Descriptor

func (*Gossip) Descriptor() ([]byte, []int)

func (*Gossip) GetRequest

func (m *Gossip) GetRequest() bool

func (*Gossip) GetSpores

func (m *Gossip) GetSpores() []string

func (*Gossip) ProtoMessage

func (*Gossip) ProtoMessage()

func (*Gossip) Reset

func (m *Gossip) Reset()

func (*Gossip) String

func (m *Gossip) String() string

type Hello

type Hello struct {
	Version   uint64                     `protobuf:"varint,1,opt,name=version" json:"version,omitempty"`
	Identity  string                     `protobuf:"bytes,2,opt,name=identity" json:"identity,omitempty"`
	Timestamp *google_protobuf.Timestamp `protobuf:"bytes,3,opt,name=timestamp" json:"timestamp,omitempty"`
	// The public key is used in the ECDHE key exchange.
	// It MUST be a curve25519 public key.
	PublicKey []byte `protobuf:"bytes,9,opt,name=public_key,json=publicKey,proto3" json:"public_key,omitempty"`
	// The signature of the Hello message is computed on the message with an empty signature.
	// signature = signature by emitter ( marshal ( hello without signature ) )
	//
	// It is used as the authentication block of the ECDHE key exchange.
	// If the used signature key is not trusted by one peer, the connection MAY BE established
	// in "untrusted" mode, meaning that sensible operations MUST NOT be executed with the
	// connected peer (vulnerable to MitM attacks).
	Signature []byte `protobuf:"bytes,10,opt,name=signature,proto3" json:"signature,omitempty"`
}

func (*Hello) Descriptor

func (*Hello) Descriptor() ([]byte, []int)

func (*Hello) GetIdentity

func (m *Hello) GetIdentity() string

func (*Hello) GetPublicKey

func (m *Hello) GetPublicKey() []byte

func (*Hello) GetSignature

func (m *Hello) GetSignature() []byte

func (*Hello) GetTimestamp

func (m *Hello) GetTimestamp() *google_protobuf.Timestamp

func (*Hello) GetVersion

func (m *Hello) GetVersion() uint64

func (*Hello) ProtoMessage

func (*Hello) ProtoMessage()

func (*Hello) Reset

func (m *Hello) Reset()

func (*Hello) String

func (m *Hello) String() string

type InputStream

type InputStream interface {
	io.Reader
	io.ByteReader
}

InputStream represents a reader that can also be read byte by byte.

type Node

type Node struct {
	Identity string `protobuf:"bytes,1,opt,name=identity" json:"identity,omitempty"`
	Address  string `protobuf:"bytes,2,opt,name=address" json:"address,omitempty"`
}

func (*Node) Descriptor

func (*Node) Descriptor() ([]byte, []int)

func (Node) Equals

func (n Node) Equals(n2 Node) bool

Equals shall be used to compare two nodes.

func (*Node) GetAddress

func (m *Node) GetAddress() string

func (*Node) GetIdentity

func (m *Node) GetIdentity() string

func (*Node) ProtoMessage

func (*Node) ProtoMessage()

func (*Node) Reset

func (m *Node) Reset()

func (*Node) String

func (m *Node) String() string

func (Node) Zero

func (n Node) Zero() bool

Zero returns true if n is the zero value for nodes.

type Nodes

type Nodes struct {
	Nodes []*Node `protobuf:"bytes,1,rep,name=nodes" json:"nodes,omitempty"`
}

func (*Nodes) Descriptor

func (*Nodes) Descriptor() ([]byte, []int)

func (*Nodes) GetNodes

func (m *Nodes) GetNodes() []*Node

func (*Nodes) ProtoMessage

func (*Nodes) ProtoMessage()

func (*Nodes) Reset

func (m *Nodes) Reset()

func (*Nodes) String

func (m *Nodes) String() string

type Raw

type Raw struct {
	Key       string     `protobuf:"bytes,1,opt,name=key" json:"key,omitempty"`
	Version   *version.V `protobuf:"bytes,2,opt,name=version" json:"version,omitempty"`
	Data      []byte     `protobuf:"bytes,3,opt,name=data,proto3" json:"data,omitempty"`
	Signature []byte     `protobuf:"bytes,10,opt,name=signature,proto3" json:"signature,omitempty"`
}

func (*Raw) Descriptor

func (*Raw) Descriptor() ([]byte, []int)

func (*Raw) GetData

func (m *Raw) GetData() []byte

func (*Raw) GetKey

func (m *Raw) GetKey() string

func (Raw) GetMessage

func (r Raw) GetMessage() []byte

GetMessage returns the message used in the signature of a raw message.

func (*Raw) GetSignature

func (m *Raw) GetSignature() []byte

func (*Raw) GetVersion

func (m *Raw) GetVersion() *version.V

func (*Raw) ProtoMessage

func (*Raw) ProtoMessage()

func (*Raw) Reset

func (m *Raw) Reset()

func (*Raw) String

func (m *Raw) String() string

type Session

type Session interface {
	// A Session can acts as a Transport itself, being transparent for the application.
	Transport

	// Hello builds a new Hello message (handshake).
	// It might be called several times, in case of connection reset.
	Hello() (*Hello, error)

	// Verify verifies Hello messages for conformity.
	// It might be called several times, in case of connection reset.
	Verify(*Hello) error

	// Open MUST be called after sending an Hello message and having received
	// a verified Hello message from the peer. It opens incoming and outgoing
	// encrypted channel.
	Open(Transport) error

	// IsTrusted returns weither the peer shall be trusted (is correctly authenticated).
	IsTrusted() bool
}

Session shall be used to establish a secure channel between two peers. It shall act as a proxy between the application and the underlying Transport.

func NewECDHESession

func NewECDHESession(kr sec.KeyRing, identity string) Session

NewECDHESession returns a ECDHE session, using the KeyRing for peer authentication and signature management. Identity must be current node's own identity.

Once Open has been called, every data passing through this Session will be encrypted using AES-256-CTR. Additional data authentication mechanism should be used for sensible informations (Raw messages for instance).

type Transport

type Transport interface {
	io.ReadWriteCloser
	io.ByteReader
}

Transport is a generic representation of a communication channel.

func NewLocalTransport

func NewLocalTransport() (a, b Transport)

NewLocalTransport returns two bounded Transport for use in tests.