From 7fd602885fc21d2622bbd5bfdd3a09ab1f2858dc Mon Sep 17 00:00:00 2001 From: bol-van Date: Mon, 15 Dec 2025 18:58:23 +0300 Subject: [PATCH] update docs --- docs/manual.md | 146 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) diff --git a/docs/manual.md b/docs/manual.md index b96294e..232653f 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -952,6 +952,10 @@ desync: number 6 .transport_len number 110 + .l3_len + number 40 + .l4_len + number 32 .reasm_offset number 0 .reasm_data @@ -1153,6 +1157,19 @@ ipv6 extension headers и tcp options представляются в форме Все числовые многобайтовые значения автоматически переведены из network byte order в machine byte order. +**dissect** +| Поле | Тип | Описание | +|:------|:----|:---------| +| ip | table | заголовок ipv4 | +| ip6 | table | заголовок ipv6 | +| tcp | table | заголовок tcp | +| udp | table | заголовок udp | +| l4proto | number | IPPROTO_TCP или IPPROTO_UDP | +| transport_len | number | длина пакета без L3 заголовков | +| l3_len | number | длина L3 заголовков, включая ip options и ipv6 extension headers | +| l4_len | number | длина L4 заголовка, включая tcp options | +| payload | string | L4 пейлоад | + **ip** | Поле | Описание | |:------|:---------| @@ -1537,3 +1554,132 @@ HKDF - HMAC-based Key Derivation Function. Генератор ключей на * okm_len - требуемая длина okm - output keying material * возвращается raw строка - okm +### Системные функции + +``` + function uname() +``` + +Возвращает то же самое, что и команда uname в shell - название ядра ОС. "Linux", "FreeBSD", "OpenBSD". +В Windows возвращается строка, начинающаяся с "CYGWIN", далее следует версия. + + +``` + function clock_gettime() +``` + +Узнать точное время. Возвращает 2 значения - unixtime в секундах и наносекунды. Встроенная функция `os.time()` не выдает наносекунды. + +``` + function getpid() + function gettid() +``` + +* getpid() возвращает идентификатор текущего процесса - PID +* gettid() возвращает идентификатор текущего потока - TID + + +### Опции по работе с пакетами + +В следующих функциях будут использоваться стандартные наборы опций - rawsend и reconstruct. +Они представляют собой таблицы со специфическими полями. Если nil, считается, что ни одно поле не задано. + +Опции реконструкции диссектов - reconstruct_opts. Реконструкция - это сборка raw пакета из диссекта. +| Поле | Тип | Описание | +|:------|:----|:---------| +| badsum | bool | испортить L4 checksum. сделать xor со случайным значением от 1 до 0xFFFF | +| ip6_preserve_next | bool | использовать значения "next" из ip6.exthdr | +| ip6_last_proto | number | если ip6_preserve_next=true, IP протокол последнего exthdr | + +При сборке ipv6 по умолчанию цепочка ip протоколов в exthdr собирается автоматически. +У каждого exthdr есть поле type, поэтому понятно что вписывать в предыдущий exthdr, +либо в основной ip6 хедер. next протокол последнего exthdr устанавливатеся как IPPROTO_TCP +или IPPROTO_UDP в зависимости от наличия в диссекте таблиц tcp или udp. +В большинстве случаев это удобно, поскольку вам при вставлении exthdr не надо реконструировать +всю цепочку next протоколов. За вас это сделает реконструктор диссекта. + +Режим ip6_preserve_next используется, если у вас специальная цель, требующая ручной крафтинг полей next protocol. +В этом случае невозможно автоматически узнать что вы хотите вписать в последний exthdr. Туда вписывается ip6_last_proto, +либо IPPROTO_NONE, если не ip6_last_proto не задан. + +badsum вынесен в реконструкцию, поскольку чексуммы tcp и udp считаются на базе всего IP пакета. +В сумме участвуют элементы хедера ip/ip6, весь хедер tcp и сам пейлоад. +Поэтому по отдельным частям гарантированно испортить чексумму невозможно. +Что бы вы туда не вписали, существует маленькая вероятность (1/65536), что она окажется верной. + +Опции отсылки raw пакетов - rawsend_opts +| Поле | Тип | Описание | +|:------|:----|:---------| +| repeats | number | количество повторов отсылки одного и того же пакета | +| fwmark | number | fwmark исходящего пакета. только для linux. по умолчанию 0. бит desync_mark устанавливается принудительно | +| ifout | string | исходящий интерфейс. может использоваться и не использоваться в разных ситуациях | + +ifout всегда следует передавать таким, каким он пришел в диссекте. +Для windows правильный ifout обязателен. На BSD он не используется. +На Linux используется только если включены опции `--bind-fix4` или `--bind-fix6` в зависимости от версии ip. + +fwmark желательно передавать таким, каким он пришел в диссекте. +При особых случаях, когда на этом построены ваши правила таблиц, можно домешивать туда свои биты. + +repeats шлют бинарно идентичный пакет указанное количество раз, не разбираясь в его содержимом. +Никаких изменений , в том числе ip_id, не производится. +Если вам нужно изменение ip_id, можно его сделать 0, тогда Windows сама допишет увеличивающиеся значения. +Другие системы - нет. Если вам надо на любых системах управлять ip_id, то repeats - не вариант. + +### Диссекция и реконструкция + +Диссекция - процесс получения структурированного представления raw ip пакета. +Реконструкция - обратный процесс - получение raw ip из диссекта. + +``` +function dissect(raw_ip) +``` + +Возвращает таблицу - диссект пакета raw_ip. +Это та же самая операция, что происходит автоматически до вызова desync функций по профилю. +Они получают уже готовый диссект. + +``` +function reconstruct_dissect(dissect, reconstruct_opts) +``` + +Возвращает raw_ip. Все чексуммы считаются автоматически. L4 чексуммы портятся, если задан badsum в reconstruct_opts. + +``` +function reconstruct_tcphdr(tcp) +function reconstruct_udphdr(udp) +function reconstruct_iphdr(ip) +function reconstruct_ip6hdr(ip6, reconstruct_opts) +``` + +Реконструкция соответствующих raw заголовков из таблиц диссекта. Возвращает raw вариант заголовка. +* реконструкция ip6 задействует reconstruct_opts. из них берется ip6_preserve_next и ip6_last_proto. +* чексумма ip header считается автоматически, поскольку ни от чего больше не зависит +* чексуммы tcp и udp не считаются, поскольку зависят от других компонент + +``` +function csum_ip4_fix(raw_ipv4_header) +function csum_tcp_fix(raw_ip_header, raw_tcp_header, payload) +function csum_udp_fix(raw_ip_header, raw_udp_header, payload) +`` + +Функции для выправления чексумм. Поскольку строки в LUA immutable, они возвращают копию соответствующего заголовка +с исправленной чексуммой. + +* с csum_ipv4_fix все просто. на входе ip заголовок, на выходе ip заголовок с исправленной суммой +* csum_tcp_fix и csum_udp_fix берут raw ip заголовок (ipv4 или ipv6), tcp/udp заголовок и пейлоад. версия ip определяется автоматически. чексумма считается на базе L3, L4 заголовков и пейлоада. + +Прямая реконструкция отдельных заголовков нужна редко. Обычно все задачи выполняют функции по работе с диссектами. +Но если у вас особый случай, например вам нужно сконструировать icmp, то вам придется собирать его по частям и использовать rawsend для отсылки. +csum_ip4_fix вам наверняка понадобится. + +### Отсылка пакетов + +``` +function rawsend(raw_data, rawsend_opts) +function rawsend_dissect(dissect, rawsend_opts, reconstruct_opts) +``` + +* rawsend работает с raw строкой, содержащий полностью собранный ipv4 или ipv6 пакет +* rawsend_dissect собирает пакет из диссекта и отправляет +* dissect представляет собой таблицу, описанную в соответствующем разделе