fragmentation

Documentation

Overview

Package fragmentation contains the implementation of IP fragmentation. It is based on RFC 791, RFC 815 and RFC 8200.

Index

• Constants
• Variables
• type FragmentID
• type Fragmentation
  • func NewFragmentation(blockSize uint16, highMemoryLimit, lowMemoryLimit int, ...) *Fragmentation
  • func (f *Fragmentation) Process(id FragmentID, first, last uint16, more bool, proto uint8, ...) (*stack.PacketBuffer, uint8, bool, error)
• type PacketFragmenter
  • func MakePacketFragmenter(pkt *stack.PacketBuffer, fragmentPayloadLen uint32, reserve int) PacketFragmenter
  • func (pf *PacketFragmenter) BuildNextFragment() (*stack.PacketBuffer, int, int, bool)
  • func (pf *PacketFragmenter) RemainingFragmentCount() int
• type TimeoutHandler

Constants

const (
	// HighFragThreshold is the threshold at which we start trimming old
	// fragmented packets. Linux uses a default value of 4 MB. See
	// net.ipv4.ipfrag_high_thresh for more information.
	HighFragThreshold = 4 << 20 // 4MB

	// LowFragThreshold is the threshold we reach to when we start dropping
	// older fragmented packets. It's important that we keep enough room for newer
	// packets to be re-assembled. Hence, this needs to be lower than
	// HighFragThreshold enough. Linux uses a default value of 3 MB. See
	// net.ipv4.ipfrag_low_thresh for more information.
	LowFragThreshold = 3 << 20 // 3MB

)

Variables

var (
	// ErrInvalidArgs indicates to the caller that an invalid argument was
	// provided.
	ErrInvalidArgs = errors.New("invalid args")

	// ErrFragmentOverlap indicates that, during reassembly, a fragment overlaps
	// with another one.
	ErrFragmentOverlap = errors.New("overlapping fragments")

	// ErrFragmentConflict indicates that, during reassembly, some fragments are
	// in conflict with one another.
	ErrFragmentConflict = errors.New("conflicting fragments")
)

Types

type FragmentID

type FragmentID struct {
	// Source is the source address of the fragment.
	Source tcpip.Address

	// Destination is the destination address of the fragment.
	Destination tcpip.Address

	// ID is the identification value of the fragment.
	//
	// This is a uint32 because IPv6 uses a 32-bit identification value.
	ID uint32

	// The protocol for the packet.
	Protocol uint8
}

FragmentID is the identifier for a fragment.

type Fragmentation

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

Fragmentation is the main structure that other modules of the stack should use to implement IP Fragmentation.

func NewFragmentation

func NewFragmentation(blockSize uint16, highMemoryLimit, lowMemoryLimit int, reassemblingTimeout time.Duration, clock tcpip.Clock, timeoutHandler TimeoutHandler) *Fragmentation

NewFragmentation creates a new Fragmentation.

blockSize specifies the fragment block size, in bytes.

highMemoryLimit specifies the limit on the memory consumed by the fragments stored by Fragmentation (overhead of internal data-structures is not accounted). Fragments are dropped when the limit is reached.

lowMemoryLimit specifies the limit on which we will reach by dropping fragments after reaching highMemoryLimit.

reassemblingTimeout specifies the maximum time allowed to reassemble a packet. Fragments are lazily evicted only when a new a packet with an already existing fragmentation-id arrives after the timeout.

func (*Fragmentation) Process

func (f *Fragmentation) Process(
	id FragmentID, first, last uint16, more bool, proto uint8, pkt *stack.PacketBuffer) (
	*stack.PacketBuffer, uint8, bool, error)

Process processes an incoming fragment belonging to an ID and returns a complete packet and its protocol number when all the packets belonging to that ID have been received.

[first, last] is the range of the fragment bytes.

first must be a multiple of the block size f is configured with. The size of the fragment data must be a multiple of the block size, unless there are no fragments following this fragment (more set to false).

proto is the protocol number marked in the fragment being processed. It has to be given here outside of the FragmentID struct because IPv6 should not use the protocol to identify a fragment.

type PacketFragmenter

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

PacketFragmenter is the book-keeping struct for packet fragmentation.

func MakePacketFragmenter

func MakePacketFragmenter(pkt *stack.PacketBuffer, fragmentPayloadLen uint32, reserve int) PacketFragmenter

MakePacketFragmenter prepares the struct needed for packet fragmentation.

pkt is the packet to be fragmented.

fragmentPayloadLen is the maximum number of bytes of fragmentable data a fragment can have.

reserve is the number of bytes that should be reserved for the headers in each generated fragment.

func (*PacketFragmenter) BuildNextFragment

func (pf *PacketFragmenter) BuildNextFragment() (*stack.PacketBuffer, int, int, bool)

BuildNextFragment returns a packet with the payload of the next fragment, along with the fragment's offset, the number of bytes copied and a boolean indicating if there are more fragments left or not. If this function is called again after it indicated that no more fragments were left, it will panic.

Note that the returned packet will not have its network and link headers populated, but space for them will be reserved. The transport header will be stored in the packet's data.

func (*PacketFragmenter) RemainingFragmentCount

func (pf *PacketFragmenter) RemainingFragmentCount() int

RemainingFragmentCount returns the number of fragments left to be built.

type TimeoutHandler

type TimeoutHandler interface {
	// OnReassemblyTimeout will be called with the first fragment (or nil, if the
	// first fragment has not been received) of a packet whose reassembly has
	// timed out.
	OnReassemblyTimeout(pkt *stack.PacketBuffer)
}

TimeoutHandler is consulted if a packet reassembly has timed out.