rtc_stun/
lib.rs

1#![warn(rust_2018_idioms)]
2#![warn(missing_docs)]
3#![allow(dead_code)]
4
5//! STUN for the Sans-I/O WebRTC stack.
6//!
7//! Session Traversal Utilities for NAT ([RFC 5389], superseding [RFC 3489]), plus the
8//! attributes ICE ([RFC 8445]) and TURN ([RFC 5766]) layer on top. In WebRTC, STUN does
9//! double duty: it discovers a peer's server-reflexive address, and its binding
10//! request/response exchange *is* the ICE connectivity check.
11//!
12//! # Structure
13//!
14//! * [`message`] — [`Message`](message::Message), the STUN message itself: build one from
15//!   attributes, marshal it, unmarshal one off the wire.
16//! * [`attributes`], [`textattrs`], [`uattrs`], [`xoraddr`], [`error_code`] — the attribute
17//!   types, including `XOR-MAPPED-ADDRESS`, `USERNAME`, `REALM` and `ERROR-CODE`.
18//! * [`integrity`], [`fingerprint`] — `MESSAGE-INTEGRITY` (HMAC-SHA1) and `FINGERPRINT`
19//!   (CRC-32), the two attributes whose values depend on the encoded message.
20//! * [`agent`], [`client`] — transaction tracking and a Sans-I/O client for talking to a
21//!   STUN server.
22//! * [`uri`] — parsing `stun:`/`stuns:` URLs.
23//! * [`checks`] — validation helpers for received messages.
24//!
25//! # Example
26//!
27//! ```
28//! use rtc_stun::attributes::ATTR_SOFTWARE;
29//! use rtc_stun::message::{BINDING_REQUEST, Message, TransactionId};
30//! use rtc_stun::textattrs::TextAttribute;
31//!
32//! # fn example() -> Result<(), Box<dyn std::error::Error>> {
33//! let mut msg = Message::new();
34//! msg.build(&[
35//!     Box::new(TransactionId::new()),
36//!     Box::new(BINDING_REQUEST),
37//!     Box::new(TextAttribute::new(ATTR_SOFTWARE, "webrtc-rs".to_owned())),
38//! ])?;
39//!
40//! // `build` encodes as it goes, so `raw` is ready to send.
41//! assert!(!msg.raw.is_empty());
42//!
43//! let mut decoded = Message::new();
44//! decoded.raw = msg.raw.clone();
45//! decoded.decode()?;
46//! assert_eq!(decoded.typ, BINDING_REQUEST);
47//! # Ok(())
48//! # }
49//! ```
50//!
51//! Most applications do not depend on this crate directly — [`rtc-ice`] and
52//! [`rtc-turn`] build on it, and the [`rtc`](https://docs.rs/rtc) crate drives those.
53//!
54//! [RFC 5389]: https://datatracker.ietf.org/doc/html/rfc5389
55//! [RFC 3489]: https://datatracker.ietf.org/doc/html/rfc3489
56//! [RFC 8445]: https://datatracker.ietf.org/doc/html/rfc8445
57//! [RFC 5766]: https://datatracker.ietf.org/doc/html/rfc5766
58//! [`rtc-ice`]: https://docs.rs/rtc-ice
59//! [`rtc-turn`]: https://docs.rs/rtc-turn
60
61#[macro_use]
62extern crate lazy_static;
63
64/// Socket-address helpers shared by the address attributes.
65pub mod addr;
66/// Transaction tracking: which requests are outstanding and when they time out.
67pub mod agent;
68/// The STUN attribute types and the raw attribute representation.
69pub mod attributes;
70/// Validation helpers for received messages and attributes.
71pub mod checks;
72/// A Sans-I/O STUN client for talking to a STUN server.
73pub mod client;
74/// The `ERROR-CODE` attribute and the codes defined by STUN, TURN and ICE.
75pub mod error_code;
76/// The `FINGERPRINT` attribute, a CRC-32 over the message.
77pub mod fingerprint;
78/// The `MESSAGE-INTEGRITY` attribute, an HMAC-SHA1 over the message.
79pub mod integrity;
80/// The STUN message itself: header, attributes, and encoding.
81pub mod message;
82/// Text-valued attributes such as `USERNAME`, `REALM` and `SOFTWARE`.
83pub mod textattrs;
84/// The `UNKNOWN-ATTRIBUTES` attribute, listing attributes a server could not process.
85pub mod uattrs;
86/// Parsing `stun:` and `stuns:` URIs.
87pub mod uri;
88/// The `XOR-MAPPED-ADDRESS` attribute, whose value is masked with the magic cookie.
89pub mod xoraddr;
90
91/// IANA assigned ports for "stun" protocol.
92pub const DEFAULT_PORT: u16 = 3478;
93/// The default port for `stuns:` (STUN over TLS/DTLS).
94pub const DEFAULT_TLS_PORT: u16 = 5349;
95
96#[cfg(all(feature = "aws-lc-rs", feature = "ring"))]
97compile_error!("At most one of the features \"aws-lc-rs\" and \"ring\" can be enabled.");
98#[cfg(not(any(feature = "aws-lc-rs", feature = "ring")))]
99compile_error!("At least one of the features \"aws-lc-rs\" and \"ring\" must be enabled.");
100#[cfg(feature = "aws-lc-rs")]
101extern crate aws_lc_rs as ring;
rtc_stun/lib.rs

rtc_stun/
lib.rs
