net: golang.org/x/net/bpf Index | Files

package bpf

import "golang.org/x/net/bpf"

Package bpf implements marshaling and unmarshaling of programs for the Berkeley Packet Filter virtual machine.

BPF's main use is to specify a packet filter for network taps, so that the kernel doesn't have to expensively copy every packet it sees to userspace. However, it's been repurposed to other areas where running user code in-kernel is needed. For example, Linux's seccomp uses BPF to apply security policies to system calls. For simplicity, this documentation refers only to packets, but other uses of BPF have their own data payloads.

BPF programs run in a restricted virtual machine. It has almost no access to kernel functions, and while conditional branches are allowed, they can only jump forwards, to guarantee that there are no infinite loops.

The virtual machine

The BPF VM is an accumulator machine. Its main register, called register A, is an implicit source and destination in all arithmetic and logic operations. The machine also has 16 scratch registers for temporary storage, and an indirection register (register X) for indirect memory access. All registers are 32 bits wide.

Each run of a BPF program is given one packet, which is placed in the VM's read-only "main memory". LoadAbsolute and LoadIndirect instructions can fetch up to 32 bits at a time into register A for examination.

The goal of a BPF program is to produce and return a verdict (uint32), which tells the kernel what to do with the packet. In the context of packet filtering, the returned value is the number of bytes of the packet to forward to userspace, or 0 to ignore the packet. Other contexts like seccomp define their own return values.

In order to simplify programs, attempts to read past the end of the packet terminate the program execution with a verdict of 0 (ignore packet). This means that the vast majority of BPF programs don't need to do any explicit bounds checking.

In addition to the bytes of the packet, some BPF programs have access to extensions, which are essentially calls to kernel utility functions. Currently, the only extensions supported by this package are the Linux packet filter extensions.

Examples

This packet filter selects all ARP packets.

bpf.Assemble([]bpf.Instruction{
	// Load "EtherType" field from the ethernet header.
	bpf.LoadAbsolute{Off: 12, Size: 2},
	// Skip over the next instruction if EtherType is not ARP.
	bpf.JumpIf{Cond: bpf.JumpNotEqual, Val: 0x0806, SkipTrue: 1},
	// Verdict is "send up to 4k of the packet to userspace."
	bpf.RetConstant{Val: 4096},
	// Verdict is "ignore packet."
	bpf.RetConstant{Val: 0},
})

This packet filter captures a random 1% sample of traffic.

bpf.Assemble([]bpf.Instruction{
	// Get a 32-bit random number from the Linux kernel.
	bpf.LoadExtension{Num: bpf.ExtRand},
	// 1% dice roll?
	bpf.JumpIf{Cond: bpf.JumpLessThan, Val: 2^32/100, SkipFalse: 1},
	// Capture.
	bpf.RetConstant{Val: 4096},
	// Ignore.
	bpf.RetConstant{Val: 0},
})

Index

Package Files

asm.go constants.go doc.go instructions.go

func Assemble

func Assemble(insts []Instruction) ([]RawInstruction, error)

Assemble converts insts into raw instructions suitable for loading into a BPF virtual machine.

Currently, no optimization is attempted, the assembled program flow is exactly as provided.

func Disassemble

func Disassemble(raw []RawInstruction) (insts []Instruction, allDecoded bool)

Disassemble attempts to parse raw back into Instructions. Unrecognized RawInstructions are assumed to be an extension not implemented by this package, and are passed through unchanged to the output. The allDecoded value reports whether insts contains no RawInstructions.

type ALUOp

type ALUOp uint16

An ALUOp is an arithmetic or logic operation.

const (
    ALUOpAdd ALUOp = iota << 4
    ALUOpSub
    ALUOpMul
    ALUOpDiv
    ALUOpOr
    ALUOpAnd
    ALUOpShiftLeft
    ALUOpShiftRight

    ALUOpMod
    ALUOpXor
)

ALU binary operation types.

type ALUOpConstant

type ALUOpConstant struct {
    Op  ALUOp
    Val uint32
}

ALUOpConstant executes A = A <Op> Val.

func (ALUOpConstant) Assemble

func (a ALUOpConstant) Assemble() (RawInstruction, error)

Assemble implements the Instruction Assemble method.

type ALUOpX

type ALUOpX struct {
    Op ALUOp
}

