Перейти к содержанию

Сверка настроек кворума

Если настройки кворума рабочего пространства подписывает владелец, новая версия вступает в силу после его подписи на устройстве в Pert Mobile. Перед подписью владелец сверяет отпечаток версии в консоли и в приложении: совпадение значит, что подписываются ровно те настройки, которые составлены в консоли.

Подписывает ли владелец настройки, что входит в версию и кто её отправляет — в разделе Настройки под подписью владельца.

Кто что делает

Участник Где Что делает
Владелец или администратор консоль, настройки кворума отправляет новую версию на подпись и видит её номер и отпечаток
Владелец карточка запроса в Pert Mobile видит, что меняется, номер версии и отпечаток; подтверждая запрос, подписывает версию

Как сверить

  1. Отправьте новую версию настроек: консоль покажет номер версии и отпечаток — восемь групп по четыре символа.
  2. Владелец открывает запрос в Pert Mobile. Приложение считает отпечаток само по настройкам из запроса.
  3. Если версию отправил администратор, он диктует номер и отпечаток по каналу, где владелец узнаёт собеседника: телефонный или видеозвонок.
  4. Владелец сверяет номер версии и все восемь групп и подтверждает запрос.

Отпечатки не совпадают

Отклоните запрос: подтвердив его, владелец подписал бы не те настройки, что составлены в консоли. Затем отправьте настройки заново.

Отпечаток не пересылайте

Не принимайте отпечаток в почте или мессенджере, где нельзя убедиться в отправителе. Тот, кто может подменить настройки, может подменить и такое сообщение.

Формат отпечатка

  1. Каноническая запись настроек версии.
  2. SHA-256 от неё — snapshot_hash в ответах API.
  3. Первые 16 байт результата.
  4. Шестнадцатеричная запись заглавными буквами, восемь групп по четыре символа через пробел, как у отпечатка ключа устройства.
0C3E 938C 909D F89D 04F1 24D5 CC22 98C7

Каноническая запись

Настройки записываются последовательностью полей. Поле — байт типа, длина значения (8 байт, big-endian) и само значение.

Тип Байт Значение
домен 0x01 pert/quorum-settings/v1 в UTF-8
строка 0x02 UTF-8
uuid 0x03 16 байт в порядке RFC 4122
флаг 0x04 1 байт: 0x00 или 0x01
число 0x05 8 байт, знаковое, big-endian
пусто 0x07 длина 0

Порядок полей — по полям settings из запроса новой версии:

домен    pert/quorum-settings/v1
uuid     tenant_uuid
число    admin_quorum_threshold
число    количество правил
  для каждого правила, по возрастанию action_key:
  строка        action_key
  флаг          is_enabled
  строка        mode: owner_only | admin_quorum | specific_group
  uuid | пусто  group_uuid; пусто, если mode не specific_group
  число         group_threshold
  флаг          owner_approval
  флаг          admins_can_cancel
число    количество групп
  для каждой группы, по возрастанию group_uuid:
  uuid          group_uuid
  число         количество участников
  uuid …        участники по возрастанию
число    количество администраторов кворума
uuid …   администраторы кворума по возрастанию
  • mode записывается кодом: owner_only для QUORUM_APPROVAL_MODE_OWNER_ONLY, admin_quorum для QUORUM_APPROVAL_MODE_ADMIN_QUORUM, specific_group для QUORUM_APPROVAL_MODE_SPECIFIC_GROUP. В payload запроса на согласование режим уже записан кодом.
  • Правила сортируются по байтам UTF-8 action_key, группы, участники и администраторы — по 16 байтам uuid. Пустой список — количество 0.
  • Записываются отправленные значения как есть: настройки, которые не проходят проверки, платформа отклоняет, а не исправляет.

Тестовые векторы

