SHA256
359 lines
15 KiB
Markdown
359 lines
15 KiB
Markdown
# Формат DM v1
|
||
|
||
## Статус документа
|
||
|
||
Этот файл фиксирует байтовый формат DM-контейнеров SHiNE v1.
|
||
|
||
Важно:
|
||
|
||
- это актуальный формат, реализованный в текущем коде;
|
||
- контейнер `SHiNE_DM` используется для всех типов `1..8`;
|
||
- при любых будущих изменениях DM этот документ обновляется одновременно с кодом.
|
||
|
||
Логика протокола, API и поведение сервера описаны отдельно:
|
||
|
||
- `docs/Personal_Messages/Протокол_DM_v1.md`
|
||
- `docs/Personal_Messages/Доставка_и_синхронизация_DM.md`
|
||
|
||
`deliveryState`, retry-времена и sync-флаг не входят в `SHiNE_DM` и не подписываются пользователем. Это изменяемые серверные метаданные, хранящиеся отдельно от raw-контейнера. Для корреляции доставки используется уже существующий `messageKey`; добавление delivery-воркера не меняет ни одного байта формата ниже.
|
||
|
||
## 1. Общие правила
|
||
|
||
- Числа кодируются в `big-endian`.
|
||
- `toLogin` и `fromLogin` — ASCII строки длиной `1..60`.
|
||
- Подпись — `Ed25519`, 64 байта.
|
||
- `nonce` — `u32`.
|
||
- `messageType` — `u8`.
|
||
- `timeMs`, `revisionTimeMs`, `reencryptedAtMs` — `u64`.
|
||
|
||
## 2. Типы сообщений
|
||
|
||
- `1` — входящее сообщение
|
||
- `2` — исходящая копия сообщения
|
||
- `3` — входящее подтверждение прочтения
|
||
- `4` — исходящая копия подтверждения прочтения
|
||
- `5` — сообщение удалено отправителем
|
||
- `6` — сообщение удалено получателем
|
||
- `7` — переписка удалена отправителем
|
||
- `8` — переписка удалена получателем
|
||
|
||
## 3. Контейнер `SHiNE_DM`
|
||
|
||
```text
|
||
SHiNE_DM
|
||
- prefix = "SHiNE_DM"
|
||
- formatVersionMajor: u8
|
||
- formatVersionMinor: u8
|
||
- toLoginLen: u8
|
||
- toLogin
|
||
- fromLoginLen: u8
|
||
- fromLogin
|
||
- timeMs: u64
|
||
- nonce: u32
|
||
- messageType: u8
|
||
- revisionTimeMs: u64
|
||
- reencryptedAtMs: u64
|
||
- bodyLen: u32
|
||
- body
|
||
- signature: [64]
|
||
```
|
||
|
||
## 4. Смысл полей `SHiNE_DM`
|
||
|
||
### `timeMs`
|
||
|
||
Это время исходного создания сообщения.
|
||
|
||
Для типов `7/8` это время самого служебного сообщения удаления переписки и одновременно граница, раньше которой сообщения этой пары считаются недействительными.
|
||
|
||
### `nonce`
|
||
|
||
Дополнительное поле уникальности сообщения.
|
||
|
||
Используется вместе с `timeMs` для построения стабильного логического ID.
|
||
|
||
### `messageType`
|
||
|
||
Определяет смысл контейнера:
|
||
|
||
- обычное сообщение;
|
||
- исходящая копия;
|
||
- read-receipt;
|
||
- удаление одного сообщения;
|
||
- удаление всей переписки.
|
||
|
||
### `revisionTimeMs`
|
||
|
||
- `0` для исходной версии контентного сообщения;
|
||
- ненулевое значение для новой текстовой ревизии сообщения;
|
||
- для типов `5/6` это время tombstone удаления одного сообщения;
|
||
- для типов `7/8` всегда `0`.
|
||
|
||
То есть `revisionTimeMs` отвечает именно за изменение смыслового содержимого сообщения, а не за сам факт перешифровки.
|
||
|
||
### `reencryptedAtMs`
|
||
|
||
- `0`, если перешифровки не было;
|
||
- ненулевое значение, если копия сообщения была перешифрована.
|
||
|
||
Для типов `5/6/7/8` должно быть `0`.
|
||
|
||
`reencryptedAtMs` не требует, чтобы `revisionTimeMs` был ненулевым. Допустим сценарий:
|
||
|
||
- `revisionTimeMs = 0`
|
||
- `reencryptedAtMs > 0`
|
||
|
||
если исходное сообщение не редактировалось, но было перешифровано позже.
|
||
|
||
### `bodyLen`
|
||
|
||
- `> 0` для типов `1/2/3/4`;
|
||
- `0` для типов `5/6/7/8`;
|
||
- для всех типов используется один и тот же контейнер `SHiNE_DM`.
|
||
|
||
## 5. Поле `body` для типов `1/2`
|
||
|
||
Для обычного контентного DM поле `body` содержит не голый ciphertext, а контейнер шифрования:
|
||
|
||
```text
|
||
EncryptedBody_v1_0
|
||
- cryptoMethod: u8
|
||
- cryptoVersion: u8
|
||
- ephemeralPubKeyLen: u8
|
||
- ephemeralPubKey: bytes[ephemeralPubKeyLen]
|
||
- ivLen: u8
|
||
- iv: bytes[ivLen]
|
||
- cipherTextLen: u32
|
||
- cipherText: bytes[cipherTextLen]
|
||
```
|
||
|
||
### Смысл полей `EncryptedBody_v1_0`
|
||
|
||
#### `cryptoMethod`
|
||
|
||
Идентификатор метода шифрования.
|
||
|
||
В версии v1 резервируется:
|
||
|
||
- `1` — `X25519 + HKDF-SHA256 + AES-256-GCM`
|
||
|
||
#### `cryptoVersion`
|
||
|
||
Версия конкретного метода шифрования.
|
||
|
||
Для текущей версии:
|
||
|
||
- `0`
|
||
|
||
#### `ephemeralPubKey`
|
||
|
||
Публичный ephemeral `X25519` ключ отправителя конкретной ревизии.
|
||
|
||
Практически ожидается длина:
|
||
|
||
- `32`
|
||
|
||
#### `iv`
|
||
|
||
Nonce/IV для `AES-GCM`.
|
||
|
||
Практически ожидается длина:
|
||
|
||
- `12`
|
||
|
||
#### `cipherText`
|
||
|
||
Зашифрованное содержимое сообщения.
|
||
|
||
Сервер не должен трактовать это поле как UTF-8 текст и не должен пытаться расшифровывать его в обычной DM-логике.
|
||
|
||
Важно:
|
||
|
||
- официальный UI SHiNE сейчас использует именно `EncryptedBody_v1_0`;
|
||
- сервер для контентных DM `type=1/2` не должен требовать, чтобы `body` обязательно был распознан как `EncryptedBody_v1_0`;
|
||
- сервер должен хранить и пересылать `body` как opaque bytes, если внешний контейнер `SHiNE_DM` валиден.
|
||
|
||
### Точная схема для `cryptoMethod = 1`, `cryptoVersion = 0`
|
||
|
||
- публичный ключ получателя для E2EE получается как стандартное преобразование `Ed25519 -> X25519`;
|
||
- отправитель генерирует ephemeral `X25519` приватный ключ и кладёт соответствующий `ephemeralPubKey` в контейнер;
|
||
- общий секрет вычисляется как `X25519(ephemeralPrivKey, recipientX25519PubKey)`;
|
||
- `HKDF-SHA256` использует:
|
||
- `salt = ephemeralPubKey || recipientX25519PubKey`
|
||
- `info = "SHiNE_DM|1|0|X25519+HKDF-SHA256+AES-256-GCM"` в ASCII
|
||
- `outputLen = 32`
|
||
- полученные `32` байта используются как ключ `AES-256-GCM`;
|
||
- поле `cipherText` хранит стандартный результат библиотеки `AES-GCM` в виде:
|
||
- `ciphertext || tag`
|
||
|
||
## 6. Поле `body` для типов `3/4`
|
||
|
||
Для read-receipt типов `3/4` поле `body` содержит открытый контейнер ссылки на исходное сообщение:
|
||
|
||
```text
|
||
ReadReceiptBody_v1_0
|
||
- refToLoginLen: u8
|
||
- refToLogin
|
||
- refFromLoginLen: u8
|
||
- refFromLogin
|
||
- refTimeMs: u64
|
||
- refNonce: u32
|
||
```
|
||
|
||
Смысл:
|
||
|
||
- `refToLogin`
|
||
- `refFromLogin`
|
||
- `refTimeMs`
|
||
- `refNonce`
|
||
|
||
однозначно указывают на логическое сообщение по его `baseKey`.
|
||
|
||
Отдельный `refType` в v1 не нужен, потому что подтверждение прочтения относится к самому логическому сообщению, а не к выбору между копиями `type=1` и `type=2`.
|
||
## 7. Контент типов `1/2`
|
||
|
||
Для типов `1/2`:
|
||
|
||
- `bodyLen > 0`
|
||
- `body` обязан быть контейнером `EncryptedBody_v1_0`
|
||
- ciphertext у `type=1` и `type=2` может быть разным
|
||
|
||
### Новое сообщение
|
||
|
||
- `revisionTimeMs = 0`
|
||
- `reencryptedAtMs = 0`
|
||
|
||
### Редактирование
|
||
|
||
- `revisionTimeMs > 0`
|
||
- `reencryptedAtMs = 0` или больше нуля, если одновременно произошла перешифровка
|
||
|
||
### Перешифровка
|
||
|
||
- `revisionTimeMs = 0` или `> 0`
|
||
- `reencryptedAtMs > 0`
|
||
|
||
## 8. Контент типов `3/4`
|
||
|
||
Типы:
|
||
|
||
- `3` — входящее подтверждение прочтения
|
||
- `4` — исходящая копия подтверждения прочтения
|
||
|
||
Правила:
|
||
|
||
- `bodyLen > 0`
|
||
- `body` обязан быть контейнером `ReadReceiptBody_v1_0`
|
||
- `revisionTimeMs = 0`
|
||
- `reencryptedAtMs = 0`
|
||
|
||
Тип `3` и тип `4` по стилю полностью подчиняются общему контейнеру `SHiNE_DM`:
|
||
|
||
- тот же `prefix = "SHiNE_DM"`
|
||
- те же `formatVersionMajor = 1`
|
||
- те же `formatVersionMinor = 0`
|
||
|
||
Различается только `messageType` и формат `body`.
|
||
|
||
### Серверное примечание
|
||
|
||
Внешний байтовый формат `type=3/4` не меняется, но сервер использует такие контейнеры как вход для обновления `dm_dialog_state`:
|
||
|
||
- `read receipt` обновляет серверный watermark диалога;
|
||
- `unreadCount` пересчитывается на сервере, а не только на клиенте;
|
||
- если подтверждение прочтения приходит в другом порядке, сервер сохраняет максимальный watermark и не откатывает счётчик назад.
|
||
- в списке диалогов сервер может отдавать последний signed block как `lastMessageBlobB64` без попытки извлечь plaintext preview.
|
||
|
||
## 9. Контент типов `5/6`
|
||
|
||
Типы:
|
||
|
||
- `5` — сообщение удалено отправителем
|
||
- `6` — сообщение удалено получателем
|
||
|
||
Правила:
|
||
|
||
- `bodyLen = 0`
|
||
- `body` отсутствует
|
||
- `revisionTimeMs > 0`
|
||
- `reencryptedAtMs = 0`
|
||
|
||
Это terminal tombstone конкретного сообщения.
|
||
|
||
После принятия такого контейнера содержательная версия этого же `messageKey` больше не должна приниматься.
|
||
|
||
## 10. Контент типов `7/8`
|
||
|
||
Типы:
|
||
|
||
- `7` — переписка удалена отправителем
|
||
- `8` — переписка удалена получателем
|
||
|
||
Правила:
|
||
|
||
- `bodyLen = 0`
|
||
- `body` отсутствует
|
||
- `revisionTimeMs = 0`
|
||
- `reencryptedAtMs = 0`
|
||
|
||
Здесь роль границы удаления играет:
|
||
|
||
- `timeMs` самого контейнера
|
||
|
||
После принятия такого контейнера:
|
||
|
||
- более старые сообщения этой пары должны быть удалены;
|
||
- более старые новые поступления этой пары не должны приниматься.
|
||
|
||
## 11. Подпись
|
||
|
||
Поле `signature` всегда подписывает весь контейнер от `prefix` до конца `body` включительно.
|
||
|
||
Правило подписи по `messageType`:
|
||
|
||
- `1`, `2`, `5`, `7` подписывает отправитель сообщения;
|
||
- `6`, `8` подписывает получатель сообщения.
|
||
|
||
Практическое UI-следствие:
|
||
|
||
- клиентский UI может инициировать удаление входящего сообщения через `type=6`;
|
||
- клиентский UI может инициировать очистку истории переписки через `type=8`;
|
||
- сами контейнеры и байтовый формат при этом не отличаются от уже описанных типов `5/6/7/8`.
|
||
|
||
## 12. Какие поля должны совпадать у пары `1/2`
|
||
|
||
При обычной парной отправке через `SendMessagePair` у двух копий должны совпадать:
|
||
|
||
- `fromLogin`
|
||
- `toLogin`
|
||
- `timeMs`
|
||
- `nonce`
|
||
- `revisionTimeMs`
|
||
|
||
Дополнительно:
|
||
|
||
- логический plaintext должен быть одинаковым;
|
||
- ciphertext может различаться;
|
||
- `reencryptedAtMs` при одной парной ревизии тоже должен совпадать.
|
||
|
||
## 13. Примечание о поддержке
|
||
|
||
В версии DM v1 все типы `1..8` используют единый контейнер `SHiNE_DM`.
|
||
|
||
`SendMessagePair` передаёт входящую и исходящую подписанные копии от UI на
|
||
сервер отправителя. Внутренняя операция `ReceiveIncomingMessage` передаёт
|
||
только входящую raw-копию в Base64 на единственный access-сервер получателя.
|
||
Обе операции используют существующий байтовый формат `SHiNE_DM`.
|
||
Межсерверные `ReceiveOutcomingMessage` и `DmSyncBatch` удалены.
|
||
Принимающий сервер заново проверяет пользовательскую подпись и применяет
|
||
контейнер по его `messageType`.
|
||
|
||
## 14. Превью в списке диалогов
|
||
|
||
Выбор последнего сообщения для клиентского превью не является частью байтового формата. Клиент сравнивает время сообщений обоих направлений и показывает текст самого нового входящего или исходящего сообщения. Локальная расшифрованная копия может временно иметь приоритет над более старым `lastMessageBlobB64` из серверной сводки.
|
||
|
||
Контейнер `SHiNE_DM`, подписи, `messageType`, порядок полей и правила шифрования этой UI-доработкой не изменяются.
|
||
|
||
## Примечание UI списка чатов (2026-08-28)
|
||
Это изменение не меняет байтовый формат DM. В списке чатов клиент может фильтровать уже полученные диалоги по `relationFlag` (`close_friend`, `contact`, `none`) и локально форматировать время последнего сообщения: относительное для недавних, `DD.MM, HH:MM` в текущем году и `DD.MM.YYYY` для прошлых лет.
|