messages

Documentation

Overview

Package messages implements the message types communicated between client and server. The messaging in a successful run is sequenced as follows:

Client | Server
   PR -->      Pair Request
               (wait for epoch)
      <-- BR   Begin Run
   KE -->      Key Exchange
      <-- KEs  Server broadcasts all KE messages to all peers
   SR -->      Slot Reserve
      <-- RM   Recovered Messages
   DC -->      DC-net broadcast
      <-- CM   Confirm Messages (unsigned)
   CM -->      Confirm Messages (signed)
               (server joins all signatures)
      <-- CM   Confirm Messages (with all signatures)

If a peer fails to find their message after either the exponential slot reservation or XOR DC-net, the DC or CM message indicates to the server that blame must be assigned to remove malicious peers from the mix. This process requires secrets committed to by the KE to be revealed.

Client | Server
   PR -->      Pair Request
               (wait for epoch)
      <-- BR   Begin Run
   KE -->      Key Exchange
      <-- KEs  Server broadcasts all KE messages to all peers
   SR -->      Slot Reserve
      <-- RM   Recovered Messages
   DC -->      DC-net broadcast (with RevealSecrets=true)
      <-- CM   Confirm Messages (with RevealSecrets=true)
   RS -->      Reveal Secrets
               (server discovers misbehaving peers)
      <-- BR   Begin Run (with removed peers)
      ...

At any point, if the server times out receiving a client message, the following message contains a nonzero BR field, and a new run is performed, beginning with a new key exchange.

Index

• type BR
  • func BeginRun(vk []ed25519.PublicKey, mixes []int, sid []byte) *BR
  • func (br *BR) ServerError() error
• type BinaryRepresentable
• type CM
  • func ConfirmMix(mix BinaryRepresentable) *CM
  • func (cm *CM) ServerError() error
• type DC
  • func DCNet(dcs []*dcnet.Vec, s *Session) *DC
• type KE
  • func KeyExchange(ecdh []*x25519.Public, commitment []byte, ses *Session) *KE
• type KEs
  • func (kes *KEs) ServerError() error
• type PR
  • func PairRequest(pk ed25519.PublicKey, sk ed25519.PrivateKey, commitment, unmixed []byte, ...) *PR
  • func (pr *PR) VerifySignature(pub ed25519.PublicKey) bool
  • func (pr *PR) WriteSigned(w io.Writer)
• type RM
  • func RecoveredMessages(roots []*big.Int, s *Session) *RM
  • func (rm *RM) ServerError() error
• type RS
  • func RevealSecrets(ecdh []*x25519.KX, sr []*big.Int, m [][]byte) *RS
  • func (rs *RS) Commit(ses *Session) []byte
• type SR
  • func SlotReserve(dcmix [][]*big.Int, s *Session) *SR
• type ServerError
  • func (e ServerError) Error() string
• type Session
  • func NewSession(sid []byte, run int, vk []ed25519.PublicKey) *Session
• type Signed

Types

type BR

type BR struct {
	Vk            []ed25519.PublicKey
	MessageCounts []int
	Sid           []byte
	Err           ServerError
}

BR is the begin run message. It is sent to all remaining valid peers when a new run begins.

func BeginRun

func BeginRun(vk []ed25519.PublicKey, mixes []int, sid []byte) *BR

BeginRun creates the begin run message.

func (*BR) ServerError

func (br *BR) ServerError() error

type BinaryRepresentable

type BinaryRepresentable interface {
	encoding.BinaryMarshaler
	encoding.BinaryUnmarshaler
}

BinaryRepresentable is a union of the BinaryMarshaler and BinaryUnmarshaler interfaces.

type CM

type CM struct {
	Mix           BinaryRepresentable
	RevealSecrets bool
	BR            // Indicates to begin new run after peer exclusion
	Err           ServerError
}

CM is the confirmed mix message.

func ConfirmMix

func ConfirmMix(mix BinaryRepresentable) *CM

ConfirmedMix creates the confirmed mix message, sending either the confirmed mix or indication of a confirmation failure to the server.

func (*CM) ServerError

func (cm *CM) ServerError() error

type DC

