3 releases (breaking)

0.2.0 Jul 14, 2024
0.1.0 Jun 26, 2024
0.0.1 Jun 16, 2024

#1070 in Network programming


Used in 3 crates (via stun-proto)

MIT/Apache

225KB
4.5K SLoC

Build status codecov Dependencies crates.io docs.rs

stun-types

Repository containing an implementation of STUN (RFC5389/RFC8489) protocol writing in the Rust programming language.

Goals

  • Efficiency:
    • zero-copy parsing
    • no copies until the message is written.
  • Support externally defined attributes easily. Only 3 traits required for an implementation, two of which are From and TryFrom.

Relevant standards

  • RFC5245: Interactive Connectivity Establishment (ICE): A Protocol for Network Address Translator (NAT) Traversal for Offer/Answer Protocols
  • RFC5389: Session Traversal Utilities for NAT (STUN)
  • RFC5766: Traversal Using Relays around NAT (TURN): Relay Extensions to Session Traversal Utilities for NAT (STUN)
  • RFC5769: Test Vectors for Session Traversal Utilities for NAT (STUN)
  • RFC6156: Traversal Using Relays around NAT (TURN) Extension for IPv6
  • RFC8445: Interactive Connectivity Establishment (ICE): A Protocol for Network Address Translator (NAT) Traversal
  • RFC8489: Session Traversal Utilities for NAT (STUN)
  • RFC8656: Traversal Using Relays around NAT (TURN): Relay Extensions to Session Traversal Utilities for NAT (STUN)

Examples

Have a look at the documentation at the crate root for some examples

Why not use stun_codec, stun-format, stun-rs, or 'insert crate here'?

Existing STUN crates suffer from one of a few of shortcomings.

  1. Encoding attributes as enum's rather than as a trait. Using a trait for attributes allows external code to implement their own attributes and is thus not limited to what the crate implements. A trait-based approach also allows us to add attribute implementations without requiring breaking semver. rust-stun-coder and stun-format fall into this category. While we do aim to eventually support all the STUN attributes currently defined by the IANA and in various RFCs, we are also not going to force a user to use our implementations (except for integrity and fingerprint attributes).
  2. Non-zero copy parsing. i.e. taking some input data and making no copies unless a specific attribute implement is required. This is not usually a big deal with most STUN messages but can become an issue with TURN usage and high bitrates transfers. Our goal is to perform no copies of the data unless necessary. stun-format, stun_codec, stun-rs fail this design goal. The only other implementation I could find was turn-rs which contains a very small STUN implementation that is only enough for TURN usage.
  3. Overly complicated with macros and additional traits. It shouldn't be necessary to implement STUN with complicated macros or decoder/encoder traits for messages and attributes. STUN is a relatively simple byte codec and does not require a complicated implementation. stun-rs, stun_codec, currently this design goal.

Dependencies

~1.4–2.2MB
~43K SLoC