57 KiB

Raw Blame History

uTun — Архитектура системы

Документ для разработчиков. Описывает внутреннее устройство, дизайн-решения, взаимодействие модулей и поток данных.

1. Обзор и дизайн-решения

uTun — защищённый VPN-туннель с собственным надёжным транспортным протоколом ETCP. Ключевые архитектурные решения:

Решение	Обоснование
Однопоточный async	Нет гонок данных, нет оверхеда на мьютексы, детерминированное поведение. Один `UASYNC` на поток
Очередь-ориентированный дизайн	Все взаимодействия между модулями — через lock-free очереди `ll_queue`. Callback-и + backpressure
2 уровня надёжности	ETCP (per-connection, RTT-based retrans) + etcp_router (per-service, 300ms retrans/17 попыток, transit forwarding)
Memory pools	Предварительно выделенные пулы для hot-path объектов (пакеты, ACK, payload). Нет malloc в критическом пути
Детерминированный node_id	`SHA256(privkey) → 63-bit` — глобально уникальный идентификатор без централизованного распределения
2-phase cleanup	Отложенное освобождение ресурсов через `uasync_call_soon` — защита от UAF при вызове close из callback

Область применения

Site-to-site и client-to-site VPN
Mesh-сети с автоматическим обнаружением топологии (BGP)
Exit-прокси: SOCKS5, HTTP CONNECT, TCP/UDP/ICMP туннелирование
P2P чат с синхронизацией (chatgui)
Тестирование сетевых протоколов (dummynet — эмуляция потерь/задержек)

Ограничения

Требует root для TUN и raw socket (ICMP proxy)
Однопоточная модель: CPU-bound операции блокируют event loop
Нет аппаратного ускорения криптографии (OpenSSL софтварный)
Максимум 16 hop-ов в BGP (защита от петель)
Максимум 65535 фрагментов на пакет (нормализатор)

2. Многослойный протокольный стек

┌─────────────────────────────────────────────────────────────────┐
│ Layer 4: Приложения                                              │
│ routing (IP-форвардинг), proxy (SOCKS5/TCP/UDP/ICMP), chat,     │
│ db_sync (P2P БД), NTP, NAT                                    │
├─────────────────────────────────────────────────────────────────┤
│ Layer 3: etcp_router — сервисная маршрутизация                   │
│ seq-нумерация, дедупликация, реордеринг, ретрансмиссия,         │
│ inflight control, transit forwarding (multi-hop), minRTT        │
│ SVC_ROUTE_HDR: [cmd|dst|src|seq|svc_id|flags|timestamp] (25B)  │
├─────────────────────────────────────────────────────────────────┤
│ Layer 2.5: LoadBalancer — multi-link балансировка                │
│ выбор линка (min inflight, round-robin), traffic shaper         │
│ (token bucket per-link), burst measurement                      │
├─────────────────────────────────────────────────────────────────┤
│ Layer 2: ETCP — надёжный транспорт                               │
│ inflight queues (send_q / wait_ack), ACK processing,             │
│ retransmission (K1*rtt + K2*jitter), BBR congestion control,     │
│ фрагментация (pkt_normalizer), keepalive, INIT handshake        │
├─────────────────────────────────────────────────────────────────┤
│ Layer 1: secure_channel — криптография                           │
│ X25519 ECDH → AES-128-CCM (AEAD), Ed25519 signatures,           │
│ AES-128-CTR (streaming), pubkey obfuscation (INIT/PING)         │
│ Формат: nonce[13] || AES-CCM(plaintext || CRC32) || tag[16]    │
├─────────────────────────────────────────────────────────────────┤
│ Layer 0: Транспорт                                               │
│ UDP (основной), TCP/STCP (fallback), TUN device,                │
│ кроссплатформенные абстракции (socket_compat, platform_compat)   │
└─────────────────────────────────────────────────────────────────┘

Почему два уровня надёжности?

ETCP обеспечивает надёжную доставку между двумя непосредственно соединёнными узлами (per-connection). Этого достаточно для прямого линка, но недостаточно когда трафик идёт через промежуточные узлы (transit).

etcp_router добавляет end-to-end надёжность поверх ETCP для multi-hop сценариев:

Свой sequence number — не зависит от ETCP seq (который per-hop)
Transit forwarding: промежуточный узел получает SVC_ROUTE_HDR, видит что dst_node_id != local_node_id и пересылает дальше
Собственный retransmission таймер (300ms, 17 попыток) — не ждёт ETCP retrans (который срабатывает на каждом hop-е отдельно)
Per-service изоляция: (remote_node_id, svc_id) кортеж — разные сервисы имеют независимые seq

3. Фундамент: однопоточный async (lib/)

3.1 UASYNC — событийный цикл

Центральный планировщик. Один инстанс на поток.

uasync_mainloop():
  while (!stop):
    timeout = timeout_heap_peek()  // ближайший таймер
    epoll_wait/poll(timeout)       // ждём события на сокетах
    process expired timers         // сработавшие таймеры
    process ready sockets          // сработавшие сокеты
    process call_soon queue        // отложенные callback (FIFO)
    process posted tasks           // межпоточные callback

Ключевые API:

uasync_set_timeout(ua, timeout_tb, arg, cb, name) — таймер в 0.1ms единицах. Возвращает handle для отмены
uasync_add_socket(ua, fd, read_cb, write_cb, error_cb, arg) — регистрация fd в epoll
uasync_call_soon(ua, arg, cb) — отложенный вызов на следующей итерации (FIFO). Используется для 2-phase cleanup
uasync_post(ua, cb, arg) — межпоточный вызов (thread-safe). Пробуждает epoll через wakeup pipe
uasync_memsync(ua) — memory barrier для синхронизации памяти между потоками

Правила:

