some ai docs
This commit is contained in:
@@ -0,0 +1,351 @@
|
|||||||
|
# Crypto Module Documentation
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Данный модуль реализует криптографическую основу протокола:
|
||||||
|
|
||||||
|
- согласование ключей (ECDH, X25519)
|
||||||
|
- derivation ключей (HKDF-SHA256)
|
||||||
|
- симметричное шифрование (ChaCha20-Poly1305, AEAD)
|
||||||
|
- аутентификация с плавающим временным окном (HMAC)
|
||||||
|
|
||||||
|
Архитектура разделена на независимые компоненты:
|
||||||
|
|
||||||
|
- `ecdh` — обмен ключами
|
||||||
|
- `hkdf` — derivation ключей
|
||||||
|
- `session` — управление состоянием сессии
|
||||||
|
- `chacha` — AEAD шифрование
|
||||||
|
- `aead` — абстракция шифрования
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Security Model
|
||||||
|
|
||||||
|
Модель безопасности:
|
||||||
|
|
||||||
|
- Forward secrecy обеспечивается за счёт `EphemeralSecret`
|
||||||
|
- Каждая сессия использует уникальные:
|
||||||
|
- salt (локальный + удалённый)
|
||||||
|
- ephemeral key pair
|
||||||
|
- Ключи разделены по направлениям:
|
||||||
|
- client → server
|
||||||
|
- server → client
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Key Exchange (ECDH)
|
||||||
|
|
||||||
|
### Реализация
|
||||||
|
|
||||||
|
Используется:
|
||||||
|
|
||||||
|
- X25519 (через `x25519-dalek`)
|
||||||
|
- Ephemeral ключи
|
||||||
|
|
||||||
|
````rust
|
||||||
|
let secret = EphemeralSecret::random_from_rng(&mut OsRng);
|
||||||
|
let public = PublicKey::from(&secret);
|
||||||
|
|
||||||
|
### Shared Secret
|
||||||
|
|
||||||
|
```rust
|
||||||
|
shared = private.diffie_hellman(remote_public)
|
||||||
|
````
|
||||||
|
|
||||||
|
Особенности:
|
||||||
|
|
||||||
|
- приватный ключ используется **один раз** (`take()`)
|
||||||
|
- после вызова `get_shared()` он уничтожается
|
||||||
|
|
||||||
|
Это критично для:
|
||||||
|
|
||||||
|
- forward secrecy
|
||||||
|
- защиты от повторного использования
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Salt Mechanism
|
||||||
|
|
||||||
|
### SaltPair
|
||||||
|
|
||||||
|
Каждая сторона генерирует:
|
||||||
|
|
||||||
|
- `local_salt` (32 байта, случайный)
|
||||||
|
- получает `remote_salt`
|
||||||
|
|
||||||
|
Финальный salt:
|
||||||
|
|
||||||
|
```
|
||||||
|
initiator:
|
||||||
|
total = local || remote
|
||||||
|
|
||||||
|
responder:
|
||||||
|
total = remote || local
|
||||||
|
```
|
||||||
|
|
||||||
|
Это гарантирует:
|
||||||
|
|
||||||
|
- детерминированность
|
||||||
|
- отсутствие коллизий ролей
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Key Derivation (HKDF)
|
||||||
|
|
||||||
|
Используется:
|
||||||
|
|
||||||
|
- HKDF-SHA256
|
||||||
|
|
||||||
|
### Extract
|
||||||
|
|
||||||
|
```
|
||||||
|
PRK = HKDF(salt, shared_secret)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Expand
|
||||||
|
|
||||||
|
Из PRK генерируются:
|
||||||
|
|
||||||
|
| Назначение | Размер |
|
||||||
|
| --------------- | ------ |
|
||||||
|
| client_aead key | 32 |
|
||||||
|
| client_iv | 12 |
|
||||||
|
| server_aead key | 32 |
|
||||||
|
| server_iv | 12 |
|
||||||
|
| auth_key | 32 |
|
||||||
|
|
||||||
|
Пример:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
HKDF::expand_key::<32>(&hkdf, b"client_aead")
|
||||||
|
```
|
||||||
|
|
||||||
|
Контекст (`mark`) используется как label.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## SessionKeys
|
||||||
|
|
||||||
|
Центральная структура управления:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
pub struct SessionKeys {
|
||||||
|
salt: SaltPair,
|
||||||
|
ecdh: ECDH,
|
||||||
|
auth_key: [u8; 32],
|
||||||
|
current_aead: Option<(...)>,
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Основные задачи:
|
||||||
|
|
||||||
|
1. Принять remote salt
|
||||||
|
2. Извлечь публичный ключ из TLS extension
|
||||||
|
3. Выполнить ECDH
|
||||||
|
4. Сгенерировать ключи
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## TLS Integration
|
||||||
|
|
||||||
|
Ключ извлекается из `ExtensionStack`:
|
||||||
|
|
||||||
|
- extension type: `0x0033` (KeyShare)
|
||||||
|
- поддерживается X25519 (`0x001d`)
|
||||||
|
|
||||||
|
### Client / Server различия
|
||||||
|
|
||||||
|
**Server:**
|
||||||
|
|
||||||
|
- парсит ClientHello
|
||||||
|
- ищет key share внутри структуры
|
||||||
|
|
||||||
|
**Client:**
|
||||||
|
|
||||||
|
- читает фиксированное смещение
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## AEAD Encryption (ChaCha20-Poly1305)
|
||||||
|
|
||||||
|
### Используемый алгоритм
|
||||||
|
|
||||||
|
- ChaCha20-Poly1305
|
||||||
|
- 256-bit key
|
||||||
|
- 96-bit nonce
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Nonce Strategy
|
||||||
|
|
||||||
|
### NonceState
|
||||||
|
|
||||||
|
```rust
|
||||||
|
nonce = base_iv XOR counter
|
||||||
|
```
|
||||||
|
|
||||||
|
Где:
|
||||||
|
|
||||||
|
- `base_iv` — получен из HKDF
|
||||||
|
- `counter` — 64-bit
|
||||||
|
|
||||||
|
Алгоритм:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
for i in 0..8:
|
||||||
|
iv[i+4] ^= counter[i]
|
||||||
|
```
|
||||||
|
|
||||||
|
Особенности:
|
||||||
|
|
||||||
|
- гарантированная уникальность nonce
|
||||||
|
- отсутствие повторов при корректной работе
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Cipher Structure
|
||||||
|
|
||||||
|
```rust
|
||||||
|
pub struct ChaChaCipher {
|
||||||
|
encrypt_cipher,
|
||||||
|
decrypt_cipher,
|
||||||
|
encrypt_state,
|
||||||
|
decrypt_state,
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Разделение:
|
||||||
|
|
||||||
|
- отдельные ключи и nonce для каждого направления
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Encryption Flow
|
||||||
|
|
||||||
|
```rust
|
||||||
|
encrypt_in_place(nonce, aad=nonce, data)
|
||||||
|
```
|
||||||
|
|
||||||
|
AAD:
|
||||||
|
|
||||||
|
- используется сам nonce
|
||||||
|
|
||||||
|
После:
|
||||||
|
|
||||||
|
- данные мутируются
|
||||||
|
- тег добавляется автоматически
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Decryption Flow
|
||||||
|
|
||||||
|
```rust
|
||||||
|
decrypt_in_place(nonce, aad=nonce, data)
|
||||||
|
```
|
||||||
|
|
||||||
|
При ошибке:
|
||||||
|
|
||||||
|
- ошибка аутентификации
|
||||||
|
- повреждённые данные
|
||||||
|
- несинхронный nonce
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Authentication Layer
|
||||||
|
|
||||||
|
Дополнительный механизм:
|
||||||
|
|
||||||
|
### HMAC-SHA256
|
||||||
|
|
||||||
|
```rust
|
||||||
|
tag = HMAC(auth_key, time_step)
|
||||||
|
```
|
||||||
|
|
||||||
|
Где:
|
||||||
|
|
||||||
|
```
|
||||||
|
time_step = unix_time / 60
|
||||||
|
```
|
||||||
|
|
||||||
|
### Проверка
|
||||||
|
|
||||||
|
Принимаются значения:
|
||||||
|
|
||||||
|
```
|
||||||
|
[t-2, t-1, t, t+1, t+2]
|
||||||
|
```
|
||||||
|
|
||||||
|
Назначение:
|
||||||
|
|
||||||
|
- защита от replay
|
||||||
|
- tolerance к рассинхрону времени
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## AeadPacker Trait
|
||||||
|
|
||||||
|
Абстракция для шифрования:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
trait AeadPacker {
|
||||||
|
fn encrypt(...)
|
||||||
|
fn decrypt(...)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Позволяет:
|
||||||
|
|
||||||
|
- заменить алгоритм
|
||||||
|
- тестировать разные реализации
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
Ошибки возникают в случаях:
|
||||||
|
|
||||||
|
- неизвестный протокол / extension
|
||||||
|
- повреждённые данные
|
||||||
|
- неверный AEAD tag
|
||||||
|
- отсутствие shared secret
|
||||||
|
|
||||||
|
Возвращаются:
|
||||||
|
|
||||||
|
- `Result<T, String>`
|
||||||
|
- `aead::Error`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Important Security Notes
|
||||||
|
|
||||||
|
1. Ephemeral ключ используется только один раз
|
||||||
|
2. Nonce никогда не должен повторяться
|
||||||
|
3. Salt обязателен с обеих сторон
|
||||||
|
4. AEAD тег обязателен (встроен)
|
||||||
|
5. Временные теги не заменяют AEAD
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Limitations
|
||||||
|
|
||||||
|
- Нет re-keying
|
||||||
|
- Нет защиты от state desync (nonce)
|
||||||
|
- Нет replay protection на уровне пакетов (только time-based)
|
||||||
|
- Жёстко задан HKDF context strings
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
Модуль реализует:
|
||||||
|
|
||||||
|
- безопасный ECDH handshake
|
||||||
|
- детерминированный key derivation
|
||||||
|
- AEAD шифрование с разделением направлений
|
||||||
|
- дополнительную HMAC-аутентификацию
|
||||||
|
|
||||||
|
Подходит для:
|
||||||
|
|
||||||
|
- пользовательских протоколов
|
||||||
|
- туннелей
|
||||||
|
- транспортных шифрованных каналов
|
||||||
@@ -0,0 +1,448 @@
|
|||||||
|
# Network Module Documentation
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Данный модуль реализует сетевую часть VPN ядра:
|
||||||
|
|
||||||
|
- входные TCP соединения (SOCKS / туннель)
|
||||||
|
- мультиплексирование потоков поверх одного соединения
|
||||||
|
- транспорт кадров (Frame)
|
||||||
|
- проксирование TCP/UDP
|
||||||
|
- управление туннелем (TunnelEngine)
|
||||||
|
|
||||||
|
Архитектура:
|
||||||
|
|
||||||
|
- network — точка входа (listener + режим)
|
||||||
|
- connection — логика соединений
|
||||||
|
- muxer — мультиплексирование потоков
|
||||||
|
- handler — обработка входящих фреймов
|
||||||
|
- engine — основной цикл туннеля
|
||||||
|
- bridge — проксирование сокетов
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## High-Level Architecture
|
||||||
|
|
||||||
|
Система работает по схеме:
|
||||||
|
|
||||||
|
Client (SOCKS)
|
||||||
|
→ Muxer
|
||||||
|
→ TunnelEngine (шифрованный канал)
|
||||||
|
→ Server
|
||||||
|
→ StreamHandler
|
||||||
|
→ TCP/UDP target
|
||||||
|
|
||||||
|
И обратно.
|
||||||
|
|
||||||
|
Ключевая идея:
|
||||||
|
ОДНО TCP соединение = МНОГО логических потоков (stream_id)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Network
|
||||||
|
|
||||||
|
### Назначение
|
||||||
|
|
||||||
|
Точка входа:
|
||||||
|
|
||||||
|
- запускает TCP listener
|
||||||
|
- определяет режим (Client / Server)
|
||||||
|
- управляет lifecycle
|
||||||
|
|
||||||
|
### Режимы
|
||||||
|
|
||||||
|
#### Client
|
||||||
|
|
||||||
|
- Подключается к удалённому proxy
|
||||||
|
- Поднимает SOCKS сервер
|
||||||
|
- Каждый входящий клиент → новый stream
|
||||||
|
|
||||||
|
#### Server
|
||||||
|
|
||||||
|
- Принимает туннельные соединения
|
||||||
|
- Обрабатывает handshake
|
||||||
|
- Создаёт TunnelEngine
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## NetworkConfig
|
||||||
|
|
||||||
|
Глобальная конфигурация (OnceLock)
|
||||||
|
|
||||||
|
### Основные параметры
|
||||||
|
|
||||||
|
- mtu — системный MTU
|
||||||
|
- max_wire_frame_size — MTU минус overhead
|
||||||
|
- safe_payload_size — безопасный payload
|
||||||
|
- tcp_buffer_size — буфер TCP
|
||||||
|
- udp_buffer_size — буфер UDP
|
||||||
|
- channel_capacity — размер каналов
|
||||||
|
|
||||||
|
### Расчёт
|
||||||
|
|
||||||
|
safe_payload = MTU
|
||||||
|
|
||||||
|
- IPv4/UDP overhead (~28)
|
||||||
|
- frame header
|
||||||
|
- padding
|
||||||
|
|
||||||
|
Цель:
|
||||||
|
|
||||||
|
- не фрагментировать пакеты
|
||||||
|
- держаться в ~1400 байт
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Connection
|
||||||
|
|
||||||
|
Обёртка над TCP соединением
|
||||||
|
|
||||||
|
### Содержит:
|
||||||
|
|
||||||
|
- inbound (read half)
|
||||||
|
- outbound (write half)
|
||||||
|
- read buffer
|
||||||
|
- codec (шифрование + framing)
|
||||||
|
|
||||||
|
### Основные функции
|
||||||
|
|
||||||
|
#### read_socks_request
|
||||||
|
|
||||||
|
- читает из буфера
|
||||||
|
- использует Parser trait
|
||||||
|
- ждёт пока данных достаточно
|
||||||
|
|
||||||
|
#### send_socks_reply
|
||||||
|
|
||||||
|
- сериализует ответ
|
||||||
|
- отправляет клиенту
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ClientHandler
|
||||||
|
|
||||||
|
### Назначение
|
||||||
|
|
||||||
|
- реализует SOCKS5 сервер
|
||||||
|
- преобразует запросы в multiplexed streams
|
||||||
|
|
||||||
|
### Flow
|
||||||
|
|
||||||
|
1. SOCKS handshake
|
||||||
|
2. SOCKS request (CONNECT / UDP)
|
||||||
|
3. Создание stream_id
|
||||||
|
4. Регистрация канала
|
||||||
|
5. Отправка FrameType::Connect
|
||||||
|
6. Ожидание ответа от сервера
|
||||||
|
7. Запуск bridge
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ServerHandler
|
||||||
|
|
||||||
|
### Назначение
|
||||||
|
|
||||||
|
- принимает туннель
|
||||||
|
- делает TLS-like handshake
|
||||||
|
- запускает TunnelEngine
|
||||||
|
|
||||||
|
### Особенность: Stealth Fallback
|
||||||
|
|
||||||
|
Если:
|
||||||
|
|
||||||
|
- handshake не прошёл
|
||||||
|
- таймаут
|
||||||
|
|
||||||
|
→ соединение проксируется как обычный TLS (на ubuntu.com:443)
|
||||||
|
|
||||||
|
Это:
|
||||||
|
|
||||||
|
- маскирует трафик
|
||||||
|
- снижает вероятность блокировки
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Muxer
|
||||||
|
|
||||||
|
### Назначение
|
||||||
|
|
||||||
|
Мультиплексирование потоков
|
||||||
|
|
||||||
|
### Компоненты
|
||||||
|
|
||||||
|
- control_tx — управляющие сообщения
|
||||||
|
- data_tx — данные
|
||||||
|
- streams — map stream_id → channel
|
||||||
|
- id_gen — генератор ID
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Stream ID
|
||||||
|
|
||||||
|
Генерация:
|
||||||
|
|
||||||
|
- клиент: 1, 3, 5, ...
|
||||||
|
- сервер: 2, 4, 6, ...
|
||||||
|
|
||||||
|
Это гарантирует:
|
||||||
|
|
||||||
|
- отсутствие коллизий
|
||||||
|
- определение стороны
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## MuxMessage
|
||||||
|
|
||||||
|
Структура:
|
||||||
|
|
||||||
|
- stream_id
|
||||||
|
- frame_type
|
||||||
|
- data
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Отправка данных
|
||||||
|
|
||||||
|
### send_data_safe
|
||||||
|
|
||||||
|
Если payload большой:
|
||||||
|
|
||||||
|
- режется на куски (~1300 байт)
|
||||||
|
- отправляется последовательно
|
||||||
|
|
||||||
|
Причина:
|
||||||
|
|
||||||
|
- не превышать MTU
|
||||||
|
- избежать фрагментации
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## StreamHandler
|
||||||
|
|
||||||
|
### Назначение
|
||||||
|
|
||||||
|
Обработка входящих Frame
|
||||||
|
|
||||||
|
### Типы Frame
|
||||||
|
|
||||||
|
- Connect
|
||||||
|
- UdpConnect
|
||||||
|
- Data
|
||||||
|
- UdpData
|
||||||
|
- Close
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## TCP Flow (Server)
|
||||||
|
|
||||||
|
1. Получен Connect
|
||||||
|
2. Парсится target
|
||||||
|
3. Открывается TCP соединение
|
||||||
|
4. Отправляется SOCKS reply
|
||||||
|
5. Запускается run_tcp_bridge
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## UDP Flow
|
||||||
|
|
||||||
|
1. bind UDP socket
|
||||||
|
2. connect(target)
|
||||||
|
3. запуск run_udp_bridge
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## TunnelEngine
|
||||||
|
|
||||||
|
### Центральный компонент
|
||||||
|
|
||||||
|
Отвечает за:
|
||||||
|
|
||||||
|
- чтение из сети
|
||||||
|
- декодирование
|
||||||
|
- dispatch
|
||||||
|
- шифрование
|
||||||
|
- запись
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Reader Task
|
||||||
|
|
||||||
|
Цикл:
|
||||||
|
|
||||||
|
1. read_buf
|
||||||
|
2. codec.inbound()
|
||||||
|
3. извлечение frame
|
||||||
|
4. handler.handle(frame)
|
||||||
|
|
||||||
|
### Ошибки
|
||||||
|
|
||||||
|
- Wait → ждём данных
|
||||||
|
- Drop → критическая ошибка (tampering)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Writer Task
|
||||||
|
|
||||||
|
Обрабатывает:
|
||||||
|
|
||||||
|
- control сообщения (приоритет)
|
||||||
|
- heartbeat
|
||||||
|
- data сообщения
|
||||||
|
|
||||||
|
### Heartbeat
|
||||||
|
|
||||||
|
Каждые 15 секунд:
|
||||||
|
FrameType::Heartbeat
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## handle_outbound
|
||||||
|
|
||||||
|
Flow:
|
||||||
|
|
||||||
|
1. chunking (4KB)
|
||||||
|
2. encrypt_data()
|
||||||
|
3. write_all()
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Bridge Layer
|
||||||
|
|
||||||
|
### run_tcp_bridge
|
||||||
|
|
||||||
|
Два направления:
|
||||||
|
|
||||||
|
1. socket → muxer
|
||||||
|
2. muxer → socket
|
||||||
|
|
||||||
|
Особенности:
|
||||||
|
|
||||||
|
- неблокирующий select
|
||||||
|
- graceful close
|
||||||
|
- отправка Close frame
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### run_udp_bridge
|
||||||
|
|
||||||
|
Аналог TCP, но:
|
||||||
|
|
||||||
|
- recv/send
|
||||||
|
- без stream (datagram)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Поток данных (End-to-End)
|
||||||
|
|
||||||
|
Client:
|
||||||
|
|
||||||
|
browser → SOCKS → ClientHandler
|
||||||
|
→ Muxer → TunnelEngine
|
||||||
|
→ encrypted TCP
|
||||||
|
|
||||||
|
Server:
|
||||||
|
|
||||||
|
→ TunnelEngine → StreamHandler
|
||||||
|
→ TCP connect → target
|
||||||
|
|
||||||
|
Ответ обратно тем же путём.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
Критические ошибки:
|
||||||
|
|
||||||
|
- codec Drop → разрыв туннеля
|
||||||
|
- write error → закрытие stream
|
||||||
|
- read EOF → завершение
|
||||||
|
|
||||||
|
Некритические:
|
||||||
|
|
||||||
|
- закрыт канал → удаление stream
|
||||||
|
- неизвестный stream → игнор
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Concurrency Model
|
||||||
|
|
||||||
|
Используется:
|
||||||
|
|
||||||
|
- tokio tasks
|
||||||
|
- mpsc каналы
|
||||||
|
- Arc + DashMap
|
||||||
|
|
||||||
|
Параллелизм:
|
||||||
|
|
||||||
|
- каждый stream независим
|
||||||
|
- reader / writer разделены
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Design Decisions
|
||||||
|
|
||||||
|
### 1. Один туннель
|
||||||
|
|
||||||
|
Плюсы:
|
||||||
|
|
||||||
|
- меньше соединений
|
||||||
|
- проще маскировка
|
||||||
|
|
||||||
|
Минусы:
|
||||||
|
|
||||||
|
- single point of failure
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2. Multiplexing
|
||||||
|
|
||||||
|
Плюсы:
|
||||||
|
|
||||||
|
- высокая эффективность
|
||||||
|
- меньше latency
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3. Chunking
|
||||||
|
|
||||||
|
Причины:
|
||||||
|
|
||||||
|
- MTU ограничения
|
||||||
|
- стабильность
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 4. Stealth fallback
|
||||||
|
|
||||||
|
Критично для:
|
||||||
|
|
||||||
|
- обход DPI
|
||||||
|
- маскировка под TLS
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Limitations
|
||||||
|
|
||||||
|
- Нет QoS между потоками
|
||||||
|
- Нет backpressure контроля
|
||||||
|
- Нет retransmission (TCP полагается на underlying)
|
||||||
|
- Нет stream prioritization
|
||||||
|
- UDP без гарантии доставки
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
Модуль реализует:
|
||||||
|
|
||||||
|
- TCP listener (client/server)
|
||||||
|
- multiplexed туннель
|
||||||
|
- безопасную передачу данных
|
||||||
|
- проксирование TCP/UDP
|
||||||
|
- fallback механизм маскировки
|
||||||
|
|
||||||
|
Это полноценное сетевое ядро VPN:
|
||||||
|
|
||||||
|
- scalable
|
||||||
|
- асинхронное
|
||||||
|
- расширяемое
|
||||||
@@ -3,5 +3,3 @@ pub mod connection;
|
|||||||
pub mod engine;
|
pub mod engine;
|
||||||
pub mod handler;
|
pub mod handler;
|
||||||
pub mod muxer;
|
pub mod muxer;
|
||||||
|
|
||||||
pub const MESSAGE_CHANNEL_SIZE: usize = 4;
|
|
||||||
|
|||||||
+354
-68
@@ -1,85 +1,371 @@
|
|||||||
# Netrunner TLS Engine (`tlseng`)
|
---
|
||||||
|
|
||||||
Модуль `tlseng` — это высокопроизводительное ядро для генерации, парсинга и манипуляции TLS-трафиком (TLS 1.2 / TLS 1.3). Основная задача движка — **обход систем глубокого анализа трафика (DPI)** и активных проб (Active Probing) путем идеальной мимикрии под легитимный трафик современных браузеров.
|
# TLS Engine (Masking + Parsing)
|
||||||
|
|
||||||
Движок не является полноценной реализацией криптографического стека TLS. Это "умный фасад", который формирует криптографически достоверные пакеты `ClientHello` и `ServerHello`, позволяя скрыто передавать авторизационные данные и устанавливать защищенные туннели, неотличимые от обычного HTTPS-трафика.
|
## Обзор
|
||||||
|
|
||||||
## 🌟 Ключевые возможности
|
Этот модуль реализует:
|
||||||
|
|
||||||
- **Perfect Fingerprint Mimicry (JA3 / JA4):** Полная имитация параметров расширений, порядка их следования, поддерживаемых групп и наборов шифров. Движок генерирует отпечатки, на 100% совпадающие с реальными браузерами (Chrome, Edge, Firefox, Safari).
|
- Генерацию TLS ClientHello / ServerHello с профилями браузеров
|
||||||
- **Stealth Authentication (Stateless):** Уникальный механизм скрытой авторизации. Токен доступа (Auth Tag) маскируется внутри поля `Session ID` (TLS 1.3 эхо), что позволяет серверу аутентифицировать клиента еще до начала обмена Application Data, не привлекая внимания DPI.
|
- Гибкую сборку TLS Extensions (включая GREASE, padding, ALPS)
|
||||||
- **Advanced GREASE Support:** Автоматическая и контекстно-зависимая генерация случайных идентификаторов (GREASE) согласно RFC 8701 для обхода сигнатурных фильтров, специфичных для Chromium-браузеров.
|
- Парсинг TLS-records и handshake-сообщений
|
||||||
- **Smart Padding:** Интеллектуальный расчет расширения `Padding` с учетом размера всех заголовков (overhead) для выравнивания пакета `ClientHello` до заданного размера (например, ровно 512 байт для Chrome), исключая эвристическое детектирование по длине пакета.
|
- Маскировку под реальные браузеры (Chrome / Firefox)
|
||||||
- **Zero-Copy Parsing:** Использование крейта `bytes` (`Bytes`, `BytesMut`) для парсинга и сериализации пакетов без лишних аллокаций в памяти.
|
- Минимальный TLS-стек для кастомного протокола
|
||||||
|
|
||||||
## 🏗 Архитектура модулей
|
Фокус: **fingerprint mimicry**, а не полный TLS стек.
|
||||||
|
|
||||||
Структура модуля разделена на логические компоненты для максимальной гибкости и расширяемости:
|
---
|
||||||
|
|
||||||
- **`profile/`**: База данных профилей браузеров и серверов (`BrowserProfile`, `ServerProfile`). Содержит константы для версий, шифров, наличия GREASE, ALPS и целевого размера паддинга.
|
## Архитектура
|
||||||
- **`extension/`**: Мощный и потокобезопасный `ExtensionBuilder` для сборки TLS-расширений (SNI, ALPN, KeyShare, ALPS, Supported Versions и т.д.) в строгом соответствии с профилем.
|
|
||||||
- **`handshake/`**: Реализация структур `ClientHello` и `ServerHello`. Управляет генерацией рандома, встраиванием скрытых тегов и выбором шифров.
|
|
||||||
- **`tls_record/`**: Низкоуровневая инкапсуляция данных в `TlsRecord` с правильным указанием версий (маскировка Record Layer Version под `0x0301`).
|
|
||||||
- **`types/` и `consts/`**: Строго типизированные перечисления (Enums) и константы протокола TLS.
|
|
||||||
|
|
||||||
## 🛠 Глубокое погружение: Как это работает
|
```
|
||||||
|
tlseng/
|
||||||
|
├── consts.rs # TLS константы
|
||||||
|
├── extension.rs # Extensions builder + parser
|
||||||
|
├── handshake.rs # ClientHello / ServerHello
|
||||||
|
├── profile.rs # Browser / Server profiles
|
||||||
|
├── tls_record.rs # TLS record layer
|
||||||
|
├── types.rs # enums + структуры
|
||||||
|
```
|
||||||
|
|
||||||
### 1. Профилирование трафика
|
---
|
||||||
|
|
||||||
Движок не хардкодит расширения. Вместо этого `ExtensionBuilder` принимает `BrowserProfile`. Профиль указывает, нужны ли GREASE-значения, какой должен быть `ExtensionOrder` (порядок следования) и до какого размера "надувать" пакет паддингом. Это позволяет в одну строчку переключать маскировку с Chrome 131 на Firefox 130.
|
## Основные компоненты
|
||||||
|
|
||||||
### 2. Скрытая авторизация (Session ID Auth)
|
### 1. TLS Record Layer
|
||||||
|
|
||||||
В TLS 1.3 поле `Session ID` сохранено для обратной совместимости (Middlebox Compatibility Mode).
|
Файл: `tls_record.rs`
|
||||||
`tlseng` использует это 32-байтовое поле как контейнер:
|
|
||||||
|
|
||||||
1. **Клиент:** Заполняет первые 16 байт случайными данными, а в последние 16 байт записывает HMAC (Auth Tag), сгенерированный на основе локального времени и мастер-ключа.
|
Реализует базовый TLS record:
|
||||||
2. **DPI:** Видит стандартный 32-байтовый массив, неотличимый от обычного рандома.
|
|
||||||
3. **Сервер:** Извлекает последние 16 байт из `ClientHello` и верифицирует их. Если проверка не пройдена, соединение разрывается (защита от активного сканирования). Если пройдена — сервер возвращает этот же `Session ID` эхом в `ServerHello`.
|
|
||||||
|
|
||||||
## 🚀 Примеры использования
|
|
||||||
|
|
||||||
### Генерация `ClientHello` (на стороне клиента)
|
|
||||||
|
|
||||||
Создание маскировочного пакета под Chrome 131 со встроенной авторизацией:
|
|
||||||
|
|
||||||
```rust
|
```rust
|
||||||
use crate::tlseng::profile::BrowserProfile;
|
struct TlsRecord {
|
||||||
use crate::tlseng::extension::ExtensionBuilder;
|
content_type: ContentType,
|
||||||
use crate::tlseng::handshake::ClientHello;
|
version: ProtocolVersion,
|
||||||
use crate::tlseng::tls_record::TlsRecord;
|
payload: Bytes
|
||||||
use bytes::Bytes;
|
|
||||||
|
|
||||||
pub fn make_client_hello(profile: &BrowserProfile, host: &str, keys: &SessionKeys) -> Bytes {
|
|
||||||
let tls_random = keys.salt.get_local();
|
|
||||||
|
|
||||||
// Расчет размера заголовков для точного Padding
|
|
||||||
let overhead = 5 + 4 + 2 + 32 + 1 + 32 + 2 + (profile.cipher_suites.len() * 2) + 2 + 2;
|
|
||||||
|
|
||||||
// Сборка расширений по профилю
|
|
||||||
let mut ext_builder = ExtensionBuilder::new();
|
|
||||||
ext_builder.apply_profile(profile, host, &keys.ecdh.public_key.to_bytes(), overhead);
|
|
||||||
let extensions_bytes = ext_builder.build();
|
|
||||||
|
|
||||||
// Генерация Session ID с Auth Tag
|
|
||||||
let mut session_id_bytes = [0u8; 32];
|
|
||||||
rand::fill(&mut session_id_bytes[..16]);
|
|
||||||
session_id_bytes[16..].copy_from_slice(&keys.generate_auth_tag());
|
|
||||||
|
|
||||||
let client_hello = ClientHello {
|
|
||||||
version: profile.versions.get_legacy(), // Всегда 0x0303 для TLS 1.3
|
|
||||||
random: tls_random,
|
|
||||||
session_id: Bytes::copy_from_slice(&session_id_bytes),
|
|
||||||
cipher_suites: profile.cipher_suites.to_vec(),
|
|
||||||
extensions: extensions_bytes,
|
|
||||||
};
|
|
||||||
|
|
||||||
let record = TlsRecord::new(
|
|
||||||
ContentType::Handshake,
|
|
||||||
profile.record_layer_version, // 0x0301 для маскировки
|
|
||||||
client_hello.serialize(),
|
|
||||||
);
|
|
||||||
|
|
||||||
record.serialize()
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Поддержка:
|
||||||
|
|
||||||
|
- Handshake (0x16)
|
||||||
|
- ApplicationData (0x17)
|
||||||
|
- Alert (0x15)
|
||||||
|
|
||||||
|
Особенности:
|
||||||
|
|
||||||
|
- Минимальная валидация длины
|
||||||
|
- Быстрая сериализация без аллокаций
|
||||||
|
- ApplicationData требует минимум 17 байт (под AEAD)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2. Handshake Layer
|
||||||
|
|
||||||
|
Файл: `handshake.rs`
|
||||||
|
|
||||||
|
#### ClientHello
|
||||||
|
|
||||||
|
Генерация:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
ClientHello::make_client_hello(profile, host, keys)
|
||||||
|
```
|
||||||
|
|
||||||
|
Что делает:
|
||||||
|
|
||||||
|
- Генерирует `random` (через session keys)
|
||||||
|
- Формирует `session_id`:
|
||||||
|
- 16 байт random
|
||||||
|
- 16 байт auth tag
|
||||||
|
|
||||||
|
- Вставляет cipher suites из профиля
|
||||||
|
- Добавляет extensions через `ExtensionBuilder`
|
||||||
|
- Оборачивает в TLS Record
|
||||||
|
|
||||||
|
Особенности:
|
||||||
|
|
||||||
|
- TLS 1.3 masked как TLS 1.2 (version = 0x0303)
|
||||||
|
- Поддержка padding (для fingerprint совпадения)
|
||||||
|
- Полный контроль порядка extensions
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### ServerHello
|
||||||
|
|
||||||
|
```rust
|
||||||
|
ServerHello::make_server_hello(...)
|
||||||
|
```
|
||||||
|
|
||||||
|
- Выбор cipher suite:
|
||||||
|
- либо server order
|
||||||
|
- либо client order
|
||||||
|
|
||||||
|
- Всегда включает:
|
||||||
|
- supported_versions
|
||||||
|
- key_share
|
||||||
|
|
||||||
|
Минимальный TLS 1.3 ServerHello
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3. Extension System
|
||||||
|
|
||||||
|
Файл: `extension.rs`
|
||||||
|
|
||||||
|
#### ExtensionStack (Parser)
|
||||||
|
|
||||||
|
- Парсит список extensions
|
||||||
|
- Проверяет корректность длины
|
||||||
|
- Позволяет искать extension по типу
|
||||||
|
|
||||||
|
```rust
|
||||||
|
find_by_type(etype) -> Option<Bytes>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### ExtensionBuilder
|
||||||
|
|
||||||
|
Ключевой компонент маскировки.
|
||||||
|
|
||||||
|
```rust
|
||||||
|
ExtensionBuilder::apply_profile(profile, host, pub_key, overhead)
|
||||||
|
```
|
||||||
|
|
||||||
|
Поддерживает:
|
||||||
|
|
||||||
|
| Extension | Реализация |
|
||||||
|
| --------------------- | ---------- |
|
||||||
|
| SNI | ✔ |
|
||||||
|
| ALPN | ✔ |
|
||||||
|
| ALPS | ✔ |
|
||||||
|
| Supported Groups | ✔ |
|
||||||
|
| Signature Algorithms | ✔ |
|
||||||
|
| KeyShare | ✔ |
|
||||||
|
| PSK Modes | ✔ |
|
||||||
|
| Padding | ✔ |
|
||||||
|
| GREASE | ✔ |
|
||||||
|
| Compress Certificate | ✔ |
|
||||||
|
| SCT | ✔ |
|
||||||
|
| Delegated Credentials | ✔ |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Особенности
|
||||||
|
|
||||||
|
##### GREASE
|
||||||
|
|
||||||
|
```rust
|
||||||
|
TlsExtensions::is_grease(id)
|
||||||
|
```
|
||||||
|
|
||||||
|
- Проверка по паттерну `0x?a?a`
|
||||||
|
- Вставляется только если `profile.has_grease`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
##### Padding
|
||||||
|
|
||||||
|
```rust
|
||||||
|
padding(target_size, overhead)
|
||||||
|
```
|
||||||
|
|
||||||
|
- Доводит ClientHello до нужного размера
|
||||||
|
- Используется для bypass DPI / fingerprint
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
##### ALPS (Application Settings)
|
||||||
|
|
||||||
|
```rust
|
||||||
|
application_settings(["h2"])
|
||||||
|
```
|
||||||
|
|
||||||
|
- Chromium-only behavior
|
||||||
|
- Добавляется только если есть в профиле
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 4. Profiles (Fingerprint Mimicry)
|
||||||
|
|
||||||
|
Файл: `profile.rs`
|
||||||
|
|
||||||
|
#### BrowserProfile
|
||||||
|
|
||||||
|
Определяет fingerprint:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
pub struct BrowserProfile {
|
||||||
|
groups
|
||||||
|
signatures
|
||||||
|
versions
|
||||||
|
cipher_suites
|
||||||
|
extension_order
|
||||||
|
alpn
|
||||||
|
grease
|
||||||
|
padding
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Примеры
|
||||||
|
|
||||||
|
##### Chrome 131
|
||||||
|
|
||||||
|
- GREASE: включен
|
||||||
|
- ALPS: включен
|
||||||
|
- Padding: 512 bytes
|
||||||
|
- TLS 1.3 only
|
||||||
|
- Record version: TLS 1.0 (как в реальном Chrome)
|
||||||
|
|
||||||
|
##### Firefox 130
|
||||||
|
|
||||||
|
- GREASE: выключен
|
||||||
|
- ALPS: нет
|
||||||
|
- Padding: нет
|
||||||
|
- TLS 1.2 + 1.3
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Extension Order — критично
|
||||||
|
|
||||||
|
```rust
|
||||||
|
ExtensionOrder::CHROMIUM_131
|
||||||
|
```
|
||||||
|
|
||||||
|
Порядок полностью повторяет реальный браузер.
|
||||||
|
|
||||||
|
Это ключ к обходу:
|
||||||
|
|
||||||
|
- JA3 fingerprint
|
||||||
|
- DPI
|
||||||
|
- TLS fingerprinting
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 5. Типы и константы
|
||||||
|
|
||||||
|
Файл: `types.rs`
|
||||||
|
|
||||||
|
Содержит:
|
||||||
|
|
||||||
|
- `ContentType`
|
||||||
|
- `ProtocolVersion`
|
||||||
|
- `HelloType`
|
||||||
|
- `TlsGroups`
|
||||||
|
- `TlsSignatures`
|
||||||
|
- `TlsVersions`
|
||||||
|
- `TlsExtensions`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Важно
|
||||||
|
|
||||||
|
##### TLS Versions
|
||||||
|
|
||||||
|
```rust
|
||||||
|
TlsVersions::TLS_13_ONLY
|
||||||
|
TlsVersions::MODERN
|
||||||
|
```
|
||||||
|
|
||||||
|
Метод:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
max() -> ProtocolVersion
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
##### Supported Groups
|
||||||
|
|
||||||
|
```rust
|
||||||
|
X25519 (0x001d) — основной
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
##### Signature Algorithms
|
||||||
|
|
||||||
|
Совместимы с браузерами:
|
||||||
|
|
||||||
|
- ECDSA
|
||||||
|
- RSA-PSS
|
||||||
|
- RSA PKCS1
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Парсинг
|
||||||
|
|
||||||
|
Все структуры реализуют трейт:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
trait Parser {
|
||||||
|
fn can_parse(...)
|
||||||
|
fn parse(...)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Подход:
|
||||||
|
|
||||||
|
1. `can_parse` — быстрый pre-check без аллокаций
|
||||||
|
2. `parse` — безопасный разбор
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Безопасность и ограничения
|
||||||
|
|
||||||
|
### Что есть
|
||||||
|
|
||||||
|
- Корректная структура TLS
|
||||||
|
- Реалистичный fingerprint
|
||||||
|
- Минимальная валидация
|
||||||
|
|
||||||
|
### Чего нет
|
||||||
|
|
||||||
|
- Полного TLS state machine
|
||||||
|
- Certificate validation
|
||||||
|
- Finished / handshake verify
|
||||||
|
- AEAD шифрования (в этом модуле)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Основной use-case
|
||||||
|
|
||||||
|
Этот движок предназначен для:
|
||||||
|
|
||||||
|
- TLS fingerprint spoofing
|
||||||
|
- DPI bypass
|
||||||
|
- Proxy / tunneling протоколов
|
||||||
|
- Эмуляции браузера на уровне TLS
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Пример использования
|
||||||
|
|
||||||
|
```rust
|
||||||
|
let client_hello = ClientHello::make_client_hello(
|
||||||
|
&BrowserProfile::CHROME_131,
|
||||||
|
"example.com",
|
||||||
|
&session_keys
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ключевые идеи
|
||||||
|
|
||||||
|
1. TLS используется как транспорт маскировки
|
||||||
|
2. Fingerprint важнее криптографии
|
||||||
|
3. Поведение должно совпадать с браузером
|
||||||
|
4. Порядок и длины критичны
|
||||||
|
5. GREASE обязателен для Chromium
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Если нужно — могу:
|
||||||
|
|
||||||
|
- разобрать отличия от real Chrome packet capture
|
||||||
|
- добавить JA3 генерацию
|
||||||
|
- указать где fingerprint ещё палится (важно)
|
||||||
|
|||||||
Reference in New Issue
Block a user