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

/*!
# Peer Cryptography Module

This module implements the cryptographic key exchange and NAT traversal functionality for peer-to-peer connections in the Citadel Protocol.

## Features
- **Key Exchange Protocol**: Implements a multi-stage key exchange process
- **NAT Traversal Support**: Provides NAT type detection and compatibility checking
- **TLS Integration**: Supports TLS domain configuration for secure connections
- **Security Settings**: Configurable security levels and UDP modes
- **STUN/TURN Support**: Automatic TURN server fallback for incompatible NATs

## Core Components
- `KeyExchangeProcess`: Manages the stages of peer key exchange
- `PeerNatInfo`: Handles NAT-related information and compatibility
- `TlsDomain`: Configures TLS settings for secure connections

## Important Notes
1. Key exchange follows a three-stage protocol for security
2. NAT compatibility is checked before direct connections
3. TURN servers are used as fallback for incompatible NATs
4. TLS domains ensure secure communication channels

## Related Components
- `p2p_conn_handler`: Manages peer connections
- `hole_punch_compat_sink_stream`: Handles hole punching
- `session`: Manages connection sessions
- `state_container`: Tracks connection state

*/

use crate::proto::node::TlsDomain;
use citadel_types::proto::SessionSecuritySettings;
use citadel_types::proto::UdpMode;
use citadel_wire::nat_identification::NatType;
use serde::{Deserialize, Serialize};
use std::net::SocketAddr;

#[derive(Clone, Serialize, Deserialize, Debug)]
pub enum KeyExchangeProcess {
    // alice sends public key
    Stage0(Vec<u8>, SessionSecuritySettings, UdpMode),
    // Bob sends ciphertext, addr, file transfer compatibility
    Stage1(Vec<u8>, Option<PeerNatInfo>, bool),
    // Alice sends a sync time over. Server takes care of external addr. Includes file transfer compat
    Stage2(i64, Option<PeerNatInfo>, bool),
    // The hole-punch failed
    HolePunchFailed,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct PeerNatInfo {
    // This is the location of the listener for the other peer as obtained by the central server
    pub peer_remote_addr_visible_from_server: SocketAddr,
    pub peer_nat: NatType,
    pub tls_domain: TlsDomain,
}

impl PeerNatInfo {
    pub fn generate_proper_listener_connect_addr(
        &self,
        local_nat_type: &NatType,
    ) -> (bool, SocketAddr) {
        //let predicted_addr = self.peer_nat.predict_external_addr_from_local_bind_port(self.peer_unnated_listener_port).map(|r| SocketAddr::new(self.peer_remote_ip, r.port())).unwrap_or_else(|| SocketAddr::new(self.peer_remote_ip, self.peer_unnated_listener_port));
        let predicted_addr = self.peer_remote_addr_visible_from_server;
        // TODO: This assumes same IP, Port as visible from server. For EDM's w/delta,
        // we need to *ensure* the dualstack udp hole puncher can already handle deltas
        // properly
        let needs_turn = !self.peer_nat.stun_compatible(local_nat_type);
        (needs_turn, predicted_addr)
    }
}