mirror of
https://github.com/Govor-team/Govor.git
synced 2026-11-16 20:56:03 +00:00
Add E2EE messaging and VPS deployment
Add signed, encrypted messages and attachments with per-session device keys, conversation key discovery, and server-side validation. Extend CI to publish immutable container images and deploy to a VPS, with setup and protocol documentation.
This commit is contained in:
+133
@@ -0,0 +1,133 @@
|
||||
# E2EE v1
|
||||
|
||||
Новые личные сообщения и сообщения приватных групп/каналов требуют E2EE.
|
||||
Сервер проверяет подпись и права доступа, сохраняет и пересылает зашифрованный
|
||||
конверт. Он не получает приватные ключи устройств или ключи файлов.
|
||||
Новый мобильный клиент шифрует сообщения всех чатов, включая публичные группы;
|
||||
сервер сохраняет совместимость с открытыми сообщениями публичных групп.
|
||||
|
||||
## Протокол
|
||||
|
||||
Используется `jose-jwt` 5.3.0: JWE JSON Serialization (RFC 7516),
|
||||
RSA-OAEP-256 с RSA 3072 для передачи ключа каждому устройству, AES-256-GCM для
|
||||
содержимого и JWS ES256 (RFC 7515) для подписи полного конверта.
|
||||
Алгоритмы фиксированы; сжатие, незашифрованный режим и выбор алгоритма сервером
|
||||
не поддерживаются. Это прикладной протокол на JOSE, а не Signal/MLS.
|
||||
|
||||
Поле `EncryptedContent` содержит `govor.e2ee.v1:` и компактный JWS. В подписанном
|
||||
конверте находятся версия, ID сообщения и чата, тип чата, публичный ключ автора,
|
||||
ID сессии, ссылка на ответ, время, признак редактирования, отпечатки устройств,
|
||||
ID вложений и JWE. Текст и секреты вложений находятся только внутри JWE.
|
||||
Публичный ключ RSA подписан ключом ES256 с отдельным контекстом
|
||||
`govor-key-binding-v1`. Отпечаток SHA-256 связывает оба публичных ключа.
|
||||
|
||||
Код `Govor.Application/E2ee/E2eeProtocol.cs` и его копия в мобильном репозитории
|
||||
`Govor.Mobile/Services/E2ee/E2eeProtocol.cs` должны оставаться идентичными.
|
||||
Изменение формата требует новой версии протокола и совместимых клиентов.
|
||||
|
||||
## Устройства и доверие
|
||||
|
||||
Клиент генерирует отдельную пару ключей шифрования/подписи для каждой сессии.
|
||||
Приватные ключи хранятся только в MAUI SecureStorage, раздельно для сервера,
|
||||
аккаунта и сессии. Ключи предыдущих сессий остаются локально для чтения истории.
|
||||
Ошибка записи или регистрации останавливает отправку; отката к открытому тексту нет.
|
||||
|
||||
Каждый новый отпечаток нужно сверить лично или по независимому доверенному
|
||||
каналу. Приложение показывает свой отпечаток и отпечаток другого устройства.
|
||||
Простое нажатие подтверждения без сверки не защищает от подстановки устройства
|
||||
скомпрометированным сервером. Дополнительно подтверждается состав получателей
|
||||
каждого чата при первом использовании и изменении списка устройств/участников.
|
||||
Эти подтверждения хранятся локально, а не на сервере.
|
||||
|
||||
Это не система прозрачности ключей и не подписанный участниками протокол
|
||||
управления составом групп. Сервер остаётся источником списка участников и
|
||||
статуса сессий. Если он скрывает изменения/отзыв устройств, это невозможно
|
||||
независимо обнаружить без дополнительного протокола. Не следует заявлять
|
||||
защиту уровня Signal/MLS или защиту от любых действий злонамеренного сервера.
|
||||
До публичного релиза требуется независимый аудит протокола и интеграции.
|
||||
|
||||
## Серверные API
|
||||
|
||||
- `PUT /api/e2ee/device`: публичный `DeviceKey` текущего пользователя/сессии.
|
||||
Повторная регистрация тех же ключей допустима; смена ключей внутри сессии
|
||||
запрещена. Истёкшая или отозванная сессия не может регистрировать ключи.
|
||||
- `GET /api/e2ee/conversations/{type}/{conversationId}/keys`: список участников
|
||||
и зарегистрированных устройств; `type=0` — личный чат, `type=1` — группа.
|
||||
Требуется доступ к чату. Возвращаются только публичные данные.
|
||||
- SignalR `Send`/`Edit` и HTTP загрузки истории сохраняют существующие поля DTO.
|
||||
`MessageEditResponse` дополнительно возвращает `ReplyToMessageId` для проверки
|
||||
подписанного контекста редактирования.
|
||||
|
||||
Для офлайн-доставки устройства с истёкшей, но не отозванной сессией остаются
|
||||
получателями. Отозванные сессии исключаются. При изменении набора устройств
|
||||
необходимо заново получить ключи, подтвердить состав и перешифровать сообщение.
|
||||
В группах это проверяется под существующей блокировкой модерации, чтобы бан
|
||||
не мог гоняться с сохранением сообщения. Каждый отправляемый конверт получает
|
||||
новый случайный ключ содержимого. Исключённый участник сохраняет доступ к уже
|
||||
полученным сообщениям, но его ключ больше не включается в новые конверты.
|
||||
|
||||
ID сообщения генерируется клиентом и подписывается. Повторная отправка того же
|
||||
конверта не создаёт второй записи/задания push. Редактирование проверяет ID,
|
||||
автора, чат, ответ, вложения и время версии. Клиент хранит принятые версии,
|
||||
отклоняет откат к старой версии и проверяет подпись перед показом текста.
|
||||
|
||||
## Вложения
|
||||
|
||||
Клиент шифрует файл AES-256-GCM с новым случайным 32-байтовым ключом и 12-байтовым
|
||||
nonce. Формат: `nonce || ciphertext || tag(16)`; AAD — `govor-attachment-v1`.
|
||||
Сервер получает случайное имя `.bin`, тип `application/vnd.govor.encrypted` и
|
||||
байты шифротекста. Исходное имя, MIME-тип и ключ передаются только внутри
|
||||
зашифрованного сообщения. Поле `EncryptedKey` загрузки должно быть пустым.
|
||||
Незашифрованные загрузки типа Message отклоняются; аватары остаются открытыми.
|
||||
|
||||
Получатель сначала проверяет и расшифровывает сообщение, сохраняет секреты
|
||||
вложений локально, затем загружает и проверяет файл. Предельный размер исходного
|
||||
файла — 19 MB, текста — 20 000 символов, устройств — 500, конверта — 1 000 000
|
||||
символов. Ограничения предотвращают неограниченный рост RSA-конверта.
|
||||
|
||||
## Обновление и ограничения
|
||||
|
||||
1. Собрать и согласованно обновить сервер и клиенты всех участников. Старые
|
||||
клиенты не смогут отправлять сообщения в защищаемые чаты. Автоматического
|
||||
временного перехода на открытый текст нет.
|
||||
2. Пользователям нужно войти в новый клиент для регистрации устройств. Пока
|
||||
хотя бы у одного участника нет ключа, новый клиент блокирует отправку.
|
||||
3. Сверить отпечатки и состав получателей. Проверить личный чат, приватную
|
||||
группу/канал, редактирование, вложения, новое устройство и исключение участника
|
||||
на реальных устройствах перед развёртыванием.
|
||||
|
||||
Новая миграция БД не требуется: используются существующие таблицы CryptoSession
|
||||
и SignedPreKey, в которых хранятся только публичные данные. Старые заготовки
|
||||
Signal prekeys не превращаются автоматически в совместимые ключи JOSE; если
|
||||
они уже были привязаны к сессии, нужна новая сессия.
|
||||
|
||||
Уже сохранённая открытая история и старые файлы не становятся секретными задним
|
||||
числом. Они не удаляются; клиент помечает открытую историю `[Без E2EE]`.
|
||||
При невозможности расшифровки показывается статус без шифротекста и вложений;
|
||||
неуспешный результат не сохраняется вместо исходной записи локального кэша.
|
||||
|
||||
Новый физический аппарат не получает прошлые ключи автоматически. После удаления
|
||||
SecureStorage или потери устройства зашифрованная история без другого устройства
|
||||
с нужными ключами недоступна. Серверного восстановления/экспорта ключей нет.
|
||||
Локальный кэш сообщений пока хранит уже расшифрованный текст, как и раньше.
|
||||
|
||||
В v1 нет forward secrecy/post-compromise security и Double Ratchet/MLS:
|
||||
компрометация приватного ключа устройства позволяет расшифровать сохранённые
|
||||
сообщения, адресованные этому ключу. Отзыв сессии исключает её из будущих
|
||||
получателей; украденные ключи и уже прочитанные сообщения отозвать невозможно.
|
||||
Метаданные, участники, размеры и время сообщений видны серверу. Скомпрометированное
|
||||
устройство участника и копирование текста самим участником за пределами модели
|
||||
защиты. HTTPS по-прежнему требуется для авторизации и защиты транспорта.
|
||||
|
||||
## Проверка
|
||||
|
||||
```powershell
|
||||
dotnet test Govor.Server.Tests/Govor.Server.Tests.csproj
|
||||
# В мобильном репозитории:
|
||||
dotnet test Govor.Mobile.Tests/Govor.Mobile.Tests.csproj
|
||||
dotnet build Govor.Mobile/Govor.Mobile.csproj -f net10.0-android -p:TargetFrameworks=net10.0-android
|
||||
```
|
||||
|
||||
Тесты проверяют совместимость шифрования/расшифровки, подписи и контекст,
|
||||
доступ посторонних, отзыв устройств, смену состава группы, версии сообщений,
|
||||
секреты вложений, отказ сверки ключей и отказ записи приватного ключа.
|
||||
@@ -0,0 +1,172 @@
|
||||
# Деплой на VPS Timeweb через GitHub Actions
|
||||
|
||||
После включения: push в `master` → существующие тесты SQLite/PostgreSQL → сборка
|
||||
Dockerfile → публикация в GitHub Container Registry (GHCR) → SSH → миграции →
|
||||
обновление контейнеров → проверка `/server/ready`. PR выполняет только тесты.
|
||||
Доступен и ручной запуск workflow `.NET` для `master`.
|
||||
|
||||
Базовая конфигурация рассчитана на один VPS Linux x86_64 и внешнюю PostgreSQL.
|
||||
Обновление допускает короткий перерыв. База не переносится автоматически.
|
||||
|
||||
## Постоянные данные
|
||||
|
||||
```text
|
||||
/opt/govor/
|
||||
shared/runtime.env # секреты API, создаются вручную
|
||||
shared/deploy.env # домен
|
||||
data/logs/ # /app/logs в контейнере
|
||||
data/uploads/ # /app/uploads в контейнере
|
||||
releases/<commit-run>/ # Compose, Caddyfile, deploy.sh, image.env
|
||||
current -> releases/... # последний успешный релиз
|
||||
```
|
||||
|
||||
`logs` и `uploads` подключены через bind mounts с фиксированными абсолютными путями.
|
||||
GitHub Actions копирует только конфигурацию нового релиза и заменяет контейнеры.
|
||||
Данные находятся вне репозитория и каталога релиза. Скрипт не выполняет очистку,
|
||||
`git clean`, `rsync --delete`, `docker compose down -v` или удаление Docker volumes.
|
||||
Если папок данных нет, деплой завершится ошибкой вместо создания пустого хранилища.
|
||||
Приложение по-прежнему может удалять файлы по пользовательским запросам.
|
||||
|
||||
Сертификаты Caddy хранятся в именованных Docker volumes проекта `govor`.
|
||||
Ротация Docker stdout ограничена; файловые логи API сохраняются и требуют контроля
|
||||
свободного места. Настройте отдельные резервные копии БД и `/opt/govor/data` вне VPS:
|
||||
постоянный диск сам по себе не является резервной копией.
|
||||
|
||||
## 1. Подготовить сервер один раз
|
||||
|
||||
Установите Docker Engine и Compose plugin по официальной инструкции Docker для
|
||||
выбранной ОС. Нужны Bash, `flock` (util-linux) и OpenSSH. Compose должен поддерживать
|
||||
несколько `--env-file` и `up --wait` (например, актуальный Compose v2).
|
||||
|
||||
Создайте пользователя `deploy` с SSH-доступом по отдельному ключу и доступом к
|
||||
Docker. Членство в группе `docker` фактически даёт административные права на VPS.
|
||||
На сервере, от администратора:
|
||||
|
||||
```bash
|
||||
sudo usermod -aG docker deploy
|
||||
sudo install -d -o deploy -g deploy -m 750 /opt/govor
|
||||
sudo install -d -o deploy -g deploy -m 700 /opt/govor/shared
|
||||
sudo install -d -o deploy -g deploy -m 750 /opt/govor/releases /opt/govor/data
|
||||
sudo install -d -o deploy -g deploy -m 750 /opt/govor/data/logs /opt/govor/data/uploads
|
||||
```
|
||||
|
||||
Переподключитесь по SSH после изменения групп. Добавьте публичный ключ Actions в
|
||||
`~deploy/.ssh/authorized_keys`. Приватный ключ останется в GitHub Secrets.
|
||||
|
||||
Создайте `/opt/govor/shared/runtime.env` по корневому `.env.example` с реальными
|
||||
значениями текущего приложения. Сохраните существующие JWT/refresh-секреты при
|
||||
переносе, если не требуется отзывать сессии. Формат — Docker env file; значения
|
||||
со знаком `$` заключайте в одинарные кавычки, чтобы Compose не интерполировал их.
|
||||
|
||||
Создайте `/opt/govor/shared/deploy.env` по `deploy/deploy.env.example`:
|
||||
|
||||
```dotenv
|
||||
GOVOR_DOMAIN=api.example.com
|
||||
```
|
||||
|
||||
```bash
|
||||
chmod 600 /opt/govor/shared/runtime.env /opt/govor/shared/deploy.env
|
||||
docker compose version
|
||||
docker info >/dev/null
|
||||
```
|
||||
|
||||
Настройте DNS домена на IP VPS, входящие TCP 80/443 на Caddy и SSH для деплоя.
|
||||
API 8080 и PostgreSQL не публикуются этим Compose в интернет. Разрешите новому VPS
|
||||
подключение к внешней БД. Сертификат PostgreSQL из `Govor.API/certs` уже включён
|
||||
в Dockerfile через publish проекта.
|
||||
|
||||
Для приватного GHCR-образа войдите в реестр **под пользователем deploy** один раз:
|
||||
|
||||
```bash
|
||||
read -rsp 'GHCR token (read:packages): ' ghcr_token; echo
|
||||
printf '%s' "$ghcr_token" | docker login ghcr.io -u YOUR_GITHUB_LOGIN --password-stdin
|
||||
unset ghcr_token
|
||||
```
|
||||
|
||||
Используйте токен с доступом к пакету и `read:packages` (при необходимости разрешите
|
||||
SSO организации). Токен сервера нужен для скачивания приватного образа; Actions
|
||||
публикует образ своим временным `GITHUB_TOKEN`. Публичный пакет не требует входа
|
||||
на VPS. Не помещайте токен в runtime.env или Git.
|
||||
|
||||
## 2. Перенести существующие файлы
|
||||
|
||||
До переключения клиентов сохраните копию БД и существующих `uploads`/`logs`.
|
||||
Остановите запись в старый API на время финального копирования, чтобы файлы и БД
|
||||
оставались согласованными. Скопируйте **содержимое** прежней папки uploads в
|
||||
`/opt/govor/data/uploads`, сохраняя все вложенные пути, и аналогично logs в
|
||||
`/opt/govor/data/logs`. Не создавайте лишний уровень `uploads/uploads`.
|
||||
Если БД остаётся прежней, её повторный импорт не нужен.
|
||||
|
||||
Сначала проверьте новую установку, затем переключите домен и отключите старый API.
|
||||
Если адрес API меняется, обновите настройки мобильного клиента. Для проверки до
|
||||
смены DNS можно использовать `curl --resolve` с новым IP после настройки TLS.
|
||||
|
||||
## 3. Настроить GitHub
|
||||
|
||||
В Settings → Environments создайте `production`. Ограничьте deployment branches
|
||||
веткой `master`. Для автоматического деплоя без ручного подтверждения не включайте
|
||||
required reviewers. Добавьте environment secrets:
|
||||
|
||||
| Secret | Значение |
|
||||
| --- | --- |
|
||||
| `VPS_HOST` | IP или домен SSH сервера |
|
||||
| `VPS_USER` | `deploy` |
|
||||
| `VPS_SSH_KEY` | Полный приватный SSH-ключ без passphrase, включая BEGIN/END |
|
||||
| `VPS_KNOWN_HOSTS` | Проверенная запись host key сервера в формате known_hosts |
|
||||
|
||||
Получить запись можно через `ssh-keyscan -p 22 SERVER`, но перед сохранением
|
||||
обязательно сверить fingerprint с ключом через консоль Timeweb:
|
||||
`ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub`.
|
||||
Для нестандартного порта known_hosts использует `[host]:port`.
|
||||
|
||||
В Repository → Settings → Secrets and variables → Actions → Variables:
|
||||
|
||||
| Variable | Значение |
|
||||
| --- | --- |
|
||||
| `VPS_DEPLOY_ENABLED` | `true`, только после подготовки сервера и переноса данных |
|
||||
| `VPS_SSH_PORT` | Необязательно; по умолчанию `22` |
|
||||
|
||||
Workflow публикует `ghcr.io/<owner>/<repo>:<commit>`; запускается точный digest
|
||||
`@sha256:...`. Actions получает `packages: write` только в задаче публикации.
|
||||
Если пакет уже существует, предоставьте репозиторию Actions-доступ к нему в
|
||||
настройках пакета. Пока `VPS_DEPLOY_ENABLED` не включён, работают только тесты.
|
||||
|
||||
## 4. Обновления и диагностика
|
||||
|
||||
Сделайте push в `master` или запустите `.NET` → Run workflow → `master`.
|
||||
Не удаляйте резервную копию БД перед потенциально разрушающими миграциями.
|
||||
Скрипт сначала скачивает образ, затем запускает `--migrate-only`. При ошибке
|
||||
миграции контейнер текущего API не заменяется; сама миграция уже могла изменить БД.
|
||||
При ошибке запуска job падает; автоматического отката схемы или контейнера нет.
|
||||
Ссылка `current` обновляется только после успешной проверки готовности.
|
||||
Деплои сериализуются GitHub concurrency и серверной блокировкой `flock`.
|
||||
|
||||
Посмотреть контейнеры и логи на VPS:
|
||||
|
||||
```bash
|
||||
docker compose --project-name govor \
|
||||
--env-file /opt/govor/shared/deploy.env \
|
||||
--env-file /opt/govor/current/image.env \
|
||||
-f /opt/govor/current/compose.yaml ps
|
||||
docker compose --project-name govor \
|
||||
--env-file /opt/govor/shared/deploy.env \
|
||||
--env-file /opt/govor/current/image.env \
|
||||
-f /opt/govor/current/compose.yaml logs --tail=100 api proxy
|
||||
```
|
||||
|
||||
При первом неудачном деплое вместо `current` используйте путь релиза из Actions.
|
||||
Проверьте HTTPS `/server/ready`, вход, старые вложения, отправку нового файла и
|
||||
SignalR. Чтобы проверить сохранность, запишите контрольные суммы нескольких
|
||||
существующих файлов в uploads, выполните повторный деплой и сравните их.
|
||||
|
||||
Для возврата к прежнему образу выберите совместимый со схемой БД успешный релиз
|
||||
из `releases`, возьмите digest из его `image.env` и выполните
|
||||
`bash /opt/govor/releases/<release>/deploy.sh ghcr.io/<owner>/<repo>@sha256:<digest>`.
|
||||
Старый код не отменяет миграции; несовместимая схема требует отдельного плана
|
||||
восстановления БД. Старые образы и каталоги релизов автоматически не очищаются.
|
||||
|
||||
Официальные инструкции:
|
||||
- https://docs.docker.com/engine/install/ubuntu/
|
||||
- https://docs.docker.com/engine/storage/bind-mounts/
|
||||
- https://docs.github.com/en/actions/tutorials/publish-packages/publish-docker-images
|
||||
- https://caddyserver.com/docs/quick-starts/reverse-proxy
|
||||
Reference in New Issue
Block a user