citadel_proto 0.13.0

Networking library for the Citadel Protocol
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
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

/*!
# Hole Punch Compatibility Stream Module

This module implements a compatibility layer for UDP hole punching in the Citadel Protocol, providing a reliable ordered stream interface for NAT traversal.

## Features
- **Stream Abstraction**: Implements `ReliableOrderedStreamToTarget` for hole punching
- **Compatibility Layer**: Bridges between different network protocols
- **Security Integration**: Incorporates stacked ratchet encryption
- **Packet Routing**: Supports both client-server and peer-to-peer routing
- **State Management**: Maintains connection state and packet ordering

## Core Components
- `ReliableOrderedCompatStream`: Main stream implementation for hole punching
- `ConnAddr`: Address management for connection endpoints
- `StackedRatchet`: Encryption layer for secure communication

## Important Notes
1. Supports both client-server and peer-to-peer modes
2. Requires pre-loaded ratchets for P2P communication
3. Uses central node for packet routing in P2P mode
4. Maintains packet ordering and reliability

## Related Components
- `peer_crypt`: Handles encryption and key exchange
- `p2p_conn_handler`: Manages peer connections
- `state_container`: Tracks connection state
- `packet_processor`: Handles packet routing

*/

use crate::proto::outbound_sender::{OutboundPrimaryStreamSender, UnboundedReceiver};
use crate::proto::peer::p2p_conn_handler::generic_error;
use crate::proto::state_container::StateContainerInner;
use async_trait::async_trait;
use bytes::Bytes;
use citadel_crypt::ratchets::Ratchet;
use citadel_io::tokio::sync::Mutex;
use citadel_types::crypto::SecurityLevel;
use netbeam::reliable_conn::{ConnAddr, ReliableOrderedStreamToTarget};
use std::net::SocketAddr;
use std::str::FromStr;

pub(crate) struct ReliableOrderedCompatStream<R: Ratchet> {
    to_primary_stream: OutboundPrimaryStreamSender,
    from_stream: Mutex<UnboundedReceiver<Bytes>>,
    peer_external_addr: SocketAddr,
    local_bind_addr: SocketAddr,
    hr: R,
    security_level: SecurityLevel,
    target_cid: u64,
}

impl<R: Ratchet> ReliableOrderedCompatStream<R> {
    /// For C2S, using this is straight forward (set target_cid to 0)
    /// For P2P, using this is not as straight forward. This will use the central node for routing packets. As such, the target_cid must be set to the peers to enable routing. Additionally, this will need to use the p2p ratchet. This implies that
    /// BOTH nodes must already have the ratchets loaded
    pub(crate) fn new(
        to_primary_stream: OutboundPrimaryStreamSender,
        state_container: &mut StateContainerInner<R>,
        target_cid: u64,
        hr: R,
        security_level: SecurityLevel,
    ) -> Self {
        let (from_stream_tx, from_stream_rx) = citadel_io::tokio::sync::mpsc::unbounded_channel();

        // insert from_stream_tx into state container so that the protocol can deliver packets to the hole puncher
        // NOTE: The protocol must strip the header when passing packets to the from_stream function!
        let _ = state_container
            .hole_puncher_pipes
            .insert(target_cid, from_stream_tx);
        // NOTE: this is hacky. We don't actually need real addrs here since this is used for hole punching
        let peer_external_addr = SocketAddr::from_str("1.2.3.4:1234").unwrap();
        let local_bind_addr = SocketAddr::from_str("0.0.0.0:1234").unwrap();
        Self {
            to_primary_stream,
            from_stream: Mutex::new(from_stream_rx),
            peer_external_addr,
            local_bind_addr,
            hr,
            security_level,
            target_cid,
        }
    }
}

#[async_trait]
impl<R: Ratchet> ReliableOrderedStreamToTarget for ReliableOrderedCompatStream<R> {
    async fn send_to_peer(&self, input: &[u8]) -> std::io::Result<()> {
        let packet = crate::proto::packet_crafter::hole_punch::generate_packet(
            &self.hr,
            input,
            self.security_level,
            self.target_cid,
        );
        self.to_primary_stream
            .unbounded_send(packet)
            .map_err(|err| generic_error(err.to_string()))
    }

    async fn recv(&self) -> std::io::Result<Bytes> {
        // This assumes the payload is stripped from the header and the payload is decrypted
        // packet is decrypted in hole_punch.rs
        self.from_stream
            .lock()
            .await
            .recv()
            .await
            .ok_or_else(|| generic_error("Inbound ordered reliable stream died"))
    }
}

impl<R: Ratchet> ConnAddr for ReliableOrderedCompatStream<R> {
    fn local_addr(&self) -> std::io::Result<SocketAddr> {
        Ok(self.local_bind_addr)
    }
    fn peer_addr(&self) -> std::io::Result<SocketAddr> {
        Ok(self.peer_external_addr)
    }
}