capture

package
v1.0.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 8, 2024 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package capture provides the high level / central interface definitions for all slimcap capture sources and core structures. Two Interfaces are supported:

  • Source : The most general definition of methods any capture source must provide
  • SourceZeroCopy : An extended interface definition adding capabilities for zero-copy operations

In addition to the capture source interfaces it provides the most basic implementation of a network packet, including basic interaction methods (e.g. packet length, payload, type, ...).

Index

Constants

View Source
const (

	// PacketHdrOffset denotes the header offset / length for storing information about the packet
	PacketHdrOffset = 6
)

Variables

View Source
var (

	// ErrCaptureStopped denotes that the capture was stopped
	ErrCaptureStopped = errors.New("capture was stopped")

	// ErrCaptureUnblocked denotes that the capture received an unblocking signal
	ErrCaptureUnblocked = errors.New("capture was released / unblocked")
)

Functions

This section is empty.

Types

type IPLayer

type IPLayer []byte

IPLayer denotes the subset of bytes representing an IP layer

func (IPLayer) Protocol

func (i IPLayer) Protocol() byte

Protocol returns the IP layer protocol

func (IPLayer) String

func (i IPLayer) String() (res string)

String returns a human-readable string representation of the packet IP layer

func (IPLayer) Type

func (i IPLayer) Type() byte

Type returns the IP layer type (e.g. IPv4 / IPv6)

type Packet

type Packet []byte

Packet denotes a packet retrieved via the AF_PACKET ring buffer, [Fulfils the capture.Packet interface] [0:1] - Packet Type [1:2] - IP Layer Offset [2:6] - Total packet length

func BuildPacket

func BuildPacket(sip, dip net.IP, sport, dport uint16, proto byte, addPayload []byte, pktType PacketType, totalLen int) (Packet, error)

BuildPacket provides basic capabilities to construct packets (e.g. for testing purposes)

func NewIPPacket

func NewIPPacket(buf Packet, payload []byte, pktType PacketType, totalLen int, ipLayerOffset byte) Packet

NewIPPacket instantiates a new IP packet from a given payload and packet type / length

func (*Packet) IPLayer

func (p *Packet) IPLayer() IPLayer

IPLayer returns the IP layer of the packet (up to snaplen, if set)

func (*Packet) IPLayerOffset

func (p *Packet) IPLayerOffset() byte

IPLayerOffset returns the offset of the IP layer of the packet (w.r.t. its beginning)

func (*Packet) IsInbound

func (p *Packet) IsInbound() bool

IsInbound denotes if the packet is inbound w.r.t. the interface

func (*Packet) Len

func (p *Packet) Len() int

Len returns the actual data length of the packet payload as consumed from the wire (may be truncated due to)

func (*Packet) Payload

func (p *Packet) Payload() []byte

Payload returns the raw payload / network layers of the packet

func (*Packet) TotalLen

func (p *Packet) TotalLen() uint32

TotalLen returnsthe total packet length, including all headers

func (*Packet) Type

func (p *Packet) Type() PacketType

Type denotes the packet type (i.e. the packet direction w.r.t. the interface)

type PacketType

type PacketType = byte

PacketType denotes the packet type (indicating traffic direction) https://github.com/torvalds/linux/blob/master/include/uapi/linux/if_packet.h

const (
	PacketThisHost  PacketType = iota // PacketThisHost : To us (unicast)
	PacketBroadcast                   // PacketBroadcast : To all
	PacketMulticast                   // PacketMulticast : To group
	PacketOtherHost                   // PacketOtherHost : To someone else
	PacketOutgoing                    // PacketOutgoing : Outgoing of any type

	PacketUnknown PacketType = 255 // PacketUnknown : Unknown packet type / direction
)

type Source