Никаких sleep/usleep — только таймеры
Нельзя использовать из нескольких потоков один UASYNC
uasync_post — единственный способ вызвать код uTun из другого потока

3.2 ll_queue — lock-free очередь

Основа всего межмодульного взаимодействия. Критические правила:

Callback правило: queue_set_callback(q, cb, arg) → внутри cb обязательно: queue_data_get(q) → обработка → queue_resume_callback(q). Без resume очередь навсегда блокируется.
Backpressure: queue_set_threshold(q, max_packets, max_bytes) + queue_waiter_wait(q, &handle, cb, arg). Не забиваем очередь — добавляем только когда waiter сработал.
Поиск по индексу: queue_data_put_with_index(q, entry) — entry должен иметь ключ по смещению index_offset размером index_size. FNV-1a хеш.
Память: queue_entry_new_from_pool(pool) / queue_entry_free(entry) для entry. queue_dgram_free(entry) отдельно для dgram.

3.3 Memory pools

Три пула в UTUN_INSTANCE для hot-path:

Пул	Размер блока	Назначение
`data_pool`	`PACKET_DATA_SIZE`	Payload данные (фрагменты, recv_q, output_queue)
`pkt_pool`	`sizeof(ETCP_DGRAM) + PACKET_DATA_SIZE`	Исходящие wire-пакеты
`ack_pool`	`sizeof(ACK_PACKET)`	Записи ACK в ack_q

Пулы кэшируют до 64 освобождённых блоков (singly-linked free list). При исчерпании — fallback на malloc. Канарейки для детекции переполнения.

3.4 Кроссплатформенность

Абстракция	Linux	FreeBSD	Windows
Event loop	epoll	poll	poll
TUN	/dev/net/tun (ioctl)	/dev/tun (ioctl)	Wintun DLL
Роутинг	netlink (RTM_NEWROUTE)	routing socket	CreateIpForwardEntry
Сокеты	socket_t = int	socket_t = int	socket_t = SOCKET
Random	/dev/urandom	/dev/urandom	BCryptGenRandom

4. Сквозной путь данных

4.1 Отправка: TUN → сеть

Ядро пишет IP-пакет в /dev/tun
        │
        ▼ (epoll: fd готов к чтению)
┌──────────────────────────────────────────────┐
│ tun_read_callback(fd, tun)                   │  tun_if.c
│   tun_platform_read() → сырой IP-пакет       │
│   ll_entry = pool_alloc(tun->pool)           │  префикс [0x00] (cmd byte)
│   queue_data_put(tun->output_queue, entry)   │
└──────────────────────┬───────────────────────┘
                       │ queue callback
                       ▼
┌──────────────────────────────────────────────┐
│ routing_pkt_from_tun_cb(q, instance)         │  routing.c:207
│   queue_data_get() → entry                   │
│   route_pkt(instance, entry, SELF_NODE_ID)   │
│   queue_resume_callback()                    │
└──────────────────────┬───────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────┐
│ route_pkt(instance, entry, src_node_id)      │  routing.c:53
│   extract_dst_ip(entry) → dst_ip             │  парсинг IPv4 заголовка
│   route_lookup(rt, dst_ip) → ROUTE_ENTRY     │  longest prefix match
│   if v_node_info == NULL (локальный):        │
│     → queue_data_put(tun->input_queue)       │  доставка себе
│   else (удалённый узел):                     │
│     → etcp_route_send(inst, node_id, entry)  │  отправка через ETCP
└──────────────────────┬───────────────────────┘
                       │ если удалённый
                       ▼
┌──────────────────────────────────────────────┐
│ etcp_route_send(inst, dst, entry)            │  etcp_router.c
│   rconn = etcp_router_conn_get(dst, svc_id)  │  per-(dst,svc) соединение
│   if rconn->inflight >= inflight_limit:      │
│     → queue_data_put(rconn->send_q)          │  backpressure
│     return                                    │
│   router_send_one(rconn, data, len):         │
│     SVC_ROUTE_HDR hdr = {cmd, dst, src,      │  25 байт
│        tx_seq++, svc_id, flags, timestamp}   │
│     ll_entry = [hdr || payload]              │
│     entry_copy = copy for inflight_q (retrans)│
│     etcp_send(conn, entry)                   │
│     start retrans_timer (300ms)              │
└──────────────────────┬───────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────┐
│ etcp_send(conn, entry)                       │  etcp_api.c
│   queue_data_put(conn->send_input_q, entry)  │  == normalizer->input
└──────────────────────┬───────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────┐
│ pkt_normalizer — packer                      │  pkt_normalizer.c
│   waiter на etcp->input_queue                │  backpressure: ждём пустую очередь
│   etcp_input_ready_cb():                     │
│     pop from pn->input                       │
│     write [total_len:2 LE][data] in pn->data │  буфер аккумуляции
│     when buffer >= frag_size:                │
│       pn_send_to_etcp() → ETCP_FRAGMENT      │
│       queue_data_put(etcp->input_queue)      │
│   pn_flush_cb(): flush partial buffer        │
└──────────────────────┬───────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────┐
│ etcp — inflight processing                   │  etcp.c
│   input_queue_cb():                          │
│     pop ETCP_FRAGMENT from input_queue       │
│     wrap in INFLIGHT_PACKET (inflight_pool)  │
│     assign next_tx_id++                      │
│     queue_data_put_with_index(input_send_q)  │  хеш-индекс по seq
│                                              │
│   input_send_q_cb → process_send_queue():    │
│     loop:                                    │
│       etcp_request_pkt(etcp):                │
│         select link (loadbalancer)           │
│         pop from input_send_q                │
│         move to input_wait_ack               │
│         build wire packet:                   │
│           [ACK section (0x01)]               │  mandatory, always first
│           [optional: MEAS_RESP, TIMESTAMP,   │
│            MEAS_TS, FILLER]                  │
│           [PAYLOAD (0x00): seq(4B) + data]   │  always last
│         etcp_loadbalancer_send(dgram)        │
└──────────────────────┬───────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────┐
│ LoadBalancer → secure_channel → UDP          │
│   select_link(): min inflight_bytes, RR ties │
│   check shaper (token bucket)                │
│   etcp_encrypt_send(dgram):                  │
│     sc_encrypt(header(3) + data)             │  AES-128-CCM
│     append CRC32                             │
│     socket_sendto(sock, ...)                 │
│   update shaper_load_time_tb                 │
└──────────────────────────────────────────────┘

4.2 Приём: сеть → TUN

UDP socket recvfrom()
        │
        ▼
┌──────────────────────────────────────────────┐
│ etcp_connections_read_callback_socket()      │  etcp_connections.c
│   sc_decrypt() → проверка CRC32              │
│   if INIT_REQUEST: process handshake          │
│   if INIT_RESPONSE: complete handshake        │
│   if KEEPALIVE/PING/PONG: handle              │
│   if data (ETCP sections):                    │
│     → etcp_conn_input(pkt)                   │
└──────────────────────┬───────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────┐
│ etcp_conn_input(pkt)                         │  etcp.c
│   for each section in pkt:                   │
│     ACK (0x01):                              │
│       parse cumulative rx_ack_till           │  всё до этого seq собрано
│       for each individual ACK:               │
│         find in input_wait_ack by seq        │
│         remove, update BBR (rate_sample)     │
│         free data_pool memory                │
│         advance tx state if window opens     │
│     TIMESTAMP (0x06):                        │
│       compute RTT, update jitter             │
│     PAYLOAD (0x00):                          │
│       extract seq from data[1..4]            │
│       create ACK entry in ack_q              │  будет piggybacked в ответ
│       if seq == last_delivered_id + 1:       │
│         move directly to output_queue        │
│       else:                                  │
│         store in recv_q (hash by seq)        │  OOSEQ буфер
│       etcp_output_try_assembly():            │
│         scan recv_q for contiguous seq       │
│         move to output_queue                 │
└──────────────────────┬───────────────────────┘
                       │ output_queue callback
                       ▼
┌──────────────────────────────────────────────┐
│ pkt_normalizer — unpacker                    │  pkt_normalizer.c
│   pn_unpacker_cb():                          │
│     pop ETCP_FRAGMENT from output_queue      │
│     read [total_len:2 LE] header             │
│     accumulate in recvpart buffer            │
│     when recvpart complete:                  │
│       queue_data_put(pn->output, packet)     │
└──────────────────────┬───────────────────────┘
                       │ pn->output callback
                       ▼
┌──────────────────────────────────────────────┐
│ etcp_int_recv(queue, conn)                   │  etcp_api.c
│   read cmd = data[0]                         │
│   dispatch: bindings->callbacks[cmd](conn, e)│
│   cmd=0x03 (ETCP_ID_SVC_ROUTE):              │
│     → etcp_router_recv_cb()                  │
│   cmd=0x00 (ETCP_ID_DATA):                   │
│     → direct routing handler (legacy)        │
└──────────────────────┬───────────────────────┘
                       │ для cmd=0x03 (SVC_ROUTE)
                       ▼
┌──────────────────────────────────────────────┐
│ etcp_router_recv_cb(conn, entry)             │  etcp_router.c
│   parse SVC_ROUTE_HDR:                       │
│     dst_node_id, src_node_id, seq, svc_id    │
│                                              │
│   if dst_node_id != local_node_id:           │
│     router_forward_transit():                │  мы — промежуточный узел
│       find/create TRANSIT_QUEUE(src,dst)     │
│       queue_data_put(transit_q, entry)       │
│       drain transit_q → next hop via         │
│         waiter on send_input_q               │  backpressure
│     return                                    │
│                                              │
│   if payload_len == 0:                       │  это ACK/CLOSE/RST
│     router_handle_ack(rconn, hdr):           │
│       tx_acked = hdr->seq                    │  продвигаем окно
│       drain send_q                           │  освободившиеся слоты
│     return                                    │
│                                              │
│   router_handle_data_packet(rconn, ...):     │
│     check bounds, dedup (recv_q lookup)      │
│     queue_data_put(rconn->incoming_q)        │
│     if hdr->seq == rconn->rx_seq + 1:        │  следующий ожидаемый
│       router_try_assembly(rconn):            │
│         scan recv_q for contiguous seq       │
│         deliver to service callback          │
└──────────────────────┬───────────────────────┘
                       │ service callback (ETCP_RT_ID_DATA)
                       ▼
┌──────────────────────────────────────────────┐
│ routing_pkt_from_etcp_cb(conn, pkt)          │  routing.c:180
│   route_pkt(instance, pkt, conn->peer_node)  │
│   → route_lookup() → если локальный:         │
│   → queue_data_put(tun->input_queue)         │
└──────────────────────┬───────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────┐
│ tun_input_queue_callback(q, tun)             │  tun_if.c:88
│   queue_data_get() → pkt                     │
│   tun_platform_write(pkt->dgram+1, len)      │  пишем в /dev/tun
│   queue_dgram_free + queue_entry_free        │
│   queue_resume_callback()                    │
└──────────────────────────────────────────────┘
        │
        ▼
Ядро читает IP-пакет из /dev/tun → доставка приложению

4.3 Retransmission (два уровня)

ETCP retrans (ack_timeout_check):

Таймер сканирует input_wait_ack с головы.
Для каждого INFLIGHT_PACKET:
  if now - last_timestamp > timeout:
    timeout = RTT * K1 + jitter * K2
    min 50, max 10000 (0.1ms единицы)
    → переместить обратно в input_send_q (переотправка)

Router retrans (router_retrans_timer_cb):

