SHA256
119 lines
6.7 KiB
Markdown
119 lines
6.7 KiB
Markdown
# ESP Pairing и режимы подключения
|
||
|
||
Этот документ фиксирует актуальные режимы входа/подключения в SHiNE. Он нужен как отдельная точка входа по сценариям подключения, чтобы не смешивать обычную авторизацию и серверный pairing через доверенное уже авторизованное устройство пользователя.
|
||
|
||
## 1. Текущие режимы
|
||
|
||
### 1. Создание новой сессии через `clientKey`
|
||
|
||
Поток:
|
||
|
||
`AuthChallenge -> CreateAuthSession`
|
||
|
||
Смысл:
|
||
|
||
- новое устройство уже владеет приватным `clientKey`;
|
||
- сервер проверяет подпись `clientKey`;
|
||
- создаётся обычная активная сессия пользователя;
|
||
- этот поток остаётся без изменений.
|
||
|
||
### 2. Повторный вход в существующую сессию через `sessionKey`
|
||
|
||
Поток:
|
||
|
||
`SessionChallenge -> SessionLogin`
|
||
|
||
Смысл:
|
||
|
||
- устройство уже владеет приватным `sessionKey`;
|
||
- сервер проверяет подпись `sessionKey`;
|
||
- соединение снова входит в существующую сессию;
|
||
- этот поток тоже остаётся без изменений.
|
||
|
||
## 2. Добавление сессии через доверенное устройство пользователя
|
||
|
||
Новый поток не заменяет обычный логин, а живёт рядом с ним.
|
||
|
||
Цель:
|
||
|
||
- новое устройство знает `login`, а `pairing password` используется только если он включён на доверённом устройстве;
|
||
- сервер использует пароль только как фильтр от мусора;
|
||
- реальное доверие даёт любая уже онлайн доверенная сессия пользователя;
|
||
- сервер не выдаёт приватные ключи сам от себя.
|
||
|
||
Текущий поток:
|
||
|
||
1. Любая доверенная сессия пользователя создаёт на сервере pairing-настройку:
|
||
`UpsertEspPairingSettings`
|
||
2. Новое устройство создаёт pending-заявку:
|
||
`StartEspPairing`
|
||
3. Онлайн доверенная сессия видит список активных заявок:
|
||
`ListEspPairingRequests`
|
||
4. Доверенная сессия либо подтверждает заявку:
|
||
`ApproveEspPairing`
|
||
5. Либо отклоняет:
|
||
`RejectEspPairing`
|
||
6. Новое устройство читает результат:
|
||
`GetEspPairingStatus`
|
||
|
||
## 3. Что именно делает сервер
|
||
|
||
- хранит включённость pairing и optional `passwordHash` в формате `sha256$<hex>`;
|
||
- хранит pairing-заявки всех статусов, но в список активных для доверённого устройства отдаёт только pending `created`;
|
||
- рассчитывает короткий код `shortCode` из `10` цифр;
|
||
- рассчитывает длинный `fingerprintB58` из `SHA-256` заявки;
|
||
- уведомляет онлайн доверенные сессии событием `IncomingEspPairingRequest`, если такие сессии подключены;
|
||
- хранит переданный `encryptedPayload` как непрозрачную строку и не анализирует его содержимое.
|
||
|
||
## 4. Чего сервер в этом режиме не делает
|
||
|
||
- не передаёт приватный `clientKey`;
|
||
- не расшифровывает `encryptedPayload`;
|
||
- не проверяет криптографию содержимого payload;
|
||
- не делает клиентский UI;
|
||
- не навязывает конкретную схему `Ed25519 -> X25519` в коде сервера.
|
||
|
||
Это намеренно: сервер остаётся безопасным каркасом маршрутизации и состояния, а E2E-логика упаковки ключей живёт на клиентах и ESP-устройствах.
|
||
|
||
## 5. Роли и ограничения
|
||
|
||
- любая уже авторизованная доверенная сессия пользователя может вызывать:
|
||
- `UpsertEspPairingSettings`
|
||
- `ListEspPairingRequests`
|
||
- `ApproveEspPairing`
|
||
- `RejectEspPairing`
|
||
- новое устройство может вызвать `StartEspPairing` и `GetEspPairingStatus` без уже существующей авторизованной сессии;
|
||
- `payloadType` поддерживается в вариантах:
|
||
- `1` — минимальный пакет
|
||
- `2` — расширенный пакет
|
||
- `3` — полный пакет
|
||
|
||
Сервер не интерпретирует эти три типа глубже, а только фиксирует их в состоянии заявки.
|
||
|
||
## 6. Статусы pairing-заявки
|
||
|
||
- `created` — заявка создана и ждёт решения доверенной сессии;
|
||
- `approved` — доверенная сессия подтвердила и приложила `encryptedPayload`;
|
||
- `rejected` — доверенная сессия отклонила заявку;
|
||
- `expired` — TTL заявки истёк до подтверждения.
|
||
|
||
## 7. Практический смысл
|
||
|
||
Эта схема даёт нужное разделение доверия:
|
||
|
||
- пароль на сервере, если он включён, только отсеивает лишних;
|
||
- онлайн доверенная сессия решает, добавлять ли новую сессию;
|
||
- сервер остаётся маршрутизатором и хранилищем состояния, а не владельцем секретов.
|
||
|
||
Текущий формат pairing-пароля:
|
||
|
||
```text
|
||
sha256$<hex( SHA-256("shine-pairing|" + lower(login.trim()) + "|" + password) )>
|
||
```
|
||
|
||
## 8. Связанный документ по внешнему кошельку
|
||
|
||
Для отдельного RPC-взаимодействия между браузерным wallet-расширением и ESP32 см. документ:
|
||
|
||
- [Формат_взаимодействия_внешнего_кошелька_и_ESP32.md](/home/ai/work/SHiNE/SHiNE-server-sha256/Dev_Docs/Протоколы/Формат_взаимодействия_внешнего_кошелька_и_ESP32.md)
|