pcap

Documentation

Overview

Package pcap allows reading / parsing pcap files (compressed and uncompressed) and implement the capture.Source interface. Consequently, an instance can act as network capture source, allowing to replay network traffic previously captured elsewhere. In addition, the pcap package acts as main facilitaty for testing (since it allows to mimic a live network traffic capture without the need for privileged access and / or actual network interfaces).

Index

• Constants
• type Header
  • func (h Header) SwapEndianess() Header
• type PacketHeader
  • func (h PacketHeader) SwapEndianess() PacketHeader
• type Source
  • func NewSource(iface string, r io.Reader) (*Source, error)
  • func NewSourceFromFile(path string) (*Source, error)
  • func (s *Source) Close() error
  • func (s *Source) Link() *link.Link
  • func (s *Source) NewPacket() capture.Packet
  • func (s *Source) NextIPPacket(pBuf capture.IPLayer) (capture.IPLayer, capture.PacketType, uint32, error)
  • func (s *Source) NextPacket(pBuf capture.Packet) (capture.Packet, error)
  • func (s *Source) NextPacketFn(...) error
  • func (s *Source) NextPayload(pBuf []byte) ([]byte, capture.PacketType, uint32, error)
  • func (s *Source) PacketAddCallbackFn(fn func(payload []byte, totalLen uint32, pktType, ipLayerOffset byte)) *Source
  • func (s *Source) Stats() (capture.Stats, error)
  • func (s *Source) Unblock() error

Constants

const (
	HeaderSize       = 24 // HeaderSize : Overall in-memory size of the main pcap file header
	PacketHeaderSize = 16 // PacketHeaderSize : I-memory size of the packet specific header

	MagicNativeEndianess  = uint32(0xa1b2c3d4) // MagicNativeEndianess : endianess of local system
	MagicSwappedEndianess = uint32(0xd4c3b2a1) // MagicSwappedEndianess : endianess of non-local / swapped system
)

Types

type Header

type Header struct {
	MagicNumber  uint32
	VersionMajor uint16
	VersionMinor uint16
	Thiszone     int32
	Sigfigs      uint32
	Snaplen      uint32
	Network      uint32
}

Header denotes the main pcap file header: https://wiki.wireshark.org/Development/LibpcapFileFormat

func (Header) SwapEndianess

func (h Header) SwapEndianess() Header

SwapEndianess switches / swaps the endianess of the header

type PacketHeader

type PacketHeader struct {
	TSSec       int32
	TSUsec      int32
	CaptureLen  int32
	OriginalLen int32
}

PacketHeader denotes the packet specific header: https://wiki.wireshark.org/Development/LibpcapFileFormat

func (PacketHeader) SwapEndianess

func (h PacketHeader) SwapEndianess() PacketHeader

SwapEndianess switches / swaps the endianess of the packet specific header

type Source

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

Source denotes a pcap file capture source

func NewSource

func NewSource(iface string, r io.Reader) (*Source, error)

NewSource instantiates a new pcap file capture source based on any io.Reader

func NewSourceFromFile

func NewSourceFromFile(path string) (*Source, error)

NewSourceFromFile instantiates a new pcap file capture source based on a file name

func (*Source) Close

func (s *Source) Close() error

Close stops / closes the capture source

func (*Source) Link

func (s *Source) Link() *link.Link

Link returns the underlying link

func (*Source) NewPacket

func (s *Source) NewPacket() capture.Packet

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

func (*Source) NextIPPacket

func (s *Source) NextIPPacket(pBuf capture.IPLayer) (capture.IPLayer, capture.PacketType, 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.

func (*Source) NextPacket

func (s *Source) NextPacket(pBuf capture.Packet) (capture.Packet, error)

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.

func (*Source) NextPacketFn

func (s *Source) NextPacketFn(fn func(payload []byte, totalLen uint32, pktType capture.PacketType, ipLayerOffset byte) error) 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.

func (*Source) NextPayload

func (s *Source) NextPayload(pBuf []byte) ([]byte, capture.PacketType, uint32, 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.

func (*Source) PacketAddCallbackFn

func (s *Source) PacketAddCallbackFn(fn func(payload []byte, totalLen uint32, pktType, ipLayerOffset byte)) *Source

PacketAddCallbackFn provides an optional callback function that is called when a packet is added to the mock source (e.g. to build a reference for comparison)

func (*Source) Stats

func (s *Source) Stats() (capture.Stats, error)

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

func (*Source) Unblock

func (s *Source) Unblock() error

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)