300ms начальный таймаут
Экспоненциальный backoff (×2 каждые 3 попытки)
Максимум 17 попыток (суммарно ~5 секунд)
Копии пакетов хранятся в inflight_q (hash по seq)
При успешном ACK: удаление из inflight_q

5. ETCP — надёжный транспорт (Layer 2)

5.1 Основные структуры

ETCP_CONN — одно логическое соединение с удалённым узлом:

Идентичность: peer_node_id (uint64_t), session_id (uint32_t)
Криптография: crypto_ctx (sc_context_t — сессионные ключи)
Фрагментация: normalizer (PKTNORM*)
Линки: связный список ETCP_LINK*
Счётчик seq: next_tx_id (монотонный), last_rx_id, last_delivered_id
RTT: rtt_last, rtt_avg_10, rtt_avg_100, jitter, rtt_history[10]
Состояние: 0=pending, 1=ready, 2=deleted (2-phase cleanup)

ETCP_LINK — один UDP-путь:

Статус: recv_keepalive (принимаем ли пакеты), remote_keepalive (видит ли нас пир), link_status
BBR: bbr (struct bbr*), delivered_bytes, pacing_rate, bandwidth
Flow control: inflight_bytes, inflight_packets, inflight_lim_bytes
Shaper: shaper_load_time_tb, shaper_sub_nanotime, shaper_timer
NAT: nat_type, nat_ip, nat_port

Wire-формат пакета:

[encrypted:]
  [timestamp:2] [flag_up:1]           // ETCP_ENCRYPTED_HDR = 3 байта
  [section_0] [section_1] ... [section_N]  // типизированные секции
[appended after encryption:]
  [CRC32:4]

Sections:
  ACK       (0x01): [count:1][rx_ack_till:4][rx_dup:2][per-ACK: seq(4)+ts(2)+delay(2)]
  PAYLOAD   (0x00): [seq:4 BE][data...]  (always last)
  TIMESTAMP (0x06): [cur_ts:2][txrx_offset:2]  (RTT measurement)
  MEAS_TS   (0x07): [burst_id:2][flags:1][seq:1][ts_us:2][sz:2]  (burst)
  MEAS_RESP (0x08): [burst_id:2][valid:1][gap_avg:4][gap_min:4][pkt_cnt:1]
  FILLER    (0x09): [len:2][zeros...]  (burst padding)
  METRICS   (0x0A): [csv_len:2][Ed25519_sig:64][csv...]

5.2 INIT handshake

Клиент знает pubkey сервера из конфига. Сервер не знает клиента заранее.

Client                                   Server
  │                                        │
  │ 1. ECDH: priv_C × pub_S → session_key │
  │ 2. salt = random(8)                    │
  │ 3. obf_pub = XOR(pub_C,                │
  │      SHA256(salt || pub_S))            │
  │ 4. encrypt INIT_REQUEST                │
  │    (AES-CCM, session_key)              │
  │                                        │
  │──── INIT_REQ + [salt||obf_pub] ──────→│
  │                                        │ 1. deobf: XOR(obf_pub,
  │                                        │      SHA256(salt || pub_S))
  │                                        │    → pub_C recovered
  │                                        │ 2. ECDH: priv_S × pub_C
  │                                        │    → same session_key
  │                                        │ 3. decrypt INIT_REQUEST
  │                                        │    (проверка: клиент знает pub_S)
  │                                        │ 4. create ETCP_CONN
  │                                        │ 5. encrypt INIT_RESPONSE
  │←────── INIT_RESP + [salt||obf_pub] ───│
  │                                        │
  │ decrypt RESPONSE, complete             │
  │ link_state = connected                 │
  │                                        │
  │←══════ keepalive/данные ═════════════→│

Ключевое свойство обфускации: XOR(XOR(pub_C, SHA256(salt||pub_S)), SHA256(salt||pub_S)) = pub_C. Обе стороны знают pub_S и salt, поэтому обе могут восстановить pub_C. Пассивный наблюдатель видит только случайный XOR.

5.3 BBR congestion control (per-link)

Алгоритм управления перегрузкой, работающий на уровне ETCP_LINK.

Режимы:

STARTUP  → экспоненциальный рост до обнаружения BDP
  ↓ (найден BDP)
DRAIN    → слив избыточного inflight
  ↓
PROBE_BW → циклическое зондирование bandwidth:
  CRUISE (без изменений) → REFILL (увеличение) →
  UP (зондирование вверх) → DOWN (слив) → CRUISE...
  ↓ (периодически)
PROBE_RTT → зондирование минимального RTT (inflight=4)

Оценка bandwidth: два окна — bw_hi (максимальный фильтр, окно 10) и bw_lo (минимум из окна 6). Используется fixed-point арифметика (BBR_SCALE=8, BW_SCALE=24).

Pacing rate: pacing_rate = bw * pacing_gain. Пакеты отправляются не чаще чем pkt_size / pacing_rate.

Burst measurement: Когда inflight достигает лимита и >500ms с последнего burst, отправляется 12 пакетов подряд (bypass shaper). Получатель измеряет inter-packet gaps и возвращает min/avg gap. Отправитель вычисляет: BW = pkt_size * 8000 / gap_min_us.

6. etcp_router — сервисная маршрутизация (Layer 3)

6.1 Зачем нужен поверх ETCP

ETCP обеспечивает надёжность только на одном hop-е. etcp_router добавляет:

End-to-end seq: не зависит от per-hop ETCP seq
Transit forwarding: пакет может пройти через несколько промежуточных узлов
Per-service изоляция: разные сервисы имеют независимые seq и inflight control
Inflight control: свой congestion window (max_inflight, default 256)
minRTT probing: периодически снижает inflight до 4 для измерения минимального RTT

6.2 Transit forwarding