Вектор 1 Вектор 2
tenant_uuid 7c9e6679-7425-40de-944b-e07fc1f90ae7 7c9e6679-7425-40de-944b-e07fc1f90ae7
settings {"admin_quorum_threshold": 1, "rules": [], "groups": [], "admins": []} ниже
Длина записи 125 байт 475 байт
snapshot_hash ab8b96189ab2e71c494272f56f2d9691cfbc59022464246711d7a492bb66bd08 0c3e938c909df89d04f124d5cc2298c7f59e3a1cb05a029e9deffd5f96726b78
Отпечаток AB8B 9618 9AB2 E71C 4942 72F5 6F2D 9691 0C3E 938C 909D F89D 04F1 24D5 CC22 98C7

settings вектора 2. Ключи действий в нём условные, а правила, участники и администраторы даны не по порядку — сортирует запись:

{
  "admin_quorum_threshold": 2,
  "rules": [
    { "action_key": "example.b", "is_enabled": true, "mode": "QUORUM_APPROVAL_MODE_SPECIFIC_GROUP",
      "group_uuid": "5f2b3c4d-6e7f-4a8b-9c0d-1e2f3a4b5c6d", "group_threshold": 2,
      "owner_approval": true, "admins_can_cancel": false },
    { "action_key": "example.a", "is_enabled": true, "mode": "QUORUM_APPROVAL_MODE_ADMIN_QUORUM",
      "group_threshold": 1, "owner_approval": false, "admins_can_cancel": true }
  ],
  "groups": [
    { "group_uuid": "5f2b3c4d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
      "members": ["6fa459ea-ee8a-4ca4-894e-db77e160355e", "1b4e28ba-2fa1-4d2e-883f-0016d3cca427"] }
  ],
  "admins": ["9a3f6c2e-1d4b-4e8a-b7c5-3e2d1f0a9b8c", "2c5e8f1a-4b7d-4a0e-9c3f-6b1d8e2a5f70"]
}
Каноническая запись вектора 1, hex
010000000000000017706572742f71756f72756d2d73657474696e67732f7631
0300000000000000107c9e6679742540de944be07fc1f90ae705000000000000
0008000000000000000105000000000000000800000000000000000500000000
0000000800000000000000000500000000000000080000000000000000
Каноническая запись вектора 2, hex
010000000000000017706572742f71756f72756d2d73657474696e67732f7631
0300000000000000107c9e6679742540de944be07fc1f90ae705000000000000
0008000000000000000205000000000000000800000000000000020200000000
000000096578616d706c652e610400000000000000010102000000000000000c
61646d696e5f71756f72756d0700000000000000000500000000000000080000
0000000000010400000000000000010004000000000000000101020000000000
0000096578616d706c652e620400000000000000010102000000000000000e73
706563696669635f67726f75700300000000000000105f2b3c4d6e7f4a8b9c0d
1e2f3a4b5c6d0500000000000000080000000000000002040000000000000001
0104000000000000000100050000000000000008000000000000000103000000
00000000105f2b3c4d6e7f4a8b9c0d1e2f3a4b5c6d0500000000000000080000
0000000000020300000000000000101b4e28ba2fa14d2e883f0016d3cca42703
00000000000000106fa459eaee8a4ca4894edb77e160355e0500000000000000
0800000000000000020300000000000000102c5e8f1a4b7d4a0e9c3f6b1d8e2a
5f700300000000000000109a3f6c2e1d4b4e8ab7c53e2d1f0a9b8c

snapshot_hash вектора 1 можно проверить командой:

printf '%s' '010000000000000017706572742f71756f72756d2d73657474696e67732f76310300000000000000107c9e6679742540de944be07fc1f90ae70500000000000000080000000000000001050000000000000008000000000000000005000000000000000800000000000000000500000000000000080000000000000000' \
  | xxd -r -p | openssl dgst -sha256

Почему так

  • Отпечаток считает каждая сторона сама: консоль — по настройкам, которые составила, Pert Mobile — по настройкам из запроса. snapshot_hash и fingerprint из ответов платформы сверку не заменяют: подмена настроек по дороге подменила бы и их.
  • Каноническая запись, а не JSON: байты одинаковы в любой реализации, без правил порядка ключей, экранирования и записи чисел.
  • В запись входит рабочее пространство: версию одного рабочего пространства нельзя выдать за версию другого.
  • 16 байт SHA-256 дают 128 бит: подобрать другие настройки с тем же отпечатком практически невозможно.