Documentation
¶
Overview ¶
Package ebpf provides an eBPF-based IPv4 IPID tagger for Linux.
The eBPF program (tagger.c) is compiled at build time into a Go byte-slice via bpf2go and loaded at runtime via cilium/ebpf. It attaches to the TC egress hook on a named network interface.
Key architecture:
- The Go side updates a BPF hash map with the current per-measurement authentication key (ak) at each epoch boundary, and reports the epoch whose key the map may still hold to the key schedule, which withholds that key from disclosure.
- The eBPF program reads ak from the map, computes the debuglet-tag-v1 tag (docs/tag-spec.md, tesla.TagSpec) over the packet's canonical input, writes it into the IPv4 IPID field and sets DF, updating the header checksum incrementally with bpf_l3_csum_replace.
Performance comparison ¶
Use the benchmark in bpf_linux_test.go to compare eBPF vs the pure-Go tagger at different packet rates.
Index ¶
- func RetireStaleFilters(iface *net.Interface, logger *zap.Logger) error
- type BPFTagger
- func (bt *BPFTagger) Close() error
- func (bt *BPFTagger) InstalledEpoch() (int64, bool)
- func (bt *BPFTagger) LastRefresh() (time.Time, error)
- func (bt *BPFTagger) MapKey() uint32
- func (bt *BPFTagger) Schedule() *tesla.KeySchedule
- func (bt *BPFTagger) SetSocketMark(fd int) error
- func (bt *BPFTagger) TagPacket(pkt []byte) ([]byte, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RetireStaleFilters ¶ added in v0.3.0
RetireStaleFilters removes from iface's egress hook every legacy tc filter a tagger of an earlier process left. A TCX attachment is owned by its link descriptor and ends with its process, but a legacy filter keeps its program and key map, and so keeps signing with the last key installed, until it is deleted. It is called before this process attaches any tagger, so every tagger filter found on iface is stale. Other interfaces are inspected but never changed: any remaining filter at the tagger's priority, or a failed listing or deletion, means the earlier signers are not known to be retired. A nil iface performs only this read-only check, including after a restart with fallback packet counting or no configured interface.
Types ¶
type BPFTagger ¶
type BPFTagger struct {
// Attachment names how the program is attached: "tcx", or "tc" for the
// legacy clsact filter used where the kernel has no TCX.
Attachment string
// contains filtered or unexported fields
}
BPFTagger loads, attaches, and manages the eBPF packet tagger. It implements tagger.TaggerInterface (eBPF side) and exposes a KeyManager for periodic key updates.
func NewBPFTagger ¶
func NewBPFTagger(logger *zap.Logger, iface *net.Interface, schedule *tesla.KeySchedule, measurementID []byte) (*BPFTagger, error)
NewBPFTagger loads the compiled eBPF object, attaches the TC egress program to iface, and starts the key-update goroutine.
The caller must call Close() when done to detach the program and release BPF resources.
func (*BPFTagger) InstalledEpoch ¶ added in v0.3.0
InstalledEpoch reports the epoch whose key the map slot may still hold, for the key schedule's disclosure cap.
func (*BPFTagger) LastRefresh ¶ added in v0.3.0
LastRefresh reports the last successful install and the outcome of the latest refresh, for the schedule's attribution report.
func (*BPFTagger) Schedule ¶
func (bt *BPFTagger) Schedule() *tesla.KeySchedule
Source Files