docs: rewrite all documentation in Russian + add deployment guide
- docs/protocol.md, pki.md, split-tunnel.md, sing-box.md переведены на русский и сверены с текущим кодом (транспорт v2: свой UDP + TCP/443 + QUIC fallback, handover; PKI; split-tunnel; sing-box-план). - docs/deployment.md (новый, 369 строк): пошаговое руководство для удалённого сервера — сборка, PKI init/issue-server/issue-client (проверено бинарём), server.toml/client.toml на основе фактических config/*.example, firewall + NAT/IP-форвардинг, sudo-запуск, бандл клиента (ca.crt + client.crt + client.key + server addr/sni), на каком транспорте идёт трафик, ограничения v1. - README.md (новый, корень): краткий обзор + таблица крейтов + быстрый старт. Всё на русском (проза); команды/идентификаторы/конфиги — как есть. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
xah30
+63
-53
@@ -1,70 +1,80 @@
|
||||
# Integrating AuraVPN with sing-box (approach note)
|
||||
# Интеграция AuraVPN с sing-box (план)
|
||||
|
||||
Goal: let a phone client running **sing-box** connect to an Aura server speaking the **AuraVPN**
|
||||
protocol (Aura's own tunneling — not a third party's). This is a short note on *how*; the wire
|
||||
protocol it must match is fully specified in [`protocol.md`](protocol.md).
|
||||
Цель: дать клиенту на телефоне, работающему под **sing-box**, возможность подключиться к серверу
|
||||
Aura по протоколу **AuraVPN** (это собственное туннелирование Aura, не сторонний протокол). Это
|
||||
короткая заметка о том, *как* это сделать; сам wire-протокол, который должна повторять реализация,
|
||||
полностью описан в [`protocol.md`](protocol.md).
|
||||
|
||||
sing-box is written in Go and has no generic "load an arbitrary external wire protocol" plugin, so
|
||||
integration means giving sing-box a Go implementation (or a bridge) of the Aura protocol. Three
|
||||
realistic paths, cheapest first:
|
||||
sing-box написан на Go, и в нём нет универсального плагина «загрузить произвольный внешний wire-
|
||||
протокол», поэтому интеграция означает дать sing-box Go-реализацию (или мост) протокола Aura. Три
|
||||
реалистичных пути, от самого дешёвого:
|
||||
|
||||
## Option A — Process bridge (fastest, desktop/server)
|
||||
## Option A — Process bridge (быстрее всего, для десктопа/сервера)
|
||||
|
||||
Run the existing Rust `aura` client as a local process and expose a local proxy/TUN, then point
|
||||
sing-box at it:
|
||||
Запустить существующий Rust-клиент `aura` как локальный процесс и выставить локальный
|
||||
прокси/TUN, а затем направить sing-box на него:
|
||||
|
||||
- `aura client` already creates a TUN and routes through the Aura tunnel; sing-box can route selected
|
||||
traffic into that interface, **or**
|
||||
- add a local **SOCKS5 inbound** to `aura-cli` (small addition) and configure a sing-box `socks`
|
||||
outbound pointing at `127.0.0.1:<port>`.
|
||||
- `aura client` уже создаёт TUN и направляет туда трафик через туннель Aura; sing-box может
|
||||
заворачивать выбранный трафик в этот интерфейс, **или**
|
||||
- добавить в `aura-cli` локальный **SOCKS5 inbound** (небольшое дополнение) и настроить в
|
||||
sing-box `socks` outbound на `127.0.0.1:<port>`.
|
||||
|
||||
Pros: reuses the audited Rust core verbatim; no crypto re-implementation. Cons: two processes; weak
|
||||
fit for mobile (sing-box mobile apps embed the core and don't spawn helpers easily).
|
||||
Плюсы: переиспользует прошедшую аудит Rust-сердцевину дословно; нет переписывания криптографии.
|
||||
Минусы: два процесса; плохо ложится на мобильные платформы (мобильные приложения sing-box
|
||||
встраивают ядро и не умеют легко запускать вспомогательные процессы).
|
||||
|
||||
## Option B — Native Go outbound/inbound (the real target for phones)
|
||||
## Option B — Нативный Go-outbound/inbound (целевой путь для телефонов)
|
||||
|
||||
Implement the AuraVPN protocol natively in Go and register it as a sing-box **outbound** (client) and
|
||||
**inbound** (server), so the phone's embedded sing-box core speaks AuraVPN directly. This is the
|
||||
clean, performant, mobile-friendly path. Crypto maps cleanly to existing Go libraries:
|
||||
Реализовать протокол AuraVPN на Go нативно и зарегистрировать его как sing-box **outbound**
|
||||
(клиент) и **inbound** (сервер), чтобы встроенное в телефон ядро sing-box само говорило на
|
||||
AuraVPN. Это чистый, производительный и mobile-friendly путь. Криптография чисто ложится на
|
||||
существующие Go-библиотеки:
|
||||
|
||||
| Aura piece | Rust crate | Go equivalent |
|
||||
|---|---|---|
|
||||
| X25519 ECDH | `x25519-dalek` | `crypto/ecdh` (stdlib) |
|
||||
| ML-KEM-768 (FIPS 203) | `ml-kem` | `crypto/mlkem` (Go 1.24+) or `cloudflare/circl` |
|
||||
| ChaCha20-Poly1305 | `chacha20poly1305` | `golang.org/x/crypto/chacha20poly1305` |
|
||||
| HKDF-SHA256 | `hkdf` | `golang.org/x/crypto/hkdf` |
|
||||
| HMAC-SHA256 (Finished) | `hmac` | `crypto/hmac` + `crypto/sha256` |
|
||||
| ECDSA P-256 sigs (cert auth) | `ring` | `crypto/ecdsa` + `crypto/x509` |
|
||||
| X.509 verify + CRL | `rustls-webpki` | `crypto/x509` |
|
||||
| Компонент Aura | Rust-крейт | Эквивалент в Go |
|
||||
|--------------------------------|---------------------|---------------------------------------------------------|
|
||||
| X25519 ECDH | `x25519-dalek` | `crypto/ecdh` (stdlib) |
|
||||
| ML-KEM-768 (FIPS 203) | `ml-kem` | `crypto/mlkem` (Go 1.24+) или `cloudflare/circl` |
|
||||
| ChaCha20-Poly1305 | `chacha20poly1305` | `golang.org/x/crypto/chacha20poly1305` |
|
||||
| HKDF-SHA256 | `hkdf` | `golang.org/x/crypto/hkdf` |
|
||||
| HMAC-SHA256 (Finished) | `hmac` | `crypto/hmac` + `crypto/sha256` |
|
||||
| ECDSA P-256 signatures (cert) | `ring` | `crypto/ecdsa` + `crypto/x509` |
|
||||
| X.509 verify + CRL | `rustls-webpki` | `crypto/x509` |
|
||||
|
||||
What the Go code must reproduce **exactly** (see `protocol.md`):
|
||||
- 5-byte frame header `msg_type(1) || len(u24 BE) || version=0x01`.
|
||||
- Handshake order CH → SH → ServerAuth → ClientAuth → Finished(c→s) → Finished(s→c); transcript =
|
||||
`SHA-256(ClientHello_frame || ServerHello_frame)`; ECDSA-P256/SHA-256 signature over the transcript;
|
||||
HMAC-SHA256 Finished.
|
||||
- Hybrid shared secret = `x25519_ss || mlkem_ss`; HKDF salt = `client_nonce || server_nonce`,
|
||||
Что Go-код должен повторить **в точности** (см. `protocol.md`):
|
||||
|
||||
- 5-байтный заголовок кадра: `msg_type(1) || len(u24 BE) || version=0x01`.
|
||||
- Порядок рукопожатия `CH → SH → ServerAuth → ClientAuth → Finished(c→s) → Finished(s→c)`;
|
||||
транскрипт = `SHA-256(ClientHello_frame || ServerHello_frame)`; подпись ECDSA-P256/SHA-256 по
|
||||
транскрипту; Finished — HMAC-SHA256.
|
||||
- Гибридный общий секрет = `x25519_ss || mlkem_ss`; salt HKDF = `client_nonce || server_nonce`,
|
||||
info = `b"aura-v1-session"`.
|
||||
- Data record (datagram/UDP) = `seq(8 BE) || ChaCha20Poly1305(frame, aad = seq)`, nonce =
|
||||
`LE(seq) || 0x00000000`; replay window 64. (Stream/TCP record adds the 5-byte header to the AAD.)
|
||||
- Transport selection: UDP (type `0x01` HS / `0x02` DATA) primary; TCP/443 and QUIC fallbacks.
|
||||
- Запись данных (datagram/UDP) = `seq(8 BE) || ChaCha20Poly1305(frame, aad = seq)`, nonce =
|
||||
`LE(seq) || 0x00000000`; окно anti-replay — 64. (Stream/TCP-запись дополнительно включает
|
||||
5-байтный заголовок в AAD.)
|
||||
- Выбор транспорта: UDP (тип-байт `0x01` HS / `0x02` DATA) как основной; TCP/443 и QUIC как
|
||||
fallback.
|
||||
|
||||
To de-risk the Go port, export **known-answer test vectors** from the Rust side (a captured
|
||||
handshake transcript + derived keys + a sealed data record) and assert the Go implementation
|
||||
reproduces them byte-for-byte. The ML-KEM KAT already lives in `aura-crypto/tests/kat_kyber.rs`.
|
||||
Чтобы снизить риск порта в Go, экспортируйте со стороны Rust **known-answer test vectors**
|
||||
(захваченный транскрипт рукопожатия + производные ключи + запечатанная запись данных) и
|
||||
утверждайте, что Go-реализация воспроизводит их побайтово. KAT для ML-KEM уже лежит в
|
||||
`aura-crypto/tests/kat_kyber.rs`.
|
||||
|
||||
## Option C — Rust core via cgo (`cdylib`)
|
||||
## Option C — Rust core через cgo (`cdylib`)
|
||||
|
||||
Compile the Aura Rust core to a C-ABI shared library and call it from a thin sing-box Go shim via
|
||||
cgo. Reuses the audited crypto/handshake with no Go re-implementation, but cgo + per-platform
|
||||
(Android/iOS) packaging is fiddly and complicates sing-box's pure-Go build.
|
||||
Скомпилировать Rust-сердцевину Aura в C-ABI shared library и вызывать её из тонкого Go-shim'а
|
||||
sing-box через cgo. Переиспользует прошедшую аудит крипто/рукопожатие без Go-переписывания, но
|
||||
cgo плюс упаковка под каждую платформу (Android/iOS) — занудно и усложняет чисто-Go-сборку
|
||||
sing-box.
|
||||
|
||||
## Recommendation
|
||||
## Рекомендация
|
||||
|
||||
- **Now:** Option A (process bridge) for desktop/server validation — minimal work, real protocol.
|
||||
- **For the phone:** Option B (native Go outbound), built against `protocol.md` + exported Rust test
|
||||
vectors. It is the only option that fits sing-box's embedded mobile core well.
|
||||
- Keep `protocol.md` the single source of truth and version the wire protocol (the header already
|
||||
carries `version = 0x01`) so the Rust and Go implementations stay in lockstep.
|
||||
- **Сейчас:** Option A (process bridge) для валидации на десктопе/сервере — минимум работы,
|
||||
настоящий протокол.
|
||||
- **Для телефона:** Option B (нативный Go-outbound), написанный по `protocol.md` + по
|
||||
экспортированным из Rust тест-векторам. Это единственный вариант, который хорошо ложится на
|
||||
встроенное мобильное ядро sing-box.
|
||||
- Держите `protocol.md` единственным источником истины и версионируйте wire-протокол (заголовок
|
||||
уже несёт `version = 0x01`), чтобы Rust- и Go-реализации шли в ногу.
|
||||
|
||||
> Status: this is a design note. No Go code or sing-box module is implemented yet — that is a
|
||||
> separate deliverable tracked for after the Rust transport stabilizes.
|
||||
> Статус: это проектная заметка. Go-кода и sing-box-модуля пока **нет** — это отдельный
|
||||
> deliverable, поставленный в план после стабилизации Rust-транспорта.
|
||||
|
||||
Reference in New Issue
Block a user