packet

Documentation

Overview

Package packet handles segmenting messages into uniform sized packets and generating a stream of cipher halves and receiver cloaked addresses to encrypt them with, and reassembling the segments into the original messages.

Index

• Constants
• func EncodePacket(ep *PacketParams) (pkt []byte, e error)
• func GetKeysFromPacket(d []byte) (from *crypto.Pub, to crypto.CloakedPubKey, iv nonce.IV, e error)
• func SplitToPackets(pp *PacketParams, segSize int, ks *crypto.KeySet) (dataShards int, packets [][]byte, e error)
• type Packet
  • func DecodePacket(d []byte, from *crypto.Pub, to *crypto.Prv, iv nonce.IV) (f *Packet, e error)
  • func (p *Packet) GetOverhead() int
• type PacketParams
  • func (ep PacketParams) GetOverhead() int
• type Packets
  • func JoinPackets(packets Packets) (pkts Packets, msg []byte, e error)
  • func RemovePacket(slice Packets, s int) Packets
  • func (p Packets) Len() int
  • func (p Packets) Less(i, j int) bool
  • func (p Packets) Swap(i, j int)
• type Segment
  • func (s Segment) String() (o string)
• type Segments
  • func NewSegments(payloadLen, segmentSize, overhead, parity int) (s Segments)
  • func (s Segments) AddParity(segs [][]byte) (shards [][]byte, e error)
  • func (s Segments) String() (o string)

Constants

const (
	// Overhead is the base overhead on a packet, use GetOverhead to add any extra
	// as found in a Packet.
	Overhead    = 4 + crypto.PubKeyLen + crypto.CloakLen + nonce.IVLen
	PacketMagic = "rpkt" // todo: this is really not necessary I think.
)

const (
	ErrEmptyBytes      = "cannot encode empty bytes"
	ErrDupe            = "found duplicate packet, no redundancy, decoding failed"
	ErrLostNoRedundant = "no redundancy with %d lost of %d"
	ErrMismatch        = "found disagreement about common data in segment %d of %d" +
		" in field %s value: got %v expected %v"
	ErrNotEnough = "too many lost to recover in section %d, have %d, need " +
		"%d minimum"
)

Errors that can be thrown by methods in this package:

Functions

func EncodePacket

func EncodePacket(ep *PacketParams) (pkt []byte, e error)

EncodePacket creates a Packet, encrypts the payload using the given private from key and the public to key, serializes the form and signs the bytes. the signature to the end.

func GetKeysFromPacket

func GetKeysFromPacket(d []byte) (from *crypto.Pub, to crypto.CloakedPubKey, iv nonce.IV,
	e error)

GetKeysFromPacket returns the ToHeaderPub field of the message in order, checks the packet checksum and recovers the public key.

After this, if the matching private key to the cloaked address returned is found, it is combined with the public key to generate the cipher and the entire packet should then be decrypted, and the DecodePacket function will then decode a OnionSkin.

func SplitToPackets

func SplitToPackets(pp *PacketParams, segSize int,
	ks *crypto.KeySet) (dataShards int, packets [][]byte, e error)

SplitToPackets creates a series of packets including the defined Reed Solomon parameters for extra parity shards and the return encryption public key for a reply.

The last packet that falls short of the segmentSize is padded random bytes.

Types

type Packet

type Packet struct {

	// ID is an internal identifier for this transmission.
	ID nonce.ID

	// Seq specifies the segment number of the message, 4 bytes long.
	Seq uint16

	// Length is the number of segments in the batch
	Length uint32

	// Parity is the ratio of redundancy. The remainder from 256 is the
	// proportion from 256 of data shards in a packet batch.
	Parity byte

	// Data is the message.
	Data []byte

	// TimeStamp is the time at which this message was submitted for dispatch.
	TimeStamp time.Time
}

Packet is the standard format for an encrypted, possibly segmented message container with parameters for Reed Solomon Forward Error Correction.

func DecodePacket

func DecodePacket(d []byte, from *crypto.Pub, to *crypto.Prv,
	iv nonce.IV) (f *Packet, e error)

DecodePacket decodes a packet and return the Packet with encrypted payload and signer's public key. This assumes GetKeysFromPacket succeeded and the matching private key was found.

func (*Packet) GetOverhead

func (p *Packet) GetOverhead() int

GetOverhead returns the packet frame overhead given the settings found in the packet.

type PacketParams

type PacketParams struct {

	// ID is a unique identifier for the packet, internal reference.
	ID nonce.ID

	// To is the public key of the intended recipient of the message.
	To *crypto.Pub

	// From is a private key used by the sender to derive an ECDH shared secret
	// combined with the receiver public key. Conversely, the receiver can generate
	// the same secret using the public key given in the header plus the private key
	// referred to by the cloaked To key.
	//
	// Note that everything below this is encrypted. Each packet has its own unique 16 byte nonce.
	From *crypto.Prv

	// Parity is the ratio out of 1-255 of data that is added to prevent transmission
	// failure as measured and computed by the dispatcher.
	Parity int

	// Seq is the position of the packet in the original ordering of the message for
	// reconstruction.
	Seq int

	// Length is the number of packets in this transmission.
	Length int

	// Data is the payload of this message segment.
	Data []byte
}

PacketParams defines the parameters for creating a ( split) packet given a set of keys, cipher, and data. To, From, Data are required, Parity is optional, set it to define a level of Reed Solomon redundancy on the split packets.

func (PacketParams) GetOverhead

func (ep PacketParams) GetOverhead() int

GetOverhead returns the amount of the message that will not be part of the payload.

type Packets

type Packets []*Packet

Packets is a slice of pointers to packets.

func JoinPackets

func JoinPackets(packets Packets) (pkts Packets, msg []byte, e error)

JoinPackets a collection of Packets together.

func RemovePacket

func RemovePacket(slice Packets, s int) Packets

func (Packets) Len

func (p Packets) Len() int

Len returns the number of packets in a Packets (they are a uniform size so this is 1:1 with the amount of data encoded.

func (Packets) Less

func (p Packets) Less(i, j int) bool

Less implements the sorter interface method for determining the original sequence of messages, as encoded in their sequence number.

func (Packets) Swap

func (p Packets) Swap(i, j int)

Swap is part of the sorter interface implementation that flips the position of two slice elements that fail the Less test and are in ascending relation when they should be descending.

type Segment

type Segment struct {
	DStart, DEnd, PEnd, SLen, Last int
}

Segment is the specification of a segment of a larger message as regards to its position, composition of original or redundant segments, and the size of the last, possibly padded segment of the message.

func (Segment) String

func (s Segment) String() (o string)

String is a printer that produces a Go syntax formatted version of the Segment. For debugging.

type Segments

type Segments []Segment

Segments is a slice of Segment specifying how a message should be packetised for dispatch.

func NewSegments

func NewSegments(payloadLen, segmentSize, overhead, parity int) (s Segments)

func (Segments) AddParity

func (s Segments) AddParity(segs [][]byte) (shards [][]byte, e error)

AddParity adds the expected additional parity segments as specified in the packets.

func (Segments) String

func (s Segments) String() (o string)

String is a printer that produces a Go syntax formatted version of the Segments. For debugging.