ALUOpX executes A = A <Op> X

func (ALUOpX) Assemble

func (a ALUOpX) Assemble() (RawInstruction, error)

Assemble implements the Instruction Assemble method.

type Extension

type Extension int

An Extension is a function call provided by the kernel that performs advanced operations that are expensive or impossible within the BPF virtual machine.

Extensions are only implemented by the Linux kernel.

TODO: should we prune this list? Some of these extensions seem either broken or near-impossible to use correctly, whereas other (len, random, ifindex) are quite useful.

const (
    // ExtLen returns the length of the packet.
    ExtLen Extension = 1
    // ExtProto returns the packet's L3 protocol type.
    ExtProto = 0
    // ExtType returns the packet's type (skb->pkt_type in the kernel)
    //
    // TODO: better documentation. How nice an API do we want to
    // provide for these esoteric extensions?
    ExtType = 4
    // ExtPayloadOffset returns the offset of the packet payload, or
    // the first protocol header that the kernel does not know how to
    // parse.
    ExtPayloadOffset = 52
    // ExtInterfaceIndex returns the index of the interface on which
    // the packet was received.
    ExtInterfaceIndex = 8
    // ExtNetlinkAttr returns the netlink attribute of type X at
    // offset A.
    ExtNetlinkAttr = 12
    // ExtNetlinkAttrNested returns the nested netlink attribute of
    // type X at offset A.
    ExtNetlinkAttrNested = 16
    // ExtMark returns the packet's mark value.
    ExtMark = 20
    // ExtQueue returns the packet's assigned hardware queue.
    ExtQueue = 24
    // ExtLinkLayerType returns the packet's hardware address type
    // (e.g. Ethernet, Infiniband).
    ExtLinkLayerType = 28
    // ExtRXHash returns the packets receive hash.
    //
    // TODO: figure out what this rxhash actually is.
    ExtRXHash = 32
    // ExtCPUID returns the ID of the CPU processing the current
    // packet.
    ExtCPUID = 36
    // ExtVLANTag returns the packet's VLAN tag.
    ExtVLANTag = 44
    // ExtVLANTagPresent returns non-zero if the packet has a VLAN
    // tag.
    //
    // TODO: I think this might be a lie: it reads bit 0x1000 of the
    // VLAN header, which changed meaning in recent revisions of the
    // spec - this extension may now return meaningless information.
    ExtVLANTagPresent = 48
    // ExtVLANProto returns 0x8100 if the frame has a VLAN header,
    // 0x88a8 if the frame has a "Q-in-Q" double VLAN header, or some
    // other value if no VLAN information is present.
    ExtVLANProto = 60
    // ExtRand returns a uniformly random uint32.
    ExtRand = 56
)

Extension functions available in the Linux kernel.

type Instruction

type Instruction interface {
    // Assemble assembles the Instruction into a RawInstruction.
    Assemble() (RawInstruction, error)
}

An Instruction is one instruction executed by the BPF virtual machine.

type Jump

type Jump struct {
    Skip uint32
}

Jump skips the following Skip instructions in the program.

func (Jump) Assemble

func (a Jump) Assemble() (RawInstruction, error)

Assemble implements the Instruction Assemble method.

type JumpIf

type JumpIf struct {
    Cond      JumpTest
    Val       uint32
    SkipTrue  uint8
    SkipFalse uint8
}

JumpIf skips the following Skip instructions in the program if A <Cond> Val is true.

func (JumpIf) Assemble

func (a JumpIf) Assemble() (RawInstruction, error)

Assemble implements the Instruction Assemble method.

type JumpTest

type JumpTest uint16

A JumpTest is a comparison operator used in conditional jumps.

const (
    // K == A
    JumpEqual JumpTest = iota
    // K != A
    JumpNotEqual
    // K > A
    JumpGreaterThan
    // K < A
    JumpLessThan
    // K >= A
    JumpGreaterOrEqual
    // K <= A
    JumpLessOrEqual
    // K & A != 0
    JumpBitsSet
    // K & A == 0
    JumpBitsNotSet
)

Supported operators for conditional jumps.

type LoadAbsolute

type LoadAbsolute struct {
    Off  uint32
    Size int // 1, 2 or 4
}

LoadAbsolute loads packet[Off:Off+Size] as an integer value into register A.

