ipoim/README.md

Internet Protocol over Incidental Medium

IPoIM - это средство для туннелирования SOCKS5 соединения через среду передачи, которая не предназначена для туннелирования таких соединений. IPoIM разрабатывается в расчёте на то, что к нему можно без больших усилий дописывать расширения на языке C.

Терминология

• среда передачи - то, через что передаются данные. Например, расширение vk-msg реализует передачу данные через сообщения ВК. Значит, в контексте расширения vk-msg "отправить данные через среду передачи" означает "отправить данные, закодировав их в сообщение"; а "принятие данных из среды передачи" - "принятие сообщения в ВК и его декодировка в двоичный вид".

Архитектура

• main.c - входная точка приложения, оркестратор
• event_loop.c, event_loop.h - реализация событийного цикла
  Здесь реализована асинхронная обработка событий через epoll
• connection.c, connection.h - реализация соединения
  Здесь реализован контроль за существующим соединением.
• client.c, client.h - реализация клиента
  Здесь реализовано установление соединения с сервером.
• server.c, server.h - реализация сервера
  Здесь реализован сервер.
• priv_medium.c, priv_medium.h
  Здесь реализованы внутренние функции IPoIM, связанные с Medium API. Эти функции не должны вызываться из кода расширений.
• medium.c, medium.h
  Здесь реализованы функции Medium API, которые вызываются из кода расширения.
• mediums/medium_<NAME>.c, mediums/medium_<NAME>.h
  Реализация расширений. Например, файлы medium_vk_msg.c и medium_vk_msg.h реализуют среду передачи vk-msg.

Разработка расширений

Расширение в своем заголовочном файле должно реализовывать функцию void medium_<NAME>_init(), которая инициализирует всё необходимое для работы расширения. Функция должна вызвать medium_set_callbacks(...), чтобы IPoIM могло взаимодействовать с расширением. Кроме этого расширение должно инициализировать всё, что ему необходимо для работы.

Также расширение должно реализовывать функцию void medium_<NAME>_deinit(), которая освобождает ресурсы и выполняет "правильное" завершение всего, что было инициализировано в ходе работы расширения.

Medium API

IPoIM реализует функции, которые позволяют расширению общаться с остальным приложением:

• void medium_epoll_ctl(int op, int fd, struct epoll_event *ev)
  • Что делает:
    • Вызывает epoll_ctl для дескриптора epoll, который отвечает за событийный цикл
  • Когда вызывать:
    • Когда нужно добавить, модифицировать или удалить описание файлового дескриптора в epoll
  • Заметки:
    • Если был вызван close(...) для файлового дескриптора, то не нужно вызывать эту функцию, чтобы удалить описание дескриптора из epoll. Ядро Linux само удаляет описание из epoll, если дескриптор закрывается
• void medium_set_callbacks(/* колбеки в порядке их перечисления в следующей главе */)
  • Что делает:
    • Сообщает IPoIM, какие функции соответствуют каким колбекам
  • Когда вызывать:
    • Инициализация расширения
  • Заметки: нет
• void medium_on_recv_data(const void *data, int32_t size)
  • Что делает:
    • Сообщает IPoIM, что из среды передачи были получены данные
  • Когда вызывать:
    • При получении данных из среды передачи
  • Заметки:
    • No-op, если data == NULL или size <= 0
• void medium_set_ready_to_send(bool state)
  • Что делает:
    • Сообщает IPoIM, готово ли расширение к вызову cbmed_on_send_data(...)
  • Когда вызывать:
    • При изменении готовности к вызову cbmed_on_send_data(...) и при инициализации
  • Заметки:
    • Изначально IPoIM предполагает, что среда передачи недоступна. Поэтому эта функция должна быть вызвана, как только расширение становится готовым к вызову cbmed_on_send_data(...) после инициализации
• void medium_set_max_send_size(int32_t size)
  • Что делает:
    • Сообщает IPoIM, какое максимальное количество байтов можно передать cbmed_on_send_data(...)
  • Когда вызывать:
    • При изменении максимального количества байтов cbmed_on_send_data(...)
  • Заметки:
    • Изначально IPoIM предполагает, что среда передачи может передать 1024 Б за один вызов cbmed_on_send_data(...)
    • Не допускается size <= 0

Необходимые колбеки

Все колбеки, которые вызывает IPoIM рекомендуется называть с префиксом cbmed_ (callback medium).

Время от времени IPoIM обращается к расширению, чтобы отправить данные. Чтобы IPoIM мог это делать, расширение должно реализовывать следующие колбеки:

• void cbmed_on_fd_event(int fd, uint32_t events)
  • Когда вызвается:
    • С файловым дескриптором, добавленным при помощи medium_epoll_ctl(...), что-то случилось
  • Желаемый исход:
    • IPoIM ожидает, что расширение выполнит нужные действия над файловыми дескрипторами, которые оно добавило в epoll
  • Аргументы:
    • fd - файловый дескриптор
    • events - битовая маска событий (см man epoll_ctl)
  • Возвращаемое значение: нет
  • Заметки: нет
• int32_t cbmed_on_send_data(const void *data, int32_t size)
  • Когда вызвается:
    • IPoIM хочет отправить данные через среду передачи
  • Желаемый исход:
    • IPoIM ожидает, что после вызова этого колбека, данные отправлены или запланированы к отправке
  • Аргументы:
    • data - двоичные данные, которые нужно отправить через среду передачи
    • size - размер двоичный данных в байтах
  • Возвращаемое значение:
    • В случае успеха колбек должен вернуть число байтов, ушедших в среду передачи
    • Если передача провалена, то колбек должен -1
  • Заметки:
    • Гарантируется size > 0
    • Гарантируется size <= max_send_size (см. medium_set_max_send_size(...))
    • Гарантируется, что этот колбек не будет вызван, если расширение не сообщило, что оно готово к отправке данных через среду передачи (см. medium_set_ready_to_send(...))