Documentation
¶
Overview ¶
Package tagger provides a transparent IPv4 IPID tagger that injects a 16-bit TESLA-derived authentication tag into every outgoing IPv4 packet.
The tagger operates at the Go socket layer and is invisible to the WASM debuglet module. It wraps outgoing net.Conn and net.PacketConn connections via WrappedConn / WrappedPacketConn.
Tag Placement ¶
The 16-bit tag is written into the IPv4 Identification (IPID) field (bytes 4–5 of the IPv4 header, big-endian) and DF is set. The IPv4 header checksum is recomputed after the fields are updated. The algorithm is the versioned tag specification tesla.TagSpec, docs/tag-spec.md.
Platform notes ¶
Tagging is performed in pure Go and runs on all platforms. On Linux an additional eBPF-based tagger is available for in-kernel, zero-copy tagging (see internal/executor/tagger/ebpf).
Index ¶
Constants ¶
const ( // ModeEBPF is the kernel tagger on TC egress: every IPv4 packet of a // marked socket, TCP, TLS, UDP and ICMP alike, carries the run's tag. ModeEBPF = "ebpf" // ModeUserspace is the pure-Go tagger: UDP and ICMP datagrams to IPv4 // destinations are sent through a raw socket and tagged; TCP and TLS // segments are written by the kernel and stay untagged. ModeUserspace = "userspace" // ModeNone is untagged traffic. ModeNone = "none" )
Tagging modes of one address family or transport.
Variables ¶
var ErrDatagramUntagged = errors.New("tagger: datagrams on this connection cannot be tagged in user space")
ErrDatagramUntagged reports a connection whose datagrams the pure-Go tagger cannot tag: not IPv4, not UDP or ICMP, or no raw socket available. The caller keeps using the connection untagged.
var Untagged = Mode{IPv4: ModeNone, IPv6: ModeNone, SCION: ModeNone}
Untagged is the mode of a run without a tagger.
Functions ¶
func IPv4Checksum ¶
IPv4Checksum computes the one's-complement checksum over an IPv4 header (helper exposed for tests).
Types ¶
type Mode ¶ added in v0.3.0
Mode is how a run's packets are tagged, per address family and for SCION. Neither tagger tags IPv6 yet, and SCION sockets cannot be marked, so IPv6 and SCION are always ModeNone in this build.
func (Mode) RefusesIPv6 ¶ added in v0.3.0
RefusesIPv6 reports whether a run in this mode refuses IPv6 traffic rather than send it untagged: a run whose IPv4 packets are all tagged in the kernel expects attribution, and an IPv6 packet it sent would silently lack it.
type Tagger ¶
type Tagger struct {
// contains filtered or unexported fields
}
Tagger is the pure-Go IPv4 IPID tagger backed by a TESLA key schedule.
func New ¶
func New(schedule *tesla.KeySchedule, measurementID []byte) *Tagger
New creates a Tagger for the given key schedule and measurement ID. measurementID should be the raw bytes of the measurement UUID string.
func (*Tagger) Schedule ¶
func (t *Tagger) Schedule() *tesla.KeySchedule
func (*Tagger) SetSocketMark ¶
func (*Tagger) TagPacket ¶
TagPacket writes the tag of the versioned tag specification tesla.TagSpec (docs/tag-spec.md) into the IPID field of a raw IPv4 packet, sets DF and recomputes the IPv4 header checksum. The packet is modified in-place; the same slice is returned.
The tag is computed over the packet's canonical input (tesla.HashInput), in which the fields a router, NAT or checksum offload rewrites are zeroed, so a verifier reproduces it from the packet it receives. DF is set after hashing and is not part of the input.
A packet v1 does not tag (not IPv4, too short, malformed, or a fragment) is returned unmodified without error. While the schedule has no usable signing key (epoch 0, whose key is the public anchor) the packet is likewise returned unmodified and untagged, as on the eBPF path.
func (*Tagger) WrapDatagram ¶
WrapDatagram returns conn wrapped so that every Write leaves as one IPv4 packet whose IP ID carries this run's tag, as the eBPF tagger would have written it. conn is a connected UDP socket or a connected ip4:icmp socket to an IPv4 destination. The packets are sent through a raw IPPROTO_RAW socket of the wrapper's own, which needs CAP_NET_RAW; conn itself is left as it is and keeps receiving the replies. Any other connection is refused with ErrDatagramUntagged and stays usable untagged.
type TaggerInterface ¶
type TaggerInterface interface {
// TagPacket rewrites the IPID field of the raw IPv4 packet bytes in-place
// and returns the modified slice. The slice may be the same underlying
// array as pkt (modified in-place) or a copy.
TagPacket(pkt []byte) ([]byte, error)
SetSocketMark(fd int) error
Close() error
Schedule() *tesla.KeySchedule
}
TaggerInterface is the abstraction used by both the pure-Go tagger and the eBPF tagger, enabling performance comparison.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package ebpf provides an eBPF-based IPv4 IPID tagger for Linux.
|
Package ebpf provides an eBPF-based IPv4 IPID tagger for Linux. |
|
Package tagvectors loads testdata/tag-vectors-v1.json, the known-answer vectors of the debuglet-tag-v1 packet tag generated by the independent Python reference tools/tag_vectors.py.
|
Package tagvectors loads testdata/tag-vectors-v1.json, the known-answer vectors of the debuglet-tag-v1 packet tag generated by the independent Python reference tools/tag_vectors.py. |
|
Package tesla implements a TESLA-inspired hash-chain key schedule for delayed disclosure of packet authentication keys.
|
Package tesla implements a TESLA-inspired hash-chain key schedule for delayed disclosure of packet authentication keys. |