mixtransport

Documentation

Overview

Package mixtransport implements the ENIG-Mix v2 moderate constant-rate transport orchestration. Cryptographic onion packets are supplied by an independently audited provider; this package intentionally does not invent an onion format.

Index

• Constants
• Variables
• func EncodeCommand(command Command, now time.Time) ([]byte, error)
• func ValidateCommand(command Command, now time.Time) error
• type Command
  • func DecodeCommand(encoded []byte, now time.Time) (Command, error)
  • func NewCommand(kind CommandKind, payload []byte, now time.Time, lifetime time.Duration) (Command, error)
• type CommandKind
• type Config
• type DispatchResult
• type FullRoute
  • func SelectFullRoute(policy nodedir.Policy, records []nodedir.Record, now time.Time, ...) (FullRoute, error)
• type LinkSecurity
• type PacketProvider
• type PacketSecurity
• type PacketSink
• type PreparedPacket
• type Scheduler
  • func NewScheduler(config Config, provider PacketProvider, sink PacketSink) (*Scheduler, error)
  • func (scheduler *Scheduler) Enqueue(ctx context.Context, command Command, now time.Time) (Ticket, error)
  • func (scheduler *Scheduler) Run(ctx context.Context) (runErr error)
• type Ticket
  • func (ticket Ticket) Wait(ctx context.Context) (DispatchResult, error)

Constants

const (
	ReferenceSlotInterval   = 5 * time.Second
	ReferencePollEverySlots = 6
)

const (
	// FullRouteMixHops is fixed for ENIG-Mix v2. Changing it would create a
	// distinguishable traffic class and therefore requires a protocol version.
	FullRouteMixHops = 3
	// FullRouteReplicas matches the full-node reference replication profile.
	FullRouteReplicas = 3
)

const (
	ProtocolVersion        = 2
	RequestIDBytes         = 32
	MinPacketBytes         = 8 * 1024
	DefaultPacketBytes     = 8 * 1024
	MaxPacketBytes         = 64 * 1024
	MaxCommandPayloadBytes = 2 * 1024
	MaxEncodedCommandBytes = 4 * 1024
	MaxCommandLifetime     = 15 * time.Minute
	MaxQueueEntries        = 4096
)

Variables

var (
	ErrPacketProviderRequired = errors.New("audited post-quantum hybrid mix packet provider required")
	ErrPrivateLinkRequired    = errors.New("audited post-quantum fixed-frame entry link required")
	ErrQueueFull              = errors.New("ENIG-Mix outbound queue is full")
	ErrCommandExpired         = errors.New("ENIG-Mix command expired before dispatch")
	ErrScheduleDiscontinuity  = errors.New("ENIG-Mix constant-rate schedule was interrupted")
)

var ErrInsufficientRouteDiversity = errors.New("insufficient independently addressable full nodes for an ENIG-Mix route")

Functions

func EncodeCommand

func EncodeCommand(command Command, now time.Time) ([]byte, error)

func ValidateCommand

func ValidateCommand(command Command, now time.Time) error

Types

type Command

type Command struct {
	Version   uint8       `json:"version"`
	RequestID string      `json:"request_id"`
	Kind      CommandKind `json:"kind"`
	CreatedAt time.Time   `json:"created_at"`
	ExpiresAt time.Time   `json:"expires_at"`
	Payload   []byte      `json:"payload"`
}

func DecodeCommand

func DecodeCommand(encoded []byte, now time.Time) (Command, error)

func NewCommand

func NewCommand(kind CommandKind, payload []byte, now time.Time, lifetime time.Duration) (Command, error)

type CommandKind

type CommandKind string

const (
	KindStore            CommandKind = "store"
	KindDirectoryLookup  CommandKind = "directory_lookup"
	KindDirectoryPublish CommandKind = "directory_publish"
	KindDeviceSync       CommandKind = "device_sync"
	KindDelete           CommandKind = "delete"
)

type Config

type Config struct {
	PacketBytes    int
	SlotInterval   time.Duration
	PollEverySlots uint64
	MaxQueue       int
	MaxLateness    time.Duration
	DispatchBudget time.Duration
}

type DispatchResult

type DispatchResult struct {
	RequestID string
	SentAt    time.Time
	Err       error
}

type FullRoute

type FullRoute struct {
	Mixes    [FullRouteMixHops]nodedir.Record
	Courier  nodedir.Record
	Replicas [FullRouteReplicas]nodedir.Record
}

FullRoute assigns temporary duties to otherwise identical full nodes. Every directory record is eligible for every duty; no permanent network role is encoded in the directory. A node may appear at most once in the assignment.

func SelectFullRoute

func SelectFullRoute(policy nodedir.Policy, records []nodedir.Record, now time.Time, entropy io.Reader) (FullRoute, error)

SelectFullRoute verifies the complete candidate set before randomness or selection. It then assigns three mix hops, one courier and three replicas from distinct node identities and distinct coarse IP prefixes. Prefix diversity is only a topological safeguard; it is not proof of independent ownership and must later be combined with operator-diversity attestations.

type LinkSecurity

type LinkSecurity struct {
	Protocol             string
	IndependentAudit     string
	AuthenticatedEntry   bool
	PersistentConnection bool
	FixedLengthFrames    bool
	PostQuantumHybridKEX bool
	NoRedirects          bool
}

type PacketProvider

type PacketProvider interface {
	Security() PacketSecurity
	PrepareReal(ctx context.Context, encodedCommand []byte, packetBytes int) (PreparedPacket, error)
	PreparePoll(ctx context.Context, packetBytes int) (PreparedPacket, error)
	PrepareCover(ctx context.Context, packetBytes int) (PreparedPacket, error)
}

PacketProvider owns the audited Sphinx/onion packet format, route selection, SURBs, per-hop keys, reply authentication, replay tags, and packet padding. Prepare methods must be local-only and must not perform observable network I/O.

type PacketSecurity

type PacketSecurity struct {
	Protocol                 string
	IndependentAudit         string
	MinimumMixHops           int
	FixedLengthPackets       bool
	LayeredMixing            bool
	PerHopAuthentication     bool
	ReplayProtection         bool
	UniformReplies           bool
	PostQuantumHybridOnion   bool
	ForwardSecureRoutingKeys bool
}

PacketSecurity describes requirements which the adapter and its independent audit must actually establish. These booleans are a fail-closed integration guard, not cryptographic evidence of an audit.

type PacketSink

type PacketSink interface {
	Security() LinkSecurity
	Send(ctx context.Context, packet []byte) error
}

PacketSink accepts an already protected fixed-size packet for a persistent, authenticated entry connection. It must never log packet bytes or timing together with application state.

type PreparedPacket

type PreparedPacket struct {
	Packet []byte
}

type Scheduler

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

func NewScheduler

func NewScheduler(config Config, provider PacketProvider, sink PacketSink) (*Scheduler, error)

func (*Scheduler) Enqueue

func (scheduler *Scheduler) Enqueue(ctx context.Context, command Command, now time.Time) (Ticket, error)

Enqueue performs all variable application work away from the scheduled send instant. Queue capacity is reserved before provider work or allocation.

func (*Scheduler) Run

func (scheduler *Scheduler) Run(ctx context.Context) (runErr error)

Run is the production timing loop. Any missed slot or transport failure ends the run, because continuing would make the advertised traffic shape false.

type Ticket

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

func (Ticket) Wait

func (ticket Ticket) Wait(ctx context.Context) (DispatchResult, error)