Module stun 

STUN as ICE uses it: connectivity checks over the media port (RFC 5389, RFC 8445 §7).

[sipx_transport::stun] is a Binding client with no attributes and no credentials, and its own header says so: “Anything that needs the full protocol (ICE, RFC 8445) needs a different module, not more attributes bolted onto this one.” This is that module. What it takes from there it takes unchanged — RFC 5389 §6’s header layout, the magic cookie, §7.3’s is_stun test and the cryptographically random TransactionId, which is a security decision that should exist once — and it adds nothing there.

What it does not take is the XOR-MAPPED-ADDRESS reader, for two reasons: that decoder is reachable only through parse_reply, which reads Binding Responses and discards every attribute ICE needs, and a connectivity check has to write the attribute as well as read it. Exposing the helper would have been extending the module the story was told not to extend.

Two things in here are worth reading twice, because both fail silently.

The order of the two integrity values. MESSAGE-INTEGRITY is HMAC-SHA1 over the message with the header’s length field temporarily set as though the message ended just after it (RFC 5389 §15.4); FINGERPRINT is computed last, over everything including MESSAGE-INTEGRITY, with the length field again adjusted to include it (§15.5), and its value is the CRC-32 XOR 0x5354554e. Both adjustments are easy to skip and neither is visible in a self-test: the message round-trips through this module perfectly and every real peer rejects it. The guard is a_connectivity_check_encodes_to_the_rfc_5769_sample_request, because the IETF computed that tag and not this crate.

The direction of USERNAME. See Peering.

Everything here is handed unauthenticated datagrams from whoever can reach the media port (spec §11.3): no unwrap, no raw indexing, no length arithmetic that can wrap. A malformed message is an Error and a dropped datagram.

PRIORITY is range-checked, and that is a deliberate trade

A PRIORITY outside RFC 8839 §5.1’s 1..=2^31−1 makes Message::decode reject the whole datagram, not just the attribute, because Priority will not hold the value.

Chosen with the cost known. spec §6.2 is explicit that the range check on parse is what keeps RFC 8445 §6.1.2.3’s pair-priority arithmetic inside a u64, and §5.1.2.1’s formula cannot reach 2^31 for a conforming peer, so nothing legitimate is being refused. What is being risked is a peer that treats the field as a plain u32 and sets the high bit: every check it sends is dropped, and the failure has precisely the signature Peering warns about — it looks like a blocked path and gets diagnosed as a network fault. That is written down here rather than left to be rediscovered, because the alternative — accepting the value and range-checking it at the point the arithmetic happens — moves an overflow that a peer chooses into a crate that cannot see where the number came from. Failing closed at the parser is worth the interop risk; failing closed silently would not be.

Structs

Message

A STUN message: the header, the attributes, and — once decoded — what the two integrity values said.

Peering

Our short-term credentials and the peer’s, and the two usernames they make (spec §11.2).

Enums

Attribute

One STUN attribute, in the profile spec §11.1 lists.

Class

RFC 5389 §6’s message class: the two bits that say request from response.

Error

What a datagram that was not a STUN message this profile understands turned out to be.

RoleAttribute

Which role attribute a check carries, and — for the controlling agent only — whether it nominates (RFC 8445 §7.1.2, §7.1.3).

Constants

ERROR_CODES

The error codes RFC 5389 §15.6’s three-bit class can carry: “The value MUST be between 3 and 6.” Enforced in both directions, so that neither a code this module sends nor one it reports having received is a number §15.6 does not define.

ROLE_CONFLICT

RFC 8445 §7.3.1.1’s error response code: 487 Role Conflict.

Functions

check_success

The success response to a check sipx received (RFC 8445 §7.3.1.2, RFC 5389 §10.1.2).

connectivity_check

A connectivity check to send to the peer (RFC 8445 §7.1, spec §11.1).

keepalive

A keepalive on a selected pair (RFC 8445 §11, RFC 8839 §6, spec §10).

new_transaction_id

A fresh transaction ID.

role_conflict

The 487 Role Conflict error response (RFC 8445 §7.3.1.1).

Type Aliases

TransactionId

The 96 bits that tie a response to its request (RFC 5389 §6).