type DC struct {
	Run           int
	DCNet         []*dcnet.Vec
	RevealSecrets bool
}

DC is the DC-net broadcast.

func DCNet

func DCNet(dcs []*dcnet.Vec, s *Session) *DC

DCNet creates a message containing the previously-committed DC-mix vector and the shared keys of peers we have chosen to exclude.

type KE

type KE struct {
	Run        int              // 0, 1, ...
	ECDH       []*x25519.Public // Public portions of x25519 key exchanges, one for each mixed message
	Commitment []byte           // Hash of RS (reveal secrets) message contents
}

KE is the client's opening key exchange message of a run.

func KeyExchange

func KeyExchange(ecdh []*x25519.Public, commitment []byte, ses *Session) *KE

KeyExchange creates a signed key exchange message to verifiably provide the x25519 public portion.

type KEs

type KEs struct {
	KEs []*KE
	BR  // Indicates to begin new run after peer exclusion
	Err ServerError
}

KEs is the server's broadcast of all received key exchange messages.

func (*KEs) ServerError

func (kes *KEs) ServerError() error

type PR

type PR struct {
	Identity       ed25519.PublicKey // Ephemeral session public key
	PairCommitment []byte            // Requirements for compatible mixes, e.g. same output amounts, tx versions, ...
	Unmixed        []byte            // Unmixed data contributed to a run result, e.g. transaction inputs and change outputs
	MessageCount   int               // Number of messages being mixed
	Signature      []byte
}

PR is the client's pairing request message. It is only seen at the start of the protocol.

func PairRequest

func PairRequest(pk ed25519.PublicKey, sk ed25519.PrivateKey, commitment, unmixed []byte, mixes int) *PR

PairRequest creates a signed request to be paired in a mix described by commitment, with possible initial unmixed data appearing in the final result. Ephemeral session keys pk and sk are used throughout the protocol.

func (*PR) VerifySignature

func (pr *PR) VerifySignature(pub ed25519.PublicKey) bool

func (*PR) WriteSigned

func (pr *PR) WriteSigned(w io.Writer)

type RM

type RM struct {
	Run           int
	Roots         []*big.Int
	RevealSecrets bool
	BR            // Indicates to begin new run after peer exclusion
	Err           ServerError
}

RM is the recovered messages result of collecting all SR messages and solving for the mixed original messages.

func RecoveredMessages

func RecoveredMessages(roots []*big.Int, s *Session) *RM

RecoveredMessages creates a recovered messages message.

func (*RM) ServerError

func (rm *RM) ServerError() error

type RS

type RS struct {
	ECDH []*x25519.Scalar
	SR   []*big.Int
	M    [][]byte
}

RS is the reveal secrets message. It reveals x25519, SR and DC secrets at the end of a failed run for blame assignment and misbehaving peer removal.

func RevealSecrets

func RevealSecrets(ecdh []*x25519.KX, sr []*big.Int, m [][]byte) *RS

RevealSecrets creates the reveal secrets message.

func (*RS) Commit

func (rs *RS) Commit(ses *Session) []byte

Commit commits to the contents of the reveal secrets message.

type SR

type SR struct {
	Run   int
	DCMix [][]*big.Int
}

SR is the slot reservation broadcast.

func SlotReserve

func SlotReserve(dcmix [][]*big.Int, s *Session) *SR

SlotReserve creates a slot reservation message to discover random, anonymous slot assignments for an XOR DC-net by mixing random data in a exponential DC-mix.

type ServerError

type ServerError int

ServerError describes an error message sent by the server. The peer cannot continue in the mix session if an error is received. The zero value indicates the absence of an error.

const (
	ErrAbortedSession ServerError = iota + 1
	ErrInvalidUnmixed
)

Server errors

func (ServerError) Error

func (e ServerError) Error() string

type Session

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

Session describes a current mixing session and run.

func NewSession

func NewSession(sid []byte, run int, vk []ed25519.PublicKey) *Session

NewSession creates a run session from a unique session identifier and peer ed25519 pubkeys ordered by peer index.

type Signed

type Signed interface {
	VerifySignature(pub ed25519.PublicKey) bool
}

Signed indicates a session message carries an ed25519 signature that must be checked.