Skip to content

STUN protocol support (RFC 5389) #194

Description

@EONRaider

Target: 2.6.0 (Tier 4 — AAA & infrastructure services)

Context

STUN helps a host discover its public-facing address/port for NAT
traversal — UDP (or TCP) port 3478. Its attribute encoding is
trickier than RADIUS's flat TLVs (this same tier): STUN attributes
carry addresses XOR'd against a magic cookie, worth calling out as an
explicit design point rather than a gotcha discovered mid-PR.

Deliverable

Add netprotocols.STUN (layer 7, dispatched from udp.port/
tcp.port):

  • Decode the 20-byte header (RFC 5389 §6): Message Type (2 bytes, a
    Class/Method split across non-contiguous bits — treat as one enum
    value rather than trying to split it into two dataclass fields),
    Message Length (2 bytes), Magic Cookie (4 bytes, fixed
    0x2112A442 — verify it, don't just store it), Transaction ID (12
    bytes).
  • Decode the Attribute list (Type 2 bytes, Length 2 bytes,
    Value padded to a 4-byte boundary) via _tlv.py's
    walk_kind_length_value, adapting for the padding.
  • Name MAPPED-ADDRESS (0x0001) and XOR-MAPPED-ADDRESS (0x0020) —
    the two attributes any STUN response actually needs. XOR-MAPPED-
    ADDRESS's address/port are obscured by XORing against the Magic
    Cookie and Transaction ID (RFC 5389 §15.2) — implement the
    un-XOR as a display/accessor property, the same convention this
    library already uses for hex/enum helpers, so the raw on-wire bytes
    still round-trip untouched.
  • Register udp.port 3478 and tcp.port 3478 → STUN.

Acceptance criteria

  • STUN decodes the header (with Magic Cookie verification) and
    attribute list; bytes(STUN.decode(x)) == x.
  • XOR-MAPPED-ADDRESS's un-XOR accessor returns the correct
    address/port against a known-good fixture.
  • UDP/TCP port 3478 dispatches to STUN.
  • Fixture covering a Binding Request/Response pair; truncation.
  • CHANGELOG entry; full ladder green.

References

RFC 5389 · TLV walker: _tlv.py

Part of #174

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions