iroh-relay 1.0.2

Iroh's relay server and client
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

//! Iroh's relay is a feature within [iroh](https://github.com/n0-computer/iroh), a peer-to-peer
//! networking system designed to facilitate direct, encrypted connections between devices. Iroh
//! aims to simplify decentralized communication by automatically handling connections through
//! "relays" when direct connections aren't immediately possible. The relay server helps establish
//! connections by temporarily routing encrypted traffic until a direct, P2P connection is
//! feasible. Once this direct path is set up, the relay server steps back, and the data flows
//! directly between devices. This approach allows Iroh to maintain a secure, low-latency
//! connection, even in challenging network situations.
//!
//! This crate provides a complete setup for creating and interacting with iroh relays, including:
//! - [`protos::relay`]: The protocol used to communicate between relay servers and clients. It's a
//!   revised version of the Designated Encrypted Relay for Packets (DERP) protocol written by
//!   Tailscale.
#![cfg_attr(
    feature = "server",
    doc = "- [`server`]: A fully-fledged iroh-relay server over HTTP or HTTPS."
)]
#![cfg_attr(
    not(feature = "server"),
    doc = "- `server`: A fully-fledged iroh-relay server over HTTP or HTTPS."
)]
//!
//!    Optionally will also expose a QAD endpoint and metrics. (requires the feature flag `server`)
//! - [`client`]: A client for establishing connections to the relay.
//! - *Server Binary*: A CLI for running your own relay server. It can be configured to also offer
//!   QAD support and expose metrics.
// Based on tailscale/derp/derp.go

#![cfg_attr(iroh_docsrs, feature(doc_cfg))]
#![deny(missing_docs, rustdoc::broken_intra_doc_links, unreachable_pub)]
#![cfg_attr(not(test), deny(clippy::unwrap_used))]

pub mod client;
pub mod defaults;
pub mod http;
mod key_cache;
mod ping_tracker;
pub mod protos;
pub mod quic;
mod relay_map;
#[cfg(feature = "server")]
pub mod server;
#[cfg(test)]
pub(crate) mod test_utils;
pub mod tls;

pub use crate::{
    key_cache::KeyCache,
    ping_tracker::PingTracker,
    protos::relay::MAX_PACKET_SIZE,
    relay_map::{RelayConfig, RelayMap, RelayQuicConfig},
};

/// Trait for extracting keying material from a TLS connection.
///
/// This allows anything that ends up potentially wrapping a TLS stream to use the
/// underlying [`export_keying_material`] function. It is used during the relay handshake
/// to establish a shared secret between the client and server for authentication purposes.
///
/// [`export_keying_material`]: rustls::ConnectionCommon::export_keying_material
pub trait ExportKeyingMaterial {
    /// If this type ends up wrapping a TLS stream, then this tries
    /// to export keying material by calling the underlying [`export_keying_material`]
    /// function.
    ///
    /// However unlike that function, this returns `Option`, in case the
    /// underlying stream might not be wrapping TLS, e.g. as in the case of
    /// `MaybeTlsStream`.
    ///
    /// For more information on what this function does, see the
    /// [`export_keying_material`] documentation.
    ///
    /// [`export_keying_material`]: rustls::ConnectionCommon::export_keying_material
    #[cfg_attr(wasm_browser, allow(unused))]
    fn export_keying_material<T: AsMut<[u8]>>(
        &self,
        output: T,
        label: &[u8],
        context: Option<&[u8]>,
    ) -> Option<T>;
}