stadium-proto/HANDSHAKE.md

Handshake

После успешной установки защищённого соединения, происходит обмен характеристиками обоих сторон, AKA "рукопожатие". Запрашивающий соединение отправляет пакет следующего формата:

[magic number: 8B][protocol version: 4B][sizes: 1B][crypto params: 2B][reconnection flags: 2B]

• Магическое число
  • Тип: uint64_t
  • Магическое число протокола, по которому определяется совместимость цели с протоколом Stadium. См. раздел "Магическое число" для справки.
• Версия протокола
  • Тип: uint32_t
  • Поддерживаемая запрашивающим версия протокола.
• Размерности частей пакета
  • Тип: uint8_t
  • Описывает некоторые параметры пакетов.
    • Маска 0b11000000: выделено под размерности типа событий
      • 0b00: резерв
      • 0b01: категория и подкатегория это uint8_t (каждая)
      • 0b10: категория - uint8_t, подкатегория - uint16_t
      • 0b11: категория и подкатегория это int16_t (каждая)
    • Маска 0b00110000: выделено под размерность ключа в ячейке полезной нагрузки
      • 0b00: резерв
      • 0b01: ключ это uint8_t
      • 0b10: ключ это uint16_t
      • 0b11: ключ это int32_t
    • Маска 0b00001100: выделено под размерность данных в ячейке
      • 0b00: резерв
      • 0b01: размер данных это uint8_t
      • 0b10: размер данных это uint16_t
      • 0b11: размер данных это uint64_t
    • Маска 0b00000011: резерв
• Параметры криптографии
  • Тип: uint16_t
  • Описывает используемые криптографические алгоритмы.
    • Если равно нулю, то используются опции данной версии протокола по умолчанию

• Флаги переподключения
  • Тип: uint16_t
  • Описывает параметры нового подключения:
    • 0b0000000000000000: оставить текущее подключение
    • 0b0000000000000001: переподключиться к тому-же порту
    • 0b0000000000000010: запросить новый порт для подключения
    • 0b0000000000000100: использовать TCP
    • 0b0000000000001000: использовать TLS
    • 0b0000111111110000: резерв под расширение
    • 0b1111000000000000: резерв под под нужды сторонних реализаций

На что целевой сервер отвечает пакетом либо с согласием, либо ошибкой.

Пакет с согласием имеет следующий формат:

[magic number: 8B][0x00][reconnection port: 2B]

• Магическое число
  • Тип: uint64_t
  • См. выше.
• 0x00
  • Тип: uint8_t
  • Байт с фиксированным нулевым значением, свидетельствующий об успешном подключении и принятии целевым сервером обозначенных условий.
• Порт для переподключения
  • Тип: uint8_t
  • К указанному порту целевой сервер предлагает подключиться запрашиваемому, если тот запросил его. Значение должно быть нулём, если порт не был запрошен.

Пакет с ошибкой имеет следующий формат:

[magic number: 8B][error code: 1B][error description: ~B, zero-terminated]

• Магическое число
  • Тип: uint64_t
  • См. выше.
• Код ошибки
  • Тип: uint8_t
  • Код, описывающий ошибку конкретнее.
    • 0x01: магическое число ложно.
    • 0x02: неподдерживаемая версия протокола.
    • 0x03: невозможно выделить новый порт для подключения.
    • 0x04: указанный транспортный протокол не поддерживается.
    • 0x05: указанная конфигурация размерностей не поддерживается.
    • 0x06: недопустимые параметры криптографии.
    • 0x07: один из указанных криптографических алгоритмов отключён на сервере.
• Описание ошибки
  • Тип: uint8_t
  • Текстовое описание ошибки. Является строкой в кодировке ASCII, оканчивающейся нулевым байтом.

Если цель не поддерживает указанную при рукопожатии версию протокола, запрашивающий может попробовать установить соединение снова, указав более низкую и поддерживаемую им версию протокола.

Если при хэндшейке запрашивающим был указан новый способ подключения и получен валидный ответ с согласием от сервера - то они обязаны разорвать текущее соединение, затем, спустя случайное количество времени, от 50 мс до 500 мс, создать новое.

Магическое число

Магическим числом протокола является следующая последовательность байт:

HEX: 0x53 0x74 0x61 0x64 0x69 0x75 0x6d 0x50
DEC:  83   116  97   100  105  117  109  80

Что соответствует строке "StadiumP" в кодировке ASCII.