Узел A → Узел B (промежуточный) → Узел C (цель)

A: etcp_route_send(inst, C_node_id, data)
   → topo_group_find_conn_for_node(C_node_id) → conn_AB
   → router_send_one(rconn_AC): SVC_ROUTE_HDR {dst=C, src=A, seq=5}

B: etcp_router_recv_cb():
   dst_node_id == C → не нам
   router_forward_transit():
     TRANSIT_QUEUE tq(src=A, dst=C) → queue_data_put
     drain через conn_BC → etcp_send(conn_BC, entry)
       (SVC_ROUTE_HDR не модифицируется, только пересылается)

C: etcp_router_recv_cb():
   dst_node_id == C → нам
   router_handle_data_packet()
   → incoming_q → recv_q (reorder) → service callback

Backpressure на транзите: если conn_BC->send_input_q заполнена, transit queue ждёт освобождения через waiter.

6.3 Inflight control и retrans

Отправка:
  tx_seq - tx_acked >= inflight_limit → блокировка → send_q
  tx_seq - tx_acked < inflight_limit  → router_send_one() → inflight_q + retrans_timer

ACK:
  получаем SVC_ROUTE_HDR с seq=N, payload_len=0
  → tx_acked = N
  → удаляем все inflight_q записи с seq <= N
  → drain send_q (освободившиеся слоты)

Retrans:
  300ms → 600ms → 1200ms → ... → максимум 17 попыток
  router_retransmit_one(): копия из inflight_q → etcp_send()
  если 17 попыток без ACK → закрытие rconn

7. BGP топология

7.1 Модель данных

TOPO_NODE: pubkey, ed25519_pubkey, имя, версия, флаги
TOPO_NODEQ: узел в группе + пути (TOPO_NODEPATH), подсети, connectivity, transit
TOPO_NODEPATH: путь к узлу (next_hop_node_id, hop_count, hop_list до 16)
TOPO_GROUP: группа узлов (UTUN — VPN с подсетями, CHAT — чат без подсетей)

7.2 Поток синхронизации

Новое ETCP соединение установлено
        │
        ▼
topo_group_new_conn(group, conn):
  1. topo_group_add_to_senders()          // добавить в список BGP-пиров
  2. topo_group_send_table_request(conn)  // запросить полную таблицу
        │
        ▼ (удалённая сторона получает REQUEST_TABLE)
topo_group_handle_request_table():
  1. topo_group_send_nodeinfo(local_node) // отправить информацию о себе
  2. topo_group_send_full_table()         // все известные узлы
        ├── for each node in group->nodes:
        │     if peer NOT in node's hop_list:
        │       topo_group_send_nodeinfo(node, conn)
  3. topo_group_send_table_complete()

7.3 Обработка NODEINFO

topo_group_process_nodeinfo(group, from_conn, data, len):

  1. Проверка типа группы (UTUN/CHAT)
  2. Проверка hop_count < MAX_HOPS (16)
  3. Проверка версии:
     if existing_node.version >= new_node.version:
       только обновить пути (множественные пути к узлу)
       return

  4. Полное обновление:
     - десериализация TOPO_NODE (адреса, подсети, hop_list)
     - создание/обновление TOPO_NODEQ в group->nodes (hash queue)
     - добавление пути: from_conn->peer_node_id в hop_list
     - ROUTE_INSERT(instance->rt, node)  ← ПОДСЕТИ В ТАБЛИЦУ МАРШРУТИЗАЦИИ!
     - персистентность в SQLite
     - уведомление control_server + chatgui

  5. BROADCAST соседям:
     for each sender in senders_list:
       if sender->peer_node_id not in node->hop_list:
         topo_group_send_nodeinfo(node, sender->conn)

7.4 WITHDRAW (удаление узла)

topo_group_remove_conn(group, conn):
  for each node reachable ONLY through this conn:
    topo_group_process_withdraw(group, node):
      route_delete(instance->rt, node)   ← удаление из таблицы маршрутов
      broadcast WITHDRAW соседям
      удаление из group->nodes

8. conn_mgr — трёхфазное установление соединений

8.1 Диаграмма фаз

conn_mgr_connect_node(mgr, target_node_id)
        │
        ├── Фаза 1: DIRECT ─────────────────────────┐
        │   Для каждого адреса target × наш сокет:    │
        │     etcp_connection_create()                │
        │     etcp_link_new() → INIT                  │
        │     таймер 5000ms                           │
        │                                            │
        │   ✓ Успех → CONN_MGR_OK (DIRECT)           │
        │   ✗ Таймаут:                               │
        │     if (у нас прямой IP) && (!у target):    │
        │       → Фаза 2 (REVERSE)                   │
        │     else:                                   │
        │       → Фаза 3 (INDIRECT)                  │
        │                                            │
        ├── Фаза 2: REVERSE ─────────────────────────┤
        │   etcp_route_send(DIRECT_REQ) → через BGP  │
        │     { наши адреса для подключения }         │
        │   таймер 15000ms                           │
        │                                            │
        │   Target получает DIRECT_REQ:              │
        │     etcp_connection_create()               │
        │     etcp_link_new(REVERSE) → INIT к нам    │
        │                                            │
        │   ✓ Успех → CONN_MGR_OK (REVERSE)          │
        │   ✗ Таймаут → Фаза 3 (INDIRECT)           │
        │                                            │
        └── Фаза 3: INDIRECT ────────────────────────┤
            etcp_route_send(EXCHANGE_REQ) → BGP      │
              { наши top-4 кандидата + RTT }          │
            таймер 15000ms                           │
                                                     │
            Target: probe наши кандидаты              │
              → EXCHANGE_RESP {свои кандидаты + RTT} │
                                                     │
            Мы: probe кандидаты target               │
            cm_compute_intermediaries():              │
              union списков                          │
              total_rtt = our_rtt + their_rtt        │
              sort by total_rtt, select top 3        │
              → INTERM_SELECTED                      │
            entry->conn_type = INDIRECT              │
            CONN_MGR_OK                              │

8.2 Фоновые процессы

bg_ping_timer: каждые ~100ms пингует очередной BGP-узел (RTT измерение), полный цикл ≥10s
candidate_ping_timer: каждые ~2s обновляет RTT для best_candidates[3]
idle_timer: каждые ~1s проверяет неактивные соединения, дисконнект по idle_timeout

8.3 NAT compatibility check

При выборе адресов для DIRECT фазы проверяется совместимость NAT типов:

Если у нас EIM NAT: можем соединиться с кем угодно
Если у нас Symmetric NAT и target за NAT: DIRECT невозможен (→ REVERSE/INDIRECT)
NAT тип определяется через сравнение src_ipv4 (что мы о себе сообщаем) и наблюдаемого адреса при INIT

9. Криптография

9.1 Генерация ключей и идентичности

X25519 keypair:
  EVP_PKEY_keygen(EVP_PKEY_X25519)
    → private_key[32], public_key[32]

Node ID (63-bit):
  SHA256(private_key) → hash[32]
  node_id = *((uint64_t*)hash) & 0x7FFFFFFFFFFFFFFF

Ed25519 keypair (производный от X25519):
  SHA512(private_key) → hash[64]
  ed25519_privkey = hash[0..32]
  ed25519_pubkey = EVP_PKEY_get_raw_public_key(ed25519_privkey)

9.2 Сессионный ключ

X25519 ECDH:
  shared_secret = EVP_PKEY_derive(my_priv, peer_pub)  // 32 байта

Session key (AES-128):
  SHA256(shared_secret || "uTun-v3-session") → hash[32]
  session_key = hash[0..16]

9.3 Формат зашифрованного пакета

Шифрование:
  nonce = sc_build_nonce(tx_counter)  // 13 байт: SHA256(urandom||counter||time)
  AES-128-CCM(nonce, session_key):
    encrypt: header[3] + plaintext[N] + CRC32[4]
    tag = CCM auth tag[16]

Пакет:
  [nonce:13] [ciphertext: N+7] [tag:16] [+ pubkey_block:40 для INIT]

Расшифровка:
  извлечь nonce[13] из начала, tag[16] из конца
  AES-128-CCM decrypt
  проверить CRC32
  проверить CCM auth tag (EVP_DecryptFinal_ex)

9.4 Streaming cipher (STCP)

AES-128-CTR:
  iv = SHA256(session_key || stream_id_LE || "uTun3-stream")[0..16]
  EVP_aes_128_ctr(session_key, iv)

  XOR in-place (конфиденциальность без аутентификации)
  STCP добавляет свой CRC32 на уровне фреймов

9.5 Ed25519 подписи

Используются для:

Метрик (METRICS section 0x0A) — подписанные CSV
Сообщений чата (MSG_OPT_SIGNED флаг)
db_sync записей (JSON + Ed25519 sig)

Стриминговая подпись: SHA512(SHA512(data)) — обе стороны аккумулируют SHA-512, затем one-shot Ed25519 над финальным хешем.

10. Прокси-система

10.1 Архитектура клиента (tcp_proxy_client)

Приложение (браузер и т.д.)
        │ подключается к SOCKS5 localhost:1080
        ▼
┌──────────────────┐
│ socks_proxy      │  SOCKS5/HTTP CONNECT парсинг
│ (src/proxy/)     │  → резолвинг destination
└────────┬─────────┘
         │ ETCP CONNECT → tcp_proxy_server на exit node
         ▼
┌──────────────────┐
│ lwip_tcp         │  Встроенный TCP стек
│ (src/lwip_tcp/)  │  Завершает TCP на клиенте
│                  │  tcp_write() → сегменты
└────────┬─────────┘
         │ lwIP output callback → TUN write
         ▼
┌──────────────────┐
│ TUN (nat_tun)    │  Локальный виртуальный интерфейс
│                  │  Перехватывает ВЕСЬ исходящий TCP
└────────┬─────────┘
         │ для не-TCP: udp_proxy / icmp_proxy
         │ для TCP: lwip_tcp_input() → tcp_process()
         ▼
    ETCP туннель → exit node

Ключевая особенность: клиент использует встроенный lwIP TCP стек для терминации TCP-соединений локально. Это позволяет:

Не гонять TCP ACK через туннель (нет TCP-over-TCP проблемы)
Прозрачно обрабатывать потери на пути клиент↔exit (ETCP надёжен)
Поддерживать SOCKS5/HTTP CONNECT без модификации приложений

10.2 Архитектура сервера (tcp_proxy_server)

ETCP туннель от клиента
        │ CONNECT subcmd: target_ip:port
        ▼
┌──────────────────┐
│ tcp_proxy_server │  Exit node
│                  │  Создаёт OS TCP сокет к реальному адресату
│                  │  Релеит данные: ETCP ↔ OS TCP
│                  │  Backpressure: tx_buf + pause_waiter + retry_timer
│                  │  FIN handling: отложенный FIN до опустошения read_queue
└────────┬─────────┘
         │ OS TCP connect()
         ▼
    Целевой сервер в интернете

10.3 lwIP TCP стек

Встроенный в uTun TCP/IP стек (адаптированный lwIP):

Context-based: один lwip_tcp_ctx на tcp_proxy_client
Таймеры: tcp_fasttmr() (delayed ACK) и tcp_slowtmr() (retrans, keepalive, TIME_WAIT) — каждые 250ms
4 списка PCB: bound, listen, active, time_wait
10 TCP состояний (RFC 793): CLOSED → LISTEN → SYN_RCVD → ESTABLISHED → FIN_WAIT_1/2 → TIME_WAIT
Reno congestion control: slow start, congestion avoidance, fast retransmit (3 dupack), fast recovery
Memory pools: pcb_pool, pcb_listen_pool, seg_pool
Trace ring buffer: 384 записи внутренних событий для отладки
Конфигурация: MSS=1460, RTO_MIN=3000ms, MSL=60s, TCP_WND=8*MSS

11. Модель потоков

11.1 Основной процесс uTun (однопоточный)

Поток 1 (главный):
  uasync_mainloop()
    ├── Сокеты:
    │   ├── UDP listen (все [server] сокеты)
    │   ├── TCP listen (control_server, STCP)
    │   └── TUN fd (read/write через uasync callback)
    ├── Таймеры:
    │   ├── ETCP: retrans, ack_response, keepalive
    │   ├── etcp_router: retrans, ACK, no_route_retry, minRTT_probe
    │   ├── BBR: shaper per-link
    │   ├── conn_mgr: bg_ping, candidate_ping, idle, connect_timeout
    │   ├── Нормализатор: flush_timer
    │   ├── Прокси: диагностика (1s), retry (500ms)
    │   ├── NTP: resync
    │   └── db_sync: TTL cleanup
    ├── call_soon (FIFO):
    │   └── Отложенные callback (2-phase cleanup, resume)
    └── post (межпоточные):
        └── Из chatgui/GUI потока

НЕТ: sleep, usleep, pthread_mutex_lock (в главном потоке)
ВСЕ: асинхронно через uasync

11.2 chatgui (двухпоточный)

Поток 1 (Qt main thread):
  - Рендеринг UI (QPainter)
  - Обработка событий (клики, ввод)
  - Чтение из SQLite (read-only)
  - Отправка команд в uTun через GuiBridge (Qt signals)

Поток 2 (uTun networking):
  - uasync_mainloop()
  - ETCP соединения
  - ChatSync (P2P синхронизация каналов)
  - Запись в SQLite (thread-safe write)
  - GuiBridge: получение команд через uasync_post + wakeup pipe

Правила межпоточного взаимодействия:

Из GUI → uTun: uasync_post(ua, callback, arg) — thread-safe
Из uTun → GUI: emit Qt signal — Qt thread-safe через queued connection
Память: uasync_memsync(ua) перед post для видимости изменений
БД: chat_core (uTun поток) пишет, DbManager (GUI поток) читает

11.3 Windows TUN (дополнительный поток)

На Windows TUN чтение выполняется в отдельном потоке tun_read_thread_proc (Wintun API требует dedicated thread). Результаты передаются в главный поток через uasync_post.

12. Жизненный цикл UTUN_INSTANCE

12.1 Инициализация

utun_instance_create(ua, config_path):
  config_ensure_keys_and_node_id()     // авто-генерация ключей при первом запуске
  parse_config(config_path)            // парсинг INI в utun_config
  debug_set_output_file()              // открытие лог-файла
  debug_set_level() per config         // настройка уровней отладки

  instance_init_common(instance, ua, config):
    1. Копирование name, node_id из конфига
    2. sc_init_local_keys()           // загрузка X25519 ключей
    3. sc_derive_ed25519_pubkey()     // деривация Ed25519 ключей
    4. queue_new() для networks       // хеш-очередь сетей
    5. queue_new() для connections    // хеш-очередь ETCP соединений
    6. memory_pool_init() ×3          // data_pool, pkt_pool, ack_pool
    7. routing_create(instance)       // таблица маршрутов
    8. tun_init()                     // TUN интерфейс
    9. init_sockets(instance)         // UDP сокеты из [server]
    10. topo_groups_init(instance)    // BGP группы + SQLite
    11. topo_group_update_my_nodeinfo() // локальный узел
    12. conn_mgr_init(instance)       // менеджер соединений
    13. fw_init() + fw_load_rules()   // firewall
    14. etcp_router_init(instance)    // сервисный роутер
    15. routing_bind(instance)        // привязка data handler
    16. tcp_proxy_server_init()       // exit node прокси
    17. tcp_proxy_client_create()     // клиентский прокси (если включён)

utun_instance_init(instance):
    1. db_sync_init(instance)         // распределённая БД
    2. routing_set_tun(instance)      // подключение TUN к роутингу
    3. nat_transport_init(instance)   // NAT транспорт
    4. init_connections(instance)     // ETCP соединения из [client]
    5. control_server_init()          // мониторинг
    6. running = 1
    8. ntp_time_init()                // NTP синхронизация
    9. ntp_node_time_init()           // межузловое время

12.2 Завершение (строго обратный порядок)

utun_instance_destroy(instance):
  1. running = 0
  2. Отмена NTP таймеров
  3. control_server_destroy()        // потом мониторинг
  5. Закрытие всех UDP сокетов       // etcp_socket_remove() для каждого
  6. db_sync_destroy()
  7. etcp_connection_close() для всех соединений в connections
  8. uasync_poll() до опустошения deferred callbacks
  9. Отмена pending_pings
  10. tun_route_del_all() + tun_close()  // TUN
  11. tcp_proxy_client_destroy()
  12. tcp_proxy_server_destroy()
  13. routing_destroy()
  14. nat_transport_destroy()
  15. etcp_router_destroy()
  16. conn_mgr_destroy()
  17. topo_groups_destroy()
  18. fw_free()
  19. stcp_link_server_destroy()
  20. networks queue очистка
  21. free_config()                  // освобождение конфига
  22. memory_pool_destroy() ×3       // pkt_pool, ack_pool, data_pool (порядок важен!)
  23. u_free(instance)

12.3 2-phase cleanup ETCP_CONN

