dhcp

Documentation

Overview

Package dhcp decodes DHCPv4 packets per RFC 2131 (the envelope) + RFC 2132 (the options). DHCP is the second most-captured protocol on any wired network capture after DNS — every laptop / phone / IoT device that joins a network speaks it on UDP/67-68 the moment it links up.

Wrap-vs-native judgement

Native. DHCP wraps a fixed-format 240-byte BOOTP header (RFC 951 + 1542) around a magic cookie (0x63825363) and a variable-length options list. Each option is `[code:1] [length:1][data:length]` with code 0xFF marking the end. Pasting a hex blob from Wireshark / tshark / a tcpdump-of- 67/68 capture is enough — no key material, no cryptography, no live network attach.

What this package covers

• BOOTP envelope (RFC 951 + RFC 2131 §2): op (BOOTREQUEST / BOOTREPLY), htype + hlen (Ethernet supported with hardware addresses rendered as colon MAC), hops, xid (transaction ID), secs (seconds elapsed since lease start), flags (broadcast bit + reserved), ciaddr / yiaddr / siaddr / giaddr in dotted-decimal, 16-byte chaddr (first hlen bytes are the actual hardware address), null-trimmed sname + file fields.
• Magic cookie validation: the 4-byte 0x63825363 at offset 236 must be present for the packet to be considered DHCP (rather than vanilla BOOTP).
• DHCP options walker with type-specific decode for the operationally-important options (RFC 2132 §3 + RFC 3046 / 3203 / 4361 / 4702 extensions):
• **53 DHCP Message Type** — DISCOVER / OFFER / REQUEST / DECLINE / ACK / NAK / RELEASE / INFORM / LEASEQUERY / LEASEUNASSIGNED / LEASEUNKNOWN / LEASEACTIVE / BULKLEASEQUERY / LEASEQUERYDONE / ACTIVELEASEQUERY / LEASEQUERYSTATUS / TLS.
• **1 Subnet Mask**, **3 Router**, **6 DNS Servers**, **42 NTP Servers**, **44 NetBIOS Name Servers**, **45 NetBIOS Datagram Distribution Server** — each is a list of IPv4 addresses.
• **12 Host Name**, **14 Merit Dump File**, **15 Domain Name**, **17 Root Path**, **19 IP Forward**, **40 NIS Domain**, **66 TFTP Server Name**, **67 Boot File Name** — each is an ASCII string.
• **28 Broadcast Address**, **50 Requested IP**, **54 DHCP Server Identifier** — single IPv4.
• **51 IP Address Lease Time**, **57 Maximum DHCP Message Size**, **58 Renewal Time**, **59 Rebinding Time** — durations / sizes in seconds / bytes.
• **55 Parameter Request List** — list of option codes the client is asking the server to include, rendered with option-name lookup so operators see "[Subnet Mask, Router, DNS Server, Domain Name, …]" rather than "[1, 3, 6, 15, …]".
• **60 Vendor Class Identifier**, **61 Client Identifier**, **77 User Class** — vendor / client fingerprinting strings.
• **81 Client FQDN** (RFC 4702) — flags + A-record result + AAAA-record result + FQDN.
• **82 Relay Agent Information** (RFC 3046) — with sub-option walk (Agent Circuit ID, Agent Remote ID, etc.).
• **119 Domain Search** (RFC 3397) — compressed list of search-domain FQDNs.
• **121 Classless Static Route** (RFC 3442) — list of (destination, mask, gateway) tuples.
• Every option that isn't decoded above is still reported with code + name + length + raw hex.
• End-of-options (255) and Pad (0) markers are handled correctly.

What this package does NOT cover (deliberately out of scope)

• DHCPv6 (RFC 8415) — entirely different envelope (transaction ID + IA_NA + IA_TA + options); deferred to a separate Spec.
• DHCP authentication (option 90, RFC 3118) — niche; surfaced as raw hex.
• PXE / boot-time vendor-specific options — pass-through as raw hex with the option name "Vendor-specific Information".
• Encapsulated relay forms — operators feed the inner DHCP message after stripping outer transport.

Index

• type FQDNOption
• type Option
• type Packet
  • func Decode(hexBlob string) (*Packet, error)
  • func DecodeBytes(b []byte) (*Packet, error)
• type Route
• type SubOption

Types

type FQDNOption

type FQDNOption struct {
	Flags      int    `json:"flags"`
	ARecord    int    `json:"a_record_result"`
	AAAARecord int    `json:"aaaa_record_result"`
	FQDN       string `json:"fqdn"`
}

FQDNOption is the decoded option-81 body.

type Option

type Option struct {
	Code            int         `json:"code"`
	Name            string      `json:"name"`
	Length          int         `json:"length"`
	DataHex         string      `json:"data_hex,omitempty"`
	StringValue     string      `json:"string_value,omitempty"`
	IPv4            string      `json:"ipv4,omitempty"`
	IPv4List        []string    `json:"ipv4_list,omitempty"`
	Uint32Value     uint32      `json:"uint32_value,omitempty"`
	ParameterList   []string    `json:"parameter_list,omitempty"`
	DomainSearch    []string    `json:"domain_search,omitempty"`
	ClasslessRoutes []Route     `json:"classless_routes,omitempty"`
	FQDN            *FQDNOption `json:"fqdn,omitempty"`
	RelayAgent      []SubOption `json:"relay_agent_sub_options,omitempty"`
}

Option is one decoded DHCP option.

Only the field that matches the option's type is populated; the raw bytes are always exposed via DataHex.

type Packet

type Packet struct {
	HexInput    string    `json:"hex_input"`
	Op          int       `json:"op"`
	OpName      string    `json:"op_name"`
	HType       int       `json:"htype"`
	HTypeName   string    `json:"htype_name"`
	HLen        int       `json:"hlen"`
	Hops        int       `json:"hops"`
	XID         uint32    `json:"xid"`
	Secs        int       `json:"secs"`
	Flags       int       `json:"flags"`
	Broadcast   bool      `json:"broadcast"`
	CiAddr      string    `json:"ciaddr"`
	YiAddr      string    `json:"yiaddr"`
	SiAddr      string    `json:"siaddr"`
	GiAddr      string    `json:"giaddr"`
	ClientHwHex string    `json:"client_hw_hex"`
	ClientHwMAC string    `json:"client_hw_mac,omitempty"`
	ServerName  string    `json:"server_name,omitempty"`
	BootFile    string    `json:"boot_file,omitempty"`
	MagicCookie string    `json:"magic_cookie"`
	MessageType string    `json:"message_type,omitempty"`
	Options     []*Option `json:"options,omitempty"`
}

Packet is the decoded DHCPv4 message view.

func Decode

func Decode(hexBlob string) (*Packet, error)

Decode parses a hex-encoded DHCPv4 packet.

func DecodeBytes

func DecodeBytes(b []byte) (*Packet, error)

DecodeBytes parses a raw DHCPv4 packet.

type Route

type Route struct {
	Destination string `json:"destination"`
	PrefixLen   int    `json:"prefix_length"`
	Gateway     string `json:"gateway"`
}

Route is one entry in option 121 (Classless Static Route).

type SubOption

type SubOption struct {
	Code    int    `json:"code"`
	Name    string `json:"name"`
	Length  int    `json:"length"`
	DataHex string `json:"data_hex,omitempty"`
}

SubOption is one entry inside an option whose payload is itself a list of [code, length, data] triples (e.g. option 82 Relay Agent Information).