type Source interface {

	// NewPacket creates an empty "buffer" packet to be used as destination for the NextPacket() / NextPayload() /
	// NextIPPacket() methods (the latter two by calling .Payload() / .IPLayer() on the created buffer). It ensures
	// that a valid packet of appropriate structure / length is created
	NewPacket() Packet

	// NextPacket receives the next packet from the source and returns it. The operation is blocking. In
	// case a non-nil "buffer" Packet is provided it will be populated with the data (and returned). The
	// buffer packet can be reused. Otherwise a new Packet is allocated.
	NextPacket(pBuf Packet) (Packet, error)

	// NextPayload receives the raw payload of the next packet from the source and returns it. The operation is blocking.
	// In case a non-nil "buffer" byte slice / payload is provided it will be populated with the data (and returned).
	// The buffer can be reused. Otherwise a new byte slice / payload is allocated.
	NextPayload(pBuf []byte) ([]byte, byte, uint32, error)

	// NextIPPacket receives the IP layer of the next packet from the source and returns it. The operation is blocking.
	// In case a non-nil "buffer" IPLayer is provided it will be populated with the data (and returned).
	// The buffer can be reused. Otherwise a new IPLayer is allocated.
	NextIPPacket(pBuf IPLayer) (IPLayer, PacketType, uint32, error)

	// NextPacketFn executes the provided function on the next packet received on the source. If possible, the
	// operation should provide a zero-copy way of interaction with the payload / metadata. All operations on the data
	// must be completed prior to any subsequent call to any Next*() method.
	NextPacketFn(func(payload []byte, totalLen uint32, pktType PacketType, ipLayerOffset byte) error) error

	// Stats returns (and clears) the packet counters of the underlying source
	Stats() (Stats, error)

	// Link returns the underlying link
	Link() *link.Link

	// Unblock ensures that a potentially ongoing blocking poll operation is released (returning an ErrCaptureUnblock from
	// any potentially ongoing call to Next*() that might currently be blocked)
	Unblock() error

	// Close stops / closes the capture source
	Close() error
}

Source denotes a generic packet capture source

type SourceZeroCopy

type SourceZeroCopy interface {

	// NextPayloadZeroCopy receives the raw payload of the next packet from the source and returns it. The operation is blocking.
	// The returned payload provides direct zero-copy access to the underlying data source (e.g. a ring buffer).
	NextPayloadZeroCopy() ([]byte, PacketType, uint32, error)

	// NextIPPacketZeroCopy receives the IP layer of the next packet from the source and returns it. The operation is blocking.
	// The returned IPLayer provides direct zero-copy access to the underlying data source (e.g. a ring buffer).
	NextIPPacketZeroCopy() (IPLayer, PacketType, uint32, error)

	// Wrap generic Source
	Source
}

SourceZeroCopy denotes a generic packet capture source that supports zero-copy operations

type Stats

type Stats struct {
	PacketsReceived uint64
	PacketsDropped  uint64
	QueueFreezes    uint64
}

Stats denotes a packet capture stats structure providing basic counters

Directories

Path Synopsis
Package afpacket implements a capture.Source that allows reading network packets from Linux network interfaces via the AF_PACKET mechanism.
Package afpacket implements a capture.Source that allows reading network packets from Linux network interfaces via the AF_PACKET mechanism.
afring
Package afring implements a capture.Source and a capture.SourceZeroCopy that allows reading network packets from Linux network interfaces via the AF_PACKET / TPacket ring buffer mechanism.
Package afring implements a capture.Source and a capture.SourceZeroCopy that allows reading network packets from Linux network interfaces via the AF_PACKET / TPacket ring buffer mechanism.
socket
Package socket implements AF_PACKET sockets / file descriptors (both for `afring` and plain `afpacket` modes).
Package socket implements AF_PACKET sockets / file descriptors (both for `afring` and plain `afpacket` modes).
Package pcap allows reading / parsing pcap files (compressed and uncompressed) and implement the capture.Source interface.
Package pcap allows reading / parsing pcap files (compressed and uncompressed) and implement the capture.Source interface.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL