readme: explain the MITM CA step (local CA, private key stays local, how to revoke)

Users reasonably get nervous when an installer adds a root CA. Spell
out what the install actually does and does not do, in both the English
and Persian sections:

- CA keypair is generated locally in the user-data dir
- Only the public cert is added to the trust store
- Private key never leaves the machine; no network side is involved
- Clear revocation steps
- Manual CLI fallback if the launcher isn't wanted
- Firefox NSS note in case certutil best-effort misses
This commit is contained in:
therealaleph
2026-04-21 22:27:49 +03:00
parent 2dfaef2048
commit 4d1600a349
+49 -5
View File
@@ -96,9 +96,18 @@ cargo build --release --features ui
# Binaries: target/release/mhrv-rs and target/release/mhrv-rs-ui
```
### Step 3 — First run
### Step 3 — First run: install the MITM CA
The launcher handles the one-time CA install, then starts the UI:
To route your browser's HTTPS traffic through the Apps Script relay, `mhrv-rs` has to terminate TLS locally on your machine, forward the request through the relay, and re-encrypt the response with a certificate your browser trusts. That requires a small **local** Certificate Authority.
**What actually happens on first run:**
- A fresh CA keypair (`ca/ca.crt` + `ca/ca.key`) is generated **on your machine**, in your user-data dir.
- The public `ca.crt` is added to your system trust store so browsers accept the per-site certificates `mhrv-rs` mints on the fly. This is the step that needs sudo / Administrator.
- The private `ca.key` **never leaves your machine**. Nothing uploads it, nothing phones home, and no remote party — including the Apps Script relay — can use it to impersonate sites to you.
- You can revoke it at any time by deleting the CA from your OS keychain (macOS: Keychain Access → System → delete `mhrv-rs`) / Windows cert store / `/etc/ca-certificates`, and removing the `ca/` folder.
The launcher does all of this for you and then starts the UI:
| platform | how |
|---|---|
@@ -106,7 +115,19 @@ The launcher handles the one-time CA install, then starts the UI:
| Linux | `./run.sh` from a terminal |
| Windows | double-click `run.bat` |
It will ask for your password (sudo / UAC) to add the MITM root to the system trust store. After that the CA is trusted and you can launch the UI directly next time.
It will ask for your password (sudo / UAC) **only** to trust the CA. After that the launcher also starts `mhrv-rs-ui`. On later runs you don't need the launcher — the CA is already trusted, so you can open `mhrv-rs.app` / `mhrv-rs-ui.exe` / `mhrv-rs-ui` directly.
If you prefer to do the CA step by hand:
```bash
# Linux / macOS
sudo ./mhrv-rs --install-cert
# Windows (Administrator)
mhrv-rs.exe --install-cert
```
Firefox keeps its own cert store; the installer also drops the CA into Firefox's NSS database via `certutil` (best-effort). If Firefox still complains, import `ca/ca.crt` manually via Settings → Privacy & Security → Certificates → View Certificates → Authorities → Import.
### Step 4 — Configure in the UI
@@ -291,13 +312,36 @@ Config و ریشهٔ MITM در پوشهٔ کاربر سیستم‌عامل قر
آرشیو پلتفرم خود را از [صفحهٔ releases](https://github.com/therealaleph/MasterHttpRelayVPN-RUST/releases) بگیرید و extract کنید.
#### ۳. اجرای بار اول
#### ۳. اجرای بار اول: نصب گواهی MITM
برای اینکه ترافیک HTTPS مرورگر از طریق Apps Script رد شود، `mhrv-rs` باید TLS را **روی سیستم خودتان** باز کند، درخواست را از رله بفرستد، و پاسخ را با یک گواهی که مرورگر شما trust می‌کند دوباره رمزگذاری کند. این کار یک **Certificate Authority محلی** کوچک نیاز دارد.
**چه اتفاقی در اجرای بار اول می‌افتد:**
- یک keypair تازهٔ CA (`ca/ca.crt` + `ca/ca.key`) **روی سیستم شما** در پوشهٔ user-data ساخته می‌شود.
- فایل عمومی `ca.crt` به trust store سیستم اضافه می‌شود تا مرورگر گواهی‌های per-site که `mhrv-rs` on-the-fly می‌سازد را بپذیرد. همین مرحله است که sudo / Administrator می‌خواهد.
- کلید خصوصی `ca.key` **هرگز از سیستم شما خارج نمی‌شود**. جایی آپلود نمی‌شود، با هیچ سرور راه دوری تماس گرفته نمی‌شود، و هیچ طرف دیگری — از جمله رلهٔ Apps Script — نمی‌تواند با آن خودش را جای سایت‌ها جا بزند.
- هر وقت خواستید می‌توانید حذفش کنید: keychain مک (Keychain Access → System → `mhrv-rs` را حذف کنید) / cert store ویندوز / `/etc/ca-certificates` در لینوکس، به‌علاوهٔ پاک کردن پوشهٔ `ca/`.
اسکریپت راه‌انداز همهٔ این کارها را برایتان انجام می‌دهد و بعد UI را باز می‌کند:
- **مک**: روی `run.command` دو بار کلیک کنید (یا از ترمینال `./run.command`).
- **لینوکس**: در ترمینال `./run.sh`.
- **ویندوز**: روی `run.bat` دو بار کلیک کنید.
اسکریپت رمز شما را می‌خواهد (sudo یا UAC) تا CA داخل trust store سیستم نصب شود. بعد از این کار UI باز می‌شود و در اجراهای بعدی می‌توانید مستقیماً خود UI یا `mhrv-rs.app` را اجرا کنید.
اسکریپت **فقط** برای trust کردن CA رمز شما را می‌خواهد (sudo یا UAC). بعد از آن UI هم باز می‌شود، و در اجراهای بعدی دیگر لازم نیست از launcher استفاده کنید مستقیماً `mhrv-rs.app` یا `mhrv-rs-ui.exe` یا `mhrv-rs-ui` را اجرا کنید.
اگر ترجیح می‌دهید مرحلهٔ CA را دستی انجام دهید:
```bash
# لینوکس/مک
sudo ./mhrv-rs --install-cert
# ویندوز (به‌عنوان Administrator)
mhrv-rs.exe --install-cert
```
Firefox cert store خودش را جدا دارد؛ installer تلاش می‌کند از طریق `certutil` گواهی را داخل NSS فایرفاکس هم بیندازد (best-effort). اگر فایرفاکس هنوز شکایت کرد، خودتان دستی `ca/ca.crt` را از Settings → Privacy & Security → Certificates → View Certificates → Authorities → Import اضافه کنید.
#### ۴. تنظیمات در UI