func (LoadAbsolute) Assemble

func (a LoadAbsolute) Assemble() (RawInstruction, error)

Assemble implements the Instruction Assemble method.

type LoadConstant

type LoadConstant struct {
    Dst Register
    Val uint32
}

LoadConstant loads Val into register Dst.

func (LoadConstant) Assemble

func (a LoadConstant) Assemble() (RawInstruction, error)

Assemble implements the Instruction Assemble method.

type LoadExtension

type LoadExtension struct {
    Num Extension
}

LoadExtension invokes a linux-specific extension and stores the result in register A.

func (LoadExtension) Assemble

func (a LoadExtension) Assemble() (RawInstruction, error)

Assemble implements the Instruction Assemble method.

type LoadIndirect

type LoadIndirect struct {
    Off  uint32
    Size int // 1, 2 or 4
}

LoadIndirect loads packet[X+Off:X+Off+Size] as an integer value into register A.

func (LoadIndirect) Assemble

func (a LoadIndirect) Assemble() (RawInstruction, error)

Assemble implements the Instruction Assemble method.

type LoadMemShift

type LoadMemShift struct {
    Off uint32
}

LoadMemShift multiplies the first 4 bits of the byte at packet[Off] by 4 and stores the result in register X.

This instruction is mainly useful to load into X the length of an IPv4 packet header in a single instruction, rather than have to do the arithmetic on the header's first byte by hand.

func (LoadMemShift) Assemble

func (a LoadMemShift) Assemble() (RawInstruction, error)

Assemble implements the Instruction Assemble method.

type LoadScratch

type LoadScratch struct {
    Dst Register
    N   int // 0-15
}

LoadScratch loads scratch[N] into register Dst.

func (LoadScratch) Assemble

func (a LoadScratch) Assemble() (RawInstruction, error)

Assemble implements the Instruction Assemble method.

type NegateA

type NegateA struct{}

NegateA executes A = -A.

func (NegateA) Assemble

func (a NegateA) Assemble() (RawInstruction, error)

Assemble implements the Instruction Assemble method.

type RawInstruction

type RawInstruction struct {
    // Operation to execute.
    Op  uint16
    // For conditional jump instructions, the number of instructions
    // to skip if the condition is true/false.
    Jt  uint8
    Jf  uint8
    // Constant parameter. The meaning depends on the Op.
    K   uint32
}

A RawInstruction is a raw BPF virtual machine instruction.

func (RawInstruction) Assemble

func (ri RawInstruction) Assemble() (RawInstruction, error)

Assemble implements the Instruction Assemble method.

func (RawInstruction) Disassemble

func (ri RawInstruction) Disassemble() Instruction

Disassemble parses ri into an Instruction and returns it. If ri is not recognized by this package, ri itself is returned.

type Register

type Register uint16

A Register is a register of the BPF virtual machine.

const (
    // RegA is the accumulator register. RegA is always the
    // destination register of ALU operations.
    RegA Register = iota
    // RegX is the indirection register, used by LoadIndirect
    // operations.
    RegX
)

type RetA

type RetA struct{}

RetA exits the BPF program, returning the value of register A.

func (RetA) Assemble

func (a RetA) Assemble() (RawInstruction, error)

Assemble implements the Instruction Assemble method.

type RetConstant

type RetConstant struct {
    Val uint32
}

RetConstant exits the BPF program, returning a constant value.

func (RetConstant) Assemble

func (a RetConstant) Assemble() (RawInstruction, error)

Assemble implements the Instruction Assemble method.

type StoreScratch

type StoreScratch struct {
    Src Register
    N   int // 0-15
}

StoreScratch stores register Src into scratch[N].

func (StoreScratch) Assemble

func (a StoreScratch) Assemble() (RawInstruction, error)

Assemble implements the Instruction Assemble method.

type TAX

type TAX struct{}

TAX copies the value of register A to register X.

func (TAX) Assemble

func (a TAX) Assemble() (RawInstruction, error)

Assemble implements the Instruction Assemble method.

type TXA

type TXA struct{}

TXA copies the value of register X to register A.

func (TXA) Assemble

func (a TXA) Assemble() (RawInstruction, error)

Assemble implements the Instruction Assemble method.

Package bpf imports 1 packages (graph). Updated 6 days ago. Refresh now. Tools for package owners.