protocol

package
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Aug 12, 2024 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package protocol enables Lucius to uniformly query and mutate network packets containing various protocols.

The package registers a parser with the Lucius forwarding infrastructure. The parser describes the type of packets that it accepts (network protocols and their relative ordering).

The package also provides utilities to implement network protocols. Each network protocol is implemented in its own package. They implement the interface protocol.Handler and register (optional) parse and add functions with package protocol.

The supported protocol are: Ethernet (with VLAN tags), IP4, IP6, GRE (with Key and Sequence numbers), ARP, ICMP, TCP, UDP. It also supports recursive IP tunnels such as IPv6-over-IPv4-over-GRE-over-IPv6.

Index

Constants

View Source 
const (
	SizeUint64 = 8
	SizeUint32 = 4
	SizeUint24 = 3
	SizeUint16 = 2
	SizeUint8  = 1
	SizeMAC    = 6
	SizeIP4    = SizeUint32
	SizeIP6    = 16
)

Sizes of various attribute types in bytes.

Variables

View Source 
var FieldAttr = map[fwdpb.PacketFieldNum]struct {
	Sizes       []int                   // discrete valid sizes
	DefaultSize int                     // default size computed from Sizes in init
	Group       fwdpb.PacketHeaderGroup // header group containing this field computed in init
}{
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_PACKET_LENGTH: {
		Sizes: []int{SizeUint64},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_PACKET_PORT_INPUT: {
		Sizes: []int{SizeUint64},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_PACKET_PORT_OUTPUT: {
		Sizes: []int{SizeUint64},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_PACKET_VRF: {
		Sizes: []int{SizeUint64},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_PACKET_ATTRIBUTE_32: {
		Sizes: []int{SizeUint32},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_PACKET_ATTRIBUTE_24: {
		Sizes: []int{SizeUint24},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_PACKET_ATTRIBUTE_16: {
		Sizes: []int{SizeUint16},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_PACKET_ATTRIBUTE_8: {
		Sizes: []int{SizeUint8},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_ETHER_MAC_SRC: {
		Sizes: []int{SizeMAC},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_ETHER_MAC_DST: {
		Sizes: []int{SizeMAC},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_VLAN_TAG: {
		Sizes: []int{SizeUint16},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_VLAN_PRIORITY: {
		Sizes: []int{SizeUint16},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_ETHER_TYPE: {
		Sizes: []int{SizeUint16},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_IP_VERSION: {
		Sizes: []int{SizeUint8},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_IP_ADDR_SRC: {
		Sizes: []int{SizeIP4, SizeIP6},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_IP_ADDR_DST: {
		Sizes: []int{SizeIP4, SizeIP6},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_IP_PROTO: {
		Sizes: []int{SizeUint8},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_IP_HOP: {
		Sizes: []int{SizeUint8},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_IP_QOS: {

		Sizes: []int{SizeUint32},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_IP6_FLOW: {

		Sizes: []int{SizeUint32},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_ICMP_TYPE: {
		Sizes: []int{SizeUint8},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_ICMP_CODE: {
		Sizes: []int{SizeUint8},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_ICMP6_ND_SLL: {
		Sizes: []int{SizeMAC},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_ICMP6_ND_TLL: {
		Sizes: []int{SizeMAC},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_ICMP6_ND_TARGET: {
		Sizes: []int{SizeIP6},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_L4_PORT_SRC: {
		Sizes: []int{SizeUint16},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_L4_PORT_DST: {
		Sizes: []int{SizeUint16},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_TCP_FLAGS: {
		Sizes: []int{SizeUint16},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_ARP_TPA: {
		Sizes: []int{SizeUint32},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_ARP_SPA: {
		Sizes: []int{SizeUint32},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_GRE_KEY: {
		Sizes: []int{SizeUint32},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_ARP_TMAC: {
		Sizes: []int{SizeMAC},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_ARP_SMAC: {
		Sizes: []int{SizeMAC},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_GRE_SEQUENCE: {
		Sizes: []int{SizeUint32},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_NEXT_HOP_IP: {
		Sizes: []int{SizeIP4, SizeIP6},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_NEXT_HOP_ID: {
		Sizes: []int{SizeUint64},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_NEXT_HOP_GROUP_ID: {
		Sizes: []int{SizeUint64},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_TRAP_ID: {
		Sizes: []int{SizeUint64},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_INPUT_IFACE: {
		Sizes: []int{SizeUint64},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_OUTPUT_IFACE: {
		Sizes: []int{SizeUint64},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_TUNNEL_ID: {
		Sizes: []int{SizeUint64},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_HOST_PORT_ID: {
		Sizes: []int{SizeUint64},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_L2MC_GROUP_ID: {
		Sizes: []int{SizeUint64},
	},
	fwdpb.PacketFieldNum_PACKET_FIELD_NUM_POLICER_ID: {
		Sizes: []int{SizeUint64},
	},
}

FieldAttr contains attributes for each packet field indexed by the field number. Each field has a valid size described as a discrete set of sizes.

FieldAttr is fully initialized by init routines and is logically constant after init.

View Source 
var GroupAttr = map[fwdpb.PacketHeaderGroup]struct {
	Position int                    // position of the group within a frame
	headers  []fwdpb.PacketHeaderId // headers in the group
	fields   []fwdpb.PacketFieldNum // packet fields that can be queried in this group
}{
	fwdpb.PacketHeaderGroup_PACKET_HEADER_GROUP_PACKET: {
		Position: 0,
		// contains filtered or unexported fields
	},
	fwdpb.PacketHeaderGroup_PACKET_HEADER_GROUP_L2: {
		Position: 1,
		// contains filtered or unexported fields
	},
	fwdpb.PacketHeaderGroup_PACKET_HEADER_GROUP_L3: {
		Position: 2,
		// contains filtered or unexported fields
	},
	fwdpb.PacketHeaderGroup_PACKET_HEADER_GROUP_L4: {
		Position: 3,
		// contains filtered or unexported fields
	},
	fwdpb.PacketHeaderGroup_PACKET_HEADER_GROUP_PAYLOAD: {
		Position: 4,
		// contains filtered or unexported fields
	},
}

GroupAttr contains attributes for each packet header group.

Each packet header group is associated with a set of packet headers and a set of packet fields that may be present in the group.

Each packet header group is also given a position relative to other packet header groups within the packet.

GroupAttr is logically constant and should not be changed.

View Source 
var HeaderAttr = map[fwdpb.PacketHeaderId]struct {
	Parse parseFn                 // registered function to parse the header
	Add   addFn                   // registered function to add the header
	Group fwdpb.PacketHeaderGroup // computed group of the header
}{}

HeaderAttr contains attributes for packet headers indexed by the header id.

HeaderAttr is fully initialized by init routines and is logically constant after init.

View Source 
var Sequence []fwdpb.PacketHeaderGroup

Sequence is the sequence of packet header groups used to reconstruct a frame. Each group can occur exactly once in the sequence.

Sequence is computed during initialization and is logically constnant and should not be changed after init.

Functions

func Register 

func Register(id fwdpb.PacketHeaderId, parse parseFn, add addFn)

Register registers handlers to add and parse a packet header.

func UDF 

func UDF(h frame.Header, id fwdpacket.FieldID) frame.Field

UDF returns a field as specified by a user defined field (UDF).

Types

type Desc 

type Desc struct {
	Packet *Packet // Reference to the packet.
	// contains filtered or unexported fields
}

A Desc is a set of attributes that describe a network protocol in a packet. The desc in the packet are maintained in a doubly linked list in the order in which they occur within the packet. By default, all protocol headers are marked as clean.

func (*Desc) Dirty 

func (d *Desc) Dirty() bool

Dirty returns true if the header is dirty.

func (*Desc) EnvelopeDesc 

func (d *Desc) EnvelopeDesc() *Desc

EnvelopeDesc returns the envelope's desc.

func (*Desc) EnvelopeID 

func (d *Desc) EnvelopeID() fwdpb.PacketHeaderId

EnvelopeID returns the encapsulator's header id. The envelope of a desc is the header of the last instance of the preceding desc.

func (*Desc) MarkDirty 

func (d *Desc) MarkDirty(dirty bool)

MarkDirty marks the header as dirty or clean.

func (*Desc) Payload 

func (d *Desc) Payload() []byte

Payload returns the payload. The payload of a desc is represented by the set of all subsequent desc in the packet. handlers are rebuilt and the header and trailer bytes of each protocol handler is combined to form the frame. All headers are marked as clean after being rebuilt.

func (*Desc) PayloadDesc 

func (d *Desc) PayloadDesc() *Desc

PayloadDesc returns the payload's desc.

func (*Desc) PayloadID 

func (d *Desc) PayloadID() fwdpb.PacketHeaderId

PayloadID returns the payload's header id. The payload of a desc is the header of the first instance of the succeeding desc.

func (*Desc) PayloadLength 

func (d *Desc) PayloadLength() int

PayloadLength returns the length of the payload of a protocol in the packet. The payload of a desc is represented by the set of all subsequent desc in the packet (header and trailer).

type Handler 

type Handler interface {
	// Header returns bytes of the current protocol header.
	Header() []byte

	// Trailer returns the trailing bytes of the current protocol header.
	// This is typically used for padding or trailing CRC.
	Trailer() []byte

	// ID returns the protocol header ID of the specified instance.
	ID(instance int) fwdpb.PacketHeaderId

	// Field finds the field specified by id.
	Field(id fwdpacket.FieldID) ([]byte, error)

	// UpdateField updates the field specified by id. The type of update
	// is determined by op using the constants defined in fwdpacket.
	// It returns true if the update dirties the header.
	UpdateField(id fwdpacket.FieldID, op int, arg []byte) (bool, error)

	// Remove removes the protocol header specified by id from the
	// current header.
	Remove(id fwdpb.PacketHeaderId) error

	// Modify extends the current header with the header specified
	// by id.
	Modify(id fwdpb.PacketHeaderId) error

	// Rebuild rebuilds the current header
	Rebuild() error
}

A Handler encapsulates a protocol header, providing methods to query and mutate it. Note that some protocol headers are complex i.e they can have multiple instances of themselves (IP-IP tunnels) or can be composed of multiple headers (ethernet with vlans).

type Packet 

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

A Packet is a network packet that can be queried and manipulated. A packet is created by parsing a frame to create a chain of headers.

func NewPacket 

func NewPacket(start fwdpb.PacketHeaderId, frame *frame.Frame) (*Packet, error)

NewPacket parses a frame into a Packet and returns it.

func (*Packet) Attributes 

func (p *Packet) Attributes() fwdattribute.Set

Attributes returns the attributes associated with the packet.

func (*Packet) Debug 

func (p *Packet) Debug(enable bool)

Debug controls debugging for the packet.

func (*Packet) Decap 

func (p *Packet) Decap(id fwdpb.PacketHeaderId) error

Decap removes the header specified by id. The header is marked as dirty.

func (*Packet) Encap 

func (p *Packet) Encap(id fwdpb.PacketHeaderId) error

Encap adds a Header specified by id. If a header already exists in the header-group, then the existing header is modified. The header being added or updated is always marked as dirty.

func (*Packet) Field 

func (p *Packet) Field(id fwdpacket.FieldID) ([]byte, error)

Field returns the bytes associated with a field ID.

func (*Packet) Frame 

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

Frame returns the packet's frame as a slice of bytes. The full frame of the packet is the payload of the first header which is METADATA by default.

func (*Packet) Length 

func (p *Packet) Length() int

Length returns the number of bytes in the packet.

func (*Packet) Log 

func (p *Packet) Log() logr.Logger

Log returns a logger.

func (*Packet) LogMsgs added in v0.4.0 

func (p *Packet) LogMsgs() []string

LogMsgs returns the log messages for the packet.

func (*Packet) Mirror 

func (p *Packet) Mirror(fields []fwdpacket.FieldID) (fwdpacket.Packet, error)

Mirror creates a new packet from the current packet. By default the metadata fields are lost. Additional fields specified during the mirror ensures that the field values are copied from the old packet to the new packet. This can be used to retain metadata field values across a mirror.

func (*Packet) OverrideGlobalLogLevel added in v0.4.0 

func (p *Packet) OverrideGlobalLogLevel()

OverrideGlobalLogLevel override the set by -v and logs all messages.

func (*Packet) Reparse 

func (p *Packet) Reparse(id fwdpb.PacketHeaderId, fields []fwdpacket.FieldID, prepend []byte) error

Reparse reparses the current packet to start from the specified packet header id. Note that by default reparsing creates a new packet, so metadata fields will be lost. Additional fields specified during reparsing ensures that the field values are copied from the old packet to the new packet. This can be used to retain metadata field values across a packet reparse. It can also prepend a slice of bytes to the rebuilt packet before reparsing.

func (*Packet) StartHeader 

func (p *Packet) StartHeader() fwdpb.PacketHeaderId

StartHeader returns the start header of the packet.

func (*Packet) String 

func (p *Packet) String() string

String returns a string representation of the packet.

func (*Packet) Update 

func (p *Packet) Update(id fwdpacket.FieldID, op int, arg []byte) error

Update updates a field in the packet.

Source Files

View all Source files

Directories

Path Synopsis
Package arp implements the ARP header.
 Package arp implements the ARP header.
Package ethernet implements the Ethernet header.
 Package ethernet implements the Ethernet header.
Package icmp implements the ICMP header support in Lucius.
 Package icmp implements the ICMP header support in Lucius.
Package ip handles the IP L3 portion of the packet.
 Package ip handles the IP L3 portion of the packet.
Package metadata implements the metadata packet header.
 Package metadata implements the metadata packet header.
Package opaque implements the opaque packet header.
 Package opaque implements the opaque packet header.
Package packettestutil contains a set of routines used to test the processing of packet headers and fields.
 Package packettestutil contains a set of routines used to test the processing of packet headers and fields.
Package tcp implements the TCP header support in Lucius.
 Package tcp implements the TCP header support in Lucius.
Package udp implements the UDP header support in Lucius.
 Package udp implements the UDP header support in Lucius.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.