iroh_relay/
lib.rs

1//! Iroh's relay is a feature within [iroh](https://github.com/n0-computer/iroh), a peer-to-peer
2//! networking system designed to facilitate direct, encrypted connections between devices. Iroh
3//! aims to simplify decentralized communication by automatically handling connections through
4//! "relays" when direct connections aren't immediately possible. The relay server helps establish
5//! connections by temporarily routing encrypted traffic until a direct, P2P connection is
6//! feasible. Once this direct path is set up, the relay server steps back, and the data flows
7//! directly between devices. This approach allows Iroh to maintain a secure, low-latency
8//! connection, even in challenging network situations.
9//!
10//! This crate provides a complete setup for creating and interacting with iroh relays, including:
11//! - [`protos::relay`]: The protocol used to communicate between relay servers and clients. It's a
12//!   revised version of the Designated Encrypted Relay for Packets (DERP) protocol written by
13//!   Tailscale.
14#![cfg_attr(
15    feature = "server",
16    doc = "- [`server`]: A fully-fledged iroh-relay server over HTTP or HTTPS."
17)]
18#![cfg_attr(
19    not(feature = "server"),
20    doc = "- `server`: A fully-fledged iroh-relay server over HTTP or HTTPS."
21)]
22//!
23//!    Optionally will also expose a QAD endpoint and metrics. (requires the feature flag `server`)
24//! - [`client`]: A client for establishing connections to the relay.
25//! - *Server Binary*: A CLI for running your own relay server. It can be configured to also offer
26//!   QAD support and expose metrics.
27// Based on tailscale/derp/derp.go
28
29#![cfg_attr(iroh_docsrs, feature(doc_cfg))]
30#![deny(missing_docs, rustdoc::broken_intra_doc_links, unreachable_pub)]
31#![cfg_attr(not(test), deny(clippy::unwrap_used))]
32
33pub mod client;
34pub mod defaults;
35pub mod http;
36mod key_cache;
37mod ping_tracker;
38pub mod protos;
39pub mod quic;
40mod relay_map;
41#[cfg(feature = "server")]
42pub mod server;
43#[cfg(test)]
44pub(crate) mod test_utils;
45pub mod tls;
46
47pub use crate::{
48    key_cache::KeyCache,
49    ping_tracker::PingTracker,
50    protos::relay::MAX_PACKET_SIZE,
51    relay_map::{RelayConfig, RelayMap, RelayQuicConfig},
52};
53
54/// Trait for extracting keying material from a TLS connection.
55///
56/// This allows anything that ends up potentially wrapping a TLS stream to use the
57/// underlying [`export_keying_material`] function. It is used during the relay handshake
58/// to establish a shared secret between the client and server for authentication purposes.
59///
60/// [`export_keying_material`]: rustls::ConnectionCommon::export_keying_material
61pub trait ExportKeyingMaterial {
62    /// If this type ends up wrapping a TLS stream, then this tries
63    /// to export keying material by calling the underlying [`export_keying_material`]
64    /// function.
65    ///
66    /// However unlike that function, this returns `Option`, in case the
67    /// underlying stream might not be wrapping TLS, e.g. as in the case of
68    /// `MaybeTlsStream`.
69    ///
70    /// For more information on what this function does, see the
71    /// [`export_keying_material`] documentation.
72    ///
73    /// [`export_keying_material`]: rustls::ConnectionCommon::export_keying_material
74    #[cfg_attr(wasm_browser, allow(unused))]
75    fn export_keying_material<T: AsMut<[u8]>>(
76        &self,
77        output: T,
78        label: &[u8],
79        context: Option<&[u8]>,
80    ) -> Option<T>;
81}
iroh_relay/lib.rs

iroh_relay/
lib.rs
