Documentation
¶
Overview ¶
Package tagspec implements the pure functions of the packet tag specification debuglet-tag-v1 (docs/tag-spec.md): the canonical tag input of an IPv4 packet, SipHash-2-4, the per-measurement key and the 16-bit tag. It holds no key schedule and no state, so taggers (internal/executor/tagger) and verifiers (pkg/client) share one implementation. The known-answer vectors in testdata/tag-vectors-v1.json pin it.
Index ¶
- Constants
- func ComputeTag(ak, input []byte) (uint16, error)
- func DeriveAK(k []byte, measurementID []byte) ([]byte, error)
- func HashInput(packet []byte) ([]byte, error)
- func PacketID(packet []byte) (uint16, bool)
- func PacketTag(ak, packet []byte) (uint16, error)
- func SipHash24(key, data []byte) uint64
- type UnsupportedError
Constants ¶
const ( UnsupportedIPv6 = "ipv6" // IPv6 is not specified in v1. UnsupportedNotIPv4 = "not_ipv4" // Neither IPv4 nor IPv6. UnsupportedTooShort = "too_short" // Fewer bytes than the header or the tag input. UnsupportedMalformed = "malformed" // IHL below 5 or a total length below the header. UnsupportedFragment = "fragment" // MF set or a non-zero fragment offset. )
Reasons why a packet has no v1 tag. The tagger leaves such a packet unchanged, and a verifier reports it unsupported rather than unmatched.
const ID = "debuglet-tag-v1"
ID identifies the packet-tag algorithm this package implements. Taggers and verifiers of one fleet use one version; results record it so evidence names the algorithm its tags follow.
const MaxInput = 64
MaxInput is the most packet bytes the tag authenticates.
const MinDisclosureDelay = 2
MinDisclosureDelay is the shortest disclosure delay d, in epochs, that a tagger uses and a verifier accepts. A verifier tries a packet's epoch t and t-1; with d = 1 the key of t-1 is already public during epoch t.
const Version = 1
Version is the numeric form of ID that the dispatcher's attribution history reports per chain. Zero there is an executor that predates the versioned specification (the unversioned pre-v1 tag), which no verifier accepts.
Variables ¶
This section is empty.
Functions ¶
func ComputeTag ¶
ComputeTag is the 16-bit tag of an already canonical input: the low 16 bits of SipHash-2-4 keyed with ak[0:16]. Every input byte is hashed; HashInput bounds a packet's input to MaxInput bytes.
func DeriveAK ¶
DeriveAK computes the per-measurement authentication key of §2:
ak = HKDF-SHA256(secret=k, salt=absent, info=measurementID, length=32)
where measurementID is the ASCII of the run's canonical lowercase UUID.
func HashInput ¶
HashInput returns the canonical tag input of an IPv4 packet: its first min(64, total length) bytes with TOS, IP ID, flags and fragment offset, TTL, header checksum, IP options and the ICMP, TCP or UDP checksum zeroed. It fails with an *UnsupportedError for a packet v1 does not tag. packet is not modified.
func PacketID ¶
PacketID returns the Identification field of an IPv4 packet, where the tag is carried, and false for a packet too short to hold it.
Types ¶
type UnsupportedError ¶
type UnsupportedError struct{ Reason string }
UnsupportedError is returned for a packet the specification assigns no tag.
func (*UnsupportedError) Error ¶
func (e *UnsupportedError) Error() string
Source Files