etcp_connection_close(etcp):
  Phase 1:
    - очистка таймеров
    - уничтожение линков (etcp_link_free)
    - уничтожение нормализатора
    - удаление из instance->connections
    - state = 2 (deleted)

  Phase 2 (if ref_count == 0):
    - uasync_call_soon(etcp_connection_free_deferred)
    - на следующей итерации event loop:
      - освобождение всех очередей
      - освобождение crypto_ctx
      - u_free(etcp)

Зачем 2 фазы:
  - close может быть вызван из callback того же ETCP_CONN
  - нельзя освобождать память пока мы ещё в стеке вызова callback
  - call_soon гарантирует что стек полностью размотается перед free

12.4 Reload

utun_instance_reload(instance, new_config_path):
  - парсинг нового конфига
  - сравнение [server] секций: удалить удалённые, добавить новые
  - сравнение [client] секций: закрыть ненужные соединения, открыть новые
  - обновление firewall, NAT, keepalive параметров
  - замена instance->config → free_config(old)

Приложение A: Полный список очередей в системе

Модуль	Очередь	Тип	Назначение
tun_if	`tun->output_queue`	FIFO	TUN → routing
tun_if	`tun->input_queue`	FIFO	routing → TUN
routing	`routing_pkt` (через etcp_router)	—	IP-пакеты на маршрутизацию
pkt_normalizer	`pn->input`	FIFO	Пакеты на фрагментацию
pkt_normalizer	`pn->output`	FIFO	Собранные пакеты
etcp	`send_input_q`	FIFO	Вход от нормализатора
etcp	`input_queue`	FIFO	Фрагменты → inflight
etcp	`input_send_q`	hash(seq)	Готовые к отправке
etcp	`input_wait_ack`	hash(seq)	Отправленные, ждут ACK
etcp	`recv_q`	hash(seq)	Принятые не по порядку
etcp	`output_queue`	FIFO	Собранные данные
etcp	`ack_q`	hash(seq)	Неотправленные ACK
etcp	`transit_queues`	hash(src,dst)	Транзитные пакеты
etcp_router	`rconn->incoming_q`	FIFO	Входящие router-пакеты
etcp_router	`rconn->recv_q`	hash(seq)	Реордеринг router-пакетов
etcp_router	`rconn->send_q`	FIFO	Заблокированные на отправку
etcp_router	`rconn->inflight_q`	hash(seq)	Копии для ретрансмиссии
topo_group	`group->nodes`	hash(node_id)	Все известные узлы
topo_group	`group->senders_list`	linked list	BGP-пиры
utun_instance	`instance->connections`	hash(peer_node_id)	Все ETCP_CONN
utun_instance	`instance->networks`	hash(network_id)	Доверенные сети
conn_mgr	`mgr->entries[]`	dynamic array	Состояния подключений

Приложение B: Основные таймауты и константы

Константа	Значение	Где используется
ETCP retrans min	5ms (50 tb)	etcp ack_timeout_check
ETCP retrans max	1000ms (10000 tb)	etcp ack_timeout_check
ETCP delayed ACK	2ms (20 tb)	etcp ack_response_timer
Router retrans init	300ms	etcp_router retrans_timer
Router retrans max tries	17 (~5s)	etcp_router
Router minRTT probe interval	10s	etcp_router
Keepalive interval (active)	200ms	etcp_connections
Keepalive interval (idle)	10s	etcp_connections
INIT retrans init	500ms	etcp_connections
INIT retrans max	3200ms	etcp_connections
conn_mgr DIRECT timeout	5s	conn_mgr
conn_mgr REVERSE/INDIRECT timeout	15s	conn_mgr
Normalizer frag_size	mtu - ACK_RESERVE - UDP_HDR - SC_HDR	~1553 bytes
BBR burst packets	12	etcp burst measurement
BBR max cwnd	1MB (configurable)	etcp_bbr
lwIP TCP_RTO_MIN	3000ms	lwip_tcp
lwIP TCP_MSL	60s	lwip_tcp
UDP proxy flow expiry	60s	udp_proxy
ICMP proxy request timeout	5s	icmp_proxy
db_sync record batch	32	db_sync
BGP max hops	16	topo_group
BGP MAX_ADDR_TYPES	16	topo_node

Приложение C: Ключевые callback-цепочки

C.1 Новое ETCP соединение

etcp_connection_create()
  → new_conn_cbks chain (topo_group_etcp_conn_cbk, ...)
    → topo_group: up/down callbacks on connection
  → etcp_conn_queue_set_ready()
    → ready_cbks chain

etcp_on_up()
  → up_cbks chain (topo_group_on_conn_up, conn_mgr notification, ...)
    → topo_group_on_conn_up: BGP full table sync

C.2 Получение данных (снизу вверх)

UDP recv → sc_decrypt
  → etcp_conn_input: parse sections, ACK processing, store in recv_q
    → etcp_output_try_assembly: output_queue
      → pn_unpacker_cb: reassemble
        → etcp_int_recv: dispatch by cmd byte
          → cmd=0x03: etcp_router_recv_cb
            → router_handle_data_packet
              → incoming_q callback
                → router_try_assembly
                  → service callback (routing_pkt_from_etcp_cb, proxy, chat, ...)

C.3 Отправка данных (сверху вниз)

service (routing, proxy, chat)
  → etcp_route_send / etcp_router_conn_send
    → router_send_one: SVC_ROUTE_HDR + inflight_q
      → etcp_send: send_input_q
        → pkt_normalizer packer: fragment
          → etcp->input_queue
            → input_queue_cb: INFLIGHT_PACKET
              → input_send_q
                → process_send_queue: etcp_request_pkt
                  → loadbalancer_select_link
                    → etcp_encrypt_send: sc_encrypt
                      → socket_sendto

Документ основан на анализе исходного кода uTun. Для каждого модуля доступен отдельный _doc.md файл с детальным описанием API.

57 KiB Raw Blame History