From 6b5dcd2a646decfedd4aa23c6f3ec369d200e823 Mon Sep 17 00:00:00 2001 From: evgeny Date: Sun, 25 Oct 2026 23:26:24 +0100 Subject: [PATCH] Document SOCKS ownership and cover empty UDP and input limits --- src/transport_layer/socks_client_doc.md | 62 +++++++++++++++++++++++++ tests/test_socks_client.c | 26 ++++++++++- 2 files changed, 87 insertions(+), 1 deletion(-) create mode 100644 src/transport_layer/socks_client_doc.md diff --git a/src/transport_layer/socks_client_doc.md b/src/transport_layer/socks_client_doc.md new file mode 100644 index 000000000..97fbb784e --- /dev/null +++ b/src/transport_layer/socks_client_doc.md @@ -0,0 +1,62 @@ +# socks_client + +SOCKS5 control-клиент для TCP CONNECT и UDP ASSOCIATE. Состояние принадлежит одному uasync-потоку; +cfg копируется, строки host/user/pass должны иметь NUL в массиве по 64 байта, port ненулевой. +Пустой user предлагает no-auth, непустой — no-auth и username/password (метод выбирает прокси). +Пароли не логируются. Имя самого прокси разрешается синхронным `getaddrinfo`, берётся первый IPv4/IPv6 адрес. +Это не общий асинхронный DNS-клиент; CONNECT target-domain передаётся прокси без локального резолвинга. + +## CONNECT + +`socks_dial(ua,cfg,target_host,target_port,cb,arg,timeout_tb)` принимает имя 1..255 байт без обрезания +и ненулевой target port. Числовой IP кодируется как ATYP 1/4, домен — ATYP 3. +Возврат NULL означает немедленный отказ без callback, возвращённый handle можно отменить через socks_dial_cancel. +timeout_tb задаёт общий connect+handshake срок в 0.1мс; <=0 означает 10 секунд. +Nonblocking, uasync-регистрация и таймер обязательны; отказ запуска откатывает ресурсы. +Даже немедленный успех connect продолжает handshake только после возврата конструктора. + +Control читает ровно текущую рамку: greeting/auth по 2 байта, reply по ATYP и длине адреса. +Проверяются VER/RSV/REP/ATYP. Данные TCP-потока после CONNECT reply остаются в сокете, +в том числе когда пришли одним TCP-чтением ОС с ответом прокси. +Отправка подавляет SIGPIPE, повторяет EINTR, ждёт writable при EAGAIN; нулевой send даёт EPIPE. +Полная очередь управления не заменяется новой рамкой. + +Завершение освобождает dial до cb. Успех передаёт владельцу незарегистрированный nonblocking socket, +ошибка закрывает его и передаёт SOCKET_INVALID/errno, WSA или протокольный код. +Handle после завершения недействителен; отменять его из callback нельзя. Cancel не вызывает cb. + +## UDP ASSOCIATE + +`socks_udp_associate` заимствует уже созданный local_udp_fd, держит отдельный TCP-control и relay. +На каждую попытку отводится 10 секунд. Разрыв/протокольная ошибка очищают ready, закрывают control +и планируют backoff 1,2,4,8,16,30,30... секунд. Успех сбрасывает backoff. +Начальная ошибка connect может вернуть handle с ожидающим retry; при невозможности поставить +как начальную работу, так и retry возвращается NULL без callback. + +Relay поддерживает только числовой IPv4/IPv6 и ненулевой BND.PORT. +Wildcard BND.ADDR заменяется IP TCP-прокси того же семейства с сохранением BND.PORT. +Callback err=0 приходит при каждом успешном согласовании, включая повторное. +Если после запуска невозможно выделить retry timer, callback получает ENOMEM; +сессия остаётся unready, владелец должен destroy/recreate. В callback можно уничтожить сессию. +Остальные control-ошибки с успешной постановкой reconnect видны в proxy-логе. +Неожиданные данные на готовом control игнорируются с WARN. + +`socks_udp_sendto` принимает 0..2048 байт, оборачивает в RSV=0/FRAG=0/ATYP/address/port +и отправляет через заимствованный UDP fd на relay. Успех возвращает длину данных без заголовка, +включая 0 для пустой датаграммы; -1 означает ошибку/не готово. DST только IPv4/IPv6. +Проверка длины выполняется до сложения/копирования; частичная отправка датаграммы считается ошибкой. + +`socks_udp_unwrap` не использует s (допускается NULL), проверяет RSV/FRAG/ATYP и длины. +IPv4/IPv6 возвращают src и payload; domain/фрагменты не поддерживаются. +Возврат -1 сохраняет src/payload, 0 означает корректную пустую датаграмму. +Payload можно сдвигать в том же буфере, src должен быть отдельным. Вместимость требуется для полного payload. +Функция не проверяет адрес UDP-отправителя: caller должен принимать данные своего relay, +если не полагается на последующую аутентификацию транспорта. + +Destroy снимает control/таймеры и освобождает состояние, local_udp_fd остаётся у владельца. +Все этапы/отказы видны в категории proxy; ожидание ready на send — trace. + +`test_socks_client` покрывает no-auth/auth, доменное назначение, reject, UDP echo/reconnect, +CONNECT reply вместе с первым TCP-баннером, неверный RSV, startup/retry timer faults, +синхронно завершённый connect с нулевым send, destroy из ready, пустой UDP, +границы конфигурации/длины и неизменность выходов при отказе. diff --git a/tests/test_socks_client.c b/tests/test_socks_client.c index 8625b2d61..24a5bf663 100644 --- a/tests/test_socks_client.c +++ b/tests/test_socks_client.c @@ -459,6 +459,14 @@ static int test4_udp_associate(void) { TASSERT(memcmp(&src, &unchanged, sizeof(src)) == 0); TASSERT(socks_udp_unwrap(NULL, raw, (size_t)got, payload, 4, &src) == -1); TASSERT(memcmp(&src, &unchanged, sizeof(src)) == 0); + TASSERT(socks_udp_unwrap(NULL, raw, (size_t)got, raw, sizeof(raw), &src) == 5 && !memcmp(raw, "hello", 5)); + TASSERT(socks_udp_sendto(su, NULL, 0, &peer) == 0); + got = -1; + for (int i = 0; got < 0 && i < 5000; i++) { + got = recvfrom(lfd, raw, sizeof(raw), 0, NULL, NULL); + if (got < 0) test_clock_poll(ua, 10); + } + TASSERT(got == 10 && socks_udp_unwrap(NULL, raw, (size_t)got, NULL, 0, &src) == 0); socks_udp_destroy(su); socket_close_wrapper(lfd); @@ -591,9 +599,24 @@ static int test8_destroy_in_udp_ready(void) { return 0; } +static int test9_argument_bounds(void) { + struct UASYNC* ua = uasync_create(); TASSERT(ua); + struct socks_cfg cfg = {0}; strcpy(cfg.host, "127.0.0.1"); cfg.port = 1; + char long_name[257]; memset(long_name, 'a', 256); long_name[256] = 0; + g_done = 0; + TASSERT(!socks_dial(ua, &cfg, long_name, 22, dial_cb, NULL, 0) && !g_done); + TASSERT(!socks_dial(ua, &cfg, "127.0.0.1", 0, dial_cb, NULL, 0) && !g_done); + memset(cfg.host, 'x', sizeof(cfg.host)); + TASSERT(!socks_dial(ua, &cfg, "127.0.0.1", 22, dial_cb, NULL, 0) && !g_done); + TASSERT(!socks_udp_associate(ua, &cfg, 1, NULL, NULL)); + strcpy(cfg.host, "127.0.0.1"); memset(cfg.user, 'x', sizeof(cfg.user)); + TASSERT(!socks_dial(ua, &cfg, "127.0.0.1", 22, dial_cb, NULL, 0) && !g_done); + uasync_destroy(ua, 1); return 0; +} + int main(void) { debug_config_init(); - debug_set_level(DEBUG_LEVEL_ERROR); + debug_set_level(DEBUG_LEVEL_INFO); test_clock_init(1000); socket_platform_init(); @@ -606,6 +629,7 @@ int main(void) { {"test6_banner_and_reply_validation", test6_banner_and_reply_validation}, {"test7_start_failures_and_deferred_callback", test7_start_failures_and_deferred_callback}, {"test8_destroy_in_udp_ready", test8_destroy_in_udp_ready}, + {"test9_argument_bounds", test9_argument_bounds}, }; int n = (int)(sizeof(tests) / sizeof(tests[0])); int passed = 0;