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
   CT -->       Post-Quantum ciphertext exchange
      <-- CTs   Server broadcasts ciphertexts created by others for us
   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
   CT -->       Post-Quantum ciphertext exchange
      <-- CTs   Server broadcasts ciphertexts created by others for us
   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(sk ed25519.PrivateKey, mix BinaryRepresentable) *CM
  • func (cm *CM) ServerError() error
  • func (cm *CM) VerifySignature(pub ed25519.PublicKey) bool
• type CT
  • func Ciphertexts(ciphertexts []*Sntrup4591761Ciphertext, ses *Session) *CT
  • func (ct *CT) VerifySignature(pub ed25519.PublicKey) bool
• type CTs
  • func (cts *CTs) ServerError() error
• type DC
  • func DCNet(dcs []*dcnet.Vec, s *Session) *DC
  • func (dc *DC) VerifySignature(pub ed25519.PublicKey) bool
• type KE
  • func KeyExchange(kx *dcnet.KX, commitment []byte, ses *Session) *KE
  • func (ke *KE) VerifySignature(pub ed25519.PublicKey) bool
• 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
• type RM
  • func RecoveredMessages(roots []*big.Int, s *Session) *RM
  • func (rm *RM) ServerError() error
• type RS
  • func RevealSecrets(prngSeed []byte, sr []*big.Int, m [][]byte, s *Session) *RS
  • func (rs *RS) Commit(ses *Session) []byte
• type SR
  • func SlotReserve(dcmix [][]*big.Int, s *Session) *SR
  • func (sr *SR) VerifySignature(pub ed25519.PublicKey) bool
• type ServerError
  • func (e ServerError) Error() string
• type Session
  • func NewSession(sid []byte, run int, sk ed25519.PrivateKey, vk []ed25519.PublicKey) *Session
• type Signed
• type Sntrup4591761Ciphertext
• type Sntrup4591761PublicKey

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
	Signature     []byte
}

CM is the confirmed mix message.

func ConfirmMix

func ConfirmMix(sk ed25519.PrivateKey, 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

func (*CM) VerifySignature

func (cm *CM) VerifySignature(pub ed25519.PublicKey) bool

type CT

type CT struct {
	Ciphertexts []*Sntrup4591761Ciphertext
	Signature   []byte
}

CT is the client's exchange of post-quantum shared key ciphertexts with all other peers in the run.

func Ciphertexts

func Ciphertexts(ciphertexts []*Sntrup4591761Ciphertext, ses *Session) *CT

Ciphertexts creates the ciphertext message.

func (*CT) VerifySignature

func (ct *CT) VerifySignature(pub ed25519.PublicKey) bool

type CTs

type CTs struct {
	Ciphertexts []*Sntrup4591761Ciphertext
	BR          // Indicates to begin a new run after peer exclusion
	Err         ServerError
}

CTs is the server's broadcast of encapsulated shared key ciphertexts created by all other peers for our client.

func (*CTs) ServerError

func (cts *CTs) ServerError() error

type DC

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

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.

func (*DC) VerifySignature

func (dc *DC) VerifySignature(pub ed25519.PublicKey) bool

type KE

type KE struct {
	Run        int // 0, 1, ...
	ECDH       *x25519.Public
	PQPK       *Sntrup4591761PublicKey
	Commitment []byte // Hash of RS (reveal secrets) message contents
	Signature  []byte
}

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

func KeyExchange

func KeyExchange(kx *dcnet.KX, commitment []byte, ses *Session) *KE

KeyExchange creates a signed key exchange message to verifiably provide the x25519 and sntrup4591761 public keys.

func (*KE) VerifySignature

func (ke *KE) VerifySignature(pub ed25519.PublicKey) bool

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

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 {
	Seed []byte
	SR   []*big.Int
	M    [][]byte
}

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

func RevealSecrets

func RevealSecrets(prngSeed []byte, sr []*big.Int, m [][]byte, s *Session) *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
	Signature []byte
}

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.

func (*SR) VerifySignature

func (sr *SR) VerifySignature(pub ed25519.PublicKey) bool

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
	ErrTooFewPeers
)

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, sk ed25519.PrivateKey, vk []ed25519.PublicKey) *Session

NewSession creates a run session from a unique session identifier and peer ed25519 pubkeys ordered by peer index. If sk is non-nil, signed message types created using this session will contain a valid signature.

type Signed

type Signed interface {
	VerifySignature(pub ed25519.PublicKey) bool
	// contains filtered or unexported methods
}

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

type Sntrup4591761Ciphertext

type Sntrup4591761Ciphertext = [sntrup4591761.CiphertextSize]byte

type Sntrup4591761PublicKey

type Sntrup4591761PublicKey = [sntrup4591761.PublicKeySize]byte