wolfSSL/wolfsentry

# wolfSentry -- wolfSSL 嵌入式防火墙/IDPS ## 描述 wolfSentry 是 wolfSSL 嵌入式 IDPS（入侵检测与防御系统）。 简单来说，wolfSentry 是一个嵌入式防火墙引擎（支持静态与完全动态规则），支持基于前缀和通配符的已知主机/网块查找，并且可以根据接口、地址族、协议、端口及其他流量参数进行匹配。此外，wolfSentry 可以作为一个动态可配置的逻辑枢纽，将用户定义的事件与用户定义的动作进行任意关联，关联上下文为连接属性。因此，可以详细追踪客户端-服务端关系的演化过程，允许通过预期使用模式传递流量，同时高效地拒绝滥用流量。 wolfSentry 与 lwIP 栈完全集成，通过源码树中 `lwip/` 下的补丁集实现，并具备与 wolfSSL 库的基础集成能力，用于对入站和出站连接进行应用层过滤。 wolfSentry 引擎可通过 API 动态配置程序化地控制，也可通过提供给引擎的 JSON 文本输入文件进行配置，或者通过 JSON 片段以动态、增量方式配置，或者以上方法的任意组合。 重新配置由事务语义保护，对线程目标的高级内部锁确保了原子策略切换，从而实现无缝服务可用性。回调允许实现传输无关的远程日志记录，例如通过 MQTT、syslog 或 DDS 消息总线。 wolfSentry 从设计之初就充分考虑了资源受限、裸机和实时环境的需求，具备算法可保持在指定的最大内存占用范围内，并维持确定的吞吐量。这使得在 FreeRTOS、Nucleus、NUTTX、Zephyr、VxWorks 和 Green Hills Integrity 等嵌入式目标上，以及 ARM 和其他常见嵌入式 CPU 与 MCU 上均可实现完整的防火墙与 IDPS 功能。wolfSentry 搭配动态防火墙功能，可额外增加仅 64k 的代码体积和 32k 的易失态内存占用，并能充分利用现有应用程序与同级库的逻辑与状态。 ## 文档 在 FreeRTOS-lwIP 上的基础应用集成已通过可使用的代码片段进行文档化，详见 [doc/freertos-lwip-app.md](doc/freertos-lwip-app.md)。 JSON 配置已由 [doc/json_configuration.md](doc/json_configuration.md) 详细记录。 安装 `doxygen` 后，可通过 `make doc-html` 从 wolfSentry 源码树顶部生成完整的 API 参考手册的 HTML 版本。 这是推荐的 API 引用方式。此外，源码分发包中的 `doc/` 子目录内还提供了 API 参考手册的 PDF 版本，路径为 `doc/wolfSentry_refman.pdf`。最新版本始终可在 [GitHub](https://raw.githubusercontent.com/wolfSSL/wolfsentry/master/doc/wolfSentry_refman.pdf) 获取。 最新变更与新增内容记录在仓库顶部的 [ChangeLog.md](ChangeLog.md) 中。 ## 依赖 在默认构建中，wolfSentry 依赖 POSIX 运行时环境，具体包括堆分配器、clock_gettime、stdio、信号量、pthreads 和字符串 API。 不过，通过各种构建选项可以避免这些依赖。 `make STATIC=1 SINGLETHREADED=1 NO_STDIO=1 EXTRA_CFLAGS="-DWOLFSENTRY_NO_CLOCK_BUILTIN -DWOLFSENTRY_NO_MALLOC_BUILTIN"` 可构建仅依赖少量基础字符串函数与 `inet_ntop()`（来自 POSIX.1-2001，也在 lwIP 中实现）的 libwolfsentry.a。此时必须在 `struct wolfsentry_host_platform_interface` 中设置分配器与时间回调，并通过 `wolfsentry_init()` 提供。 wolfSentry 的 `Makefile` 要求使用现代（v4.0+）的 GNU `make`。该库也可在 `make` 之外构建，例如在其他项目/框架中，通过创建用户设置宏文件并使用 `WOLFSENTRY_USER_SETTINGS_FILE` 宏传递其路径进行编译。 ## 构建 wolfSentry 在设计时考虑了可移植性，并为非 POSIX 和 C89 目标提供了支持。例如，其所有依赖项均可通过 FreeRTOS/newlib-nano/lwIP 运行时满足。如果构建 wolfSentry 遇到困难，请不要犹豫，通过我们的 [支持论坛]() 或直接联系 [support@wolfssl.com](mailto:support@wolfssl.com) 获取帮助。 当前发布的 wolfSentry 可从 [wolfSSL 网站](https://www.wolfssl.com/download) 以 ZIP 文件形式下载，开发者还可以 [浏览发布历史](https://github.com/wolfSSL/wolfsentry/tags) 并 克隆 [wolfSentry Git 仓库](https://github.com/wolfSSL/wolfsentry) 以获取最新的预发布更新。 可通过 `make` 传递若干标志以控制构建参数。`make` 会在构建时将它们存储在 `wolfsentry/wolfsentry_options.h` 中。若不使用 `make`，则应在编译 wolfSentry 和应用程序时均定义 C 宏 `WOLFSENTRY_USER_SETTINGS_FILE`，并将其指向包含设置的文件路径。 识别以下功能控制变量。默认情况下，真/假特性（如 `LWIP`、`NO_STDIO`、`NO_JSON` 等）均未定义，定义后即激活。可通过 `EXTRA_CFLAGS` 选项或 `USER_SETTINGS_FILE` 宏来设置宏。参考手册的“启动/配置/关闭子系统”主题提供了更详细的宏文档。 | `make` 选项 | 宏选项 | 描述 | | --- | --- | --- | | `SHELL` | | 提供 `bash` 的显式/替代路径。 | | `AWK` | | 提供 GNU `awk` 的显式/替代路径。 | | `V` | | 详细 `make` 输出
例如：`make V=1 -j test` | | `USER_MAKE_CONF` | | 用户定义的 make 子句，在主 Makefile 顶部包含
例如：`make -j USER_MAKE_CONF=Makefile.settings` | | `EXTRA_CFLAGS` | | 传递给编译器的额外参数（逐字传递） | | `EXTRA_LDFLAGS` | | 传递给链接器的额外参数（逐字传递） | | `SRC_TOP` | | 源码顶层目录（默认 `pwd -P`） | | `BUILD_TOP` | | 将产物构建到源码树之外或子目录中
例如：`make BUILD_TOP=./build -j test` | | `DEBUG` | | 编译器调试标志（默认 `-ggdb`） | | `OPTIM` | | 优化标志（默认 `-O3`） | | `HOST` | | 交叉编译的目标主机元组（默认未设置，即本地目标） | | `RUNTIME` | | 目标运行时生态系统（默认未设置；识别 `FreeRTOS-lwIP`、`Linux-lwIP` 和 `ThreadX-NetXDuo`） | | `C_WARNFLAGS` | | 警告标志（覆盖通用默认值） | | `STATIC` | | 构建静态链接的单元测试 | | `STRIPPED` | | 剥离二进制文件的调试符号 | | `FUNCTION_SECTIONS` | | 移除未使用的目标代码（按函数粒度）以最小化总体积 | | `BUILD_DYNAMIC` | | 构建动态链接库 | | `VERY_QUIET` | | 构建期间抑制所有非错误输出 | | `TAR` | | 用于 `make dist` 的 GNU tar 路径，在 macOS 上应设为 `gtar` | | `VERSION` | | 用于 `make dist` 的打包版本 | | `LWIP` | `WOLFSENTRY_LWIP` | 真/假 —— 为 lwIP 启用适当的构建设置 | | `NO_STDIO_STREAMS` | `WOLFSENTRY_NO_STDIO_STREAMS` | 定义以省略依赖 `stdio` 流 I/O 的功能 | | | `WOLFSENTRY_NO_STDIO_H` | 定义以禁止包含 `stdio.h` | | `NO_ADDR_BITMASK_MATCHING` | `WOLFSENTRY_NO_ADDR_BITMASK_MATCHING` | 定义以省略地址的位掩码匹配支持，仅支持前缀匹配 | | `NO_IPV6` | `WOLFSENTRY_NO_IPV6` | 定义以省略 IPv6 地址族支持 | | `NO_JSON` | `WOLFSENTRY_NO_JSON` | 定义以省略 JSON 配置支持 | | `NO_JSON_DOM` | `WOLFSENTRY_NO_JSON_DOM` | 定义以省略 JSON DOM API | | `CALL_TRACE` | `WOLFSENTRY_DEBUG_CALL_TRACE` | 定义以激活运行时调用栈日志记录（非常详细） | | `USER_SETTINGS_FILE` | `WOLFSENTRY_USER_SETTINGS_FILE` | 替代设置文件，取代自动生成的 `wolfsentry_settings.h` | | `SINGLETHREADED` | `WOLFSENTRY_SINGLETHREADED` | 定义以省略线程安全逻辑，并将安全函数与宏替换为无操作宏 | | | `WOLFSENTRY_NO_PROTOCOL_NAMES` | 若定义，省略错误代码与源文件名的可读渲染 API，将以数值形式呈现 | | | `WOLFSENTRY_NO_GETPROTOBY` | 定义以禁用按名称查找和渲染协议与服务 | | | `WOLFSENTRY_NO_ERROR_STRINGS` | 若定义，省略错误代码与源文件名的可读渲染 API，将以数值形式呈现 | | | `WOLFSENTRY_NO_MALLOC_BUILTINS` | 若定义，省略内置堆分配器原语；`wolfsentry_host_platform_interface` 必须提供 `struct wolfsentry_allocator` 中所有函数的实现 | | | `WOLFSENTRY_HAVE_NONGNU_ATOMICS` | 若 gnu 风格原子内建不可用，需定义此选项；`WOLFSENTRY_ATOMIC_*()` 宏定义需在 `WOLFSENTRY_USER_SETTINGS_FILE` 中提供（参见 `wolfsentry_util.h`） | | | `WOLFSENTRY_NO_CLOCK_BUILTIN` | 若定义，省略内置时间原语；`wolfsentry_host_platform_interface` 必须提供 `struct wolfsentry_timecbs` 中所有函数的实现 | | | `WOLFSENTRY_NO_SEM_BUILTIN` | 若定义，省略内置信号量原语；`wolfsentry_host_platform_interface` 必须提供 `struct wolfsentry_semcbs` 中所有函数的实现 | | | `WOLFSENTRY_USE_NONPOSIX_SEMAPHORES` | 若 POSIX 信号量 API 不可用，需定义此选项。若 `wolfsentry_util.c` 中无非 POSIX 内置实现，则必须设置 `WOLFSENTRY_NO_SEM_BUILTIN`，并提供完整的信号量实现（shim） | | | `WOLFSENTRY_SEMAPHORE_INCLUDE` | 定义为声明信号量 API 的头文件路径 | | | `WOLFSENTRY_USE_NONPOSIX_THREADS` | 若 POSIX 线程 API 不可用，需定义此选项；`WOLFSENTRY_THREAD_INCLUDE`、`WOLFSENTRY_THREAD_ID_T` 和 `WOLFSENTRY_THREAD_GET_ID_HANDLER` 也需要定义 | | | `WOLFSENTRY_THREAD_INCLUDE` | 定义为声明线程 API 的头文件路径 | | | `WOLFSENTRY_THREAD_ID_T` | 定义为与 POSIX `pthread_t` 类似的适当类型 | | | `WOLFSENTRY_THREAD_GET_ID_HANDLER` | 定义为与 POSIX `pthread_self` 类似的函数，返回 `WOLFSENTRY_THREAD_ID_T` 类型值 | | | `FREERTOS` | 为 FreeRTOS 构建 | ### 构建与自测示例 在 Linux 上构建并测试 libwolfsentry.a： `make -j test` 详细构建： `make V=1 -j test` 将产物构建到源码树之外或子目录中： `make BUILD_TOP=./build -j test` 从非标准目标安装到备用安装位置： `make BUILD_TOP=./build INSTALL_DIR=/usr INSTALL_LIBDIR=/usr/lib64 install` 构建 libwolfsentry.a 并在多种配置下测试： `make -j check` 在不支持多线程的情况下构建并测试 libwolfsentry.a： `make -j SINGLETHREADED=1 test` 其他可用的 make 标志包括 `STATIC=1`、`STRIPPED=1`、`NO_JSON=1` 以及 `NO_JSON_DOM=1`，同时 `DEBUG`、`OPTIM` 和 `C_WARNFLAGS` 的默认值也可以被合理覆盖。 通过用户提供的 Makefile 前置内容覆盖默认设置进行构建： `make -j USER_MAKE_CONF=Makefile.settings` （`Makefile.settings` 可包含类似 `OPTIM := -Os` 的简单设置，或包含额外规则与依赖机制的复杂 makefile 代码。） 构建尽可能小的极简库： `make -j SINGLETHREADED=1 NO_STDIO=1 DEBUG= OPTIM=-Os EXTRA_CFLAGS="-DWOLFSENTRY_NO_CLOCK_BUILTIN -DWOLFSENTRY_NO_MALLOC_BUILTIN -DWOLFSENTRY_NO_ERROR_STRINGS -Wno-error=inline -Wno-inline"` 使用用户设置构建并测试： `make -j USER_SETTINGS_FILE=user_settings.h test` 在 ARM32 上为 FreeRTOS 构建（假设 FreeRTOS 与 lwIP 源码树位置如下）： `make -j HOST=arm-none-eabi RUNTIME=FreeRTOS-lwIP FREERTOS_TOP=../third/FreeRTOSv202212.00 LWIP_TOP=../third/lwip EXTRA_CFLAGS=-mcpu=cortex-m7` ## 项目示例 在 `wolfsentry/examples/` 子目录中提供了一系列端口与应用程序示例，包括一个实现玩具 TLS 加密嵌入式 Web 服务器并与 Linux D-Bus 设施集成的弹出通知系统。 更全面的 API 使用示例位于： `tests/unittests.c`，特别是 `test_static_routes()`、`test_dynamic_rules()` 和 `test_json()`，以及 `tests/test-config*.json` 中的 JSON 配置文件。 在 [wolfSSL 仓库](https://github.com/wolfSSL/wolfssl) 中，可查看 `wolfssl/test.h` 中受 `WOLFSSL_WOLFSENTRY_HOOKS` 保护的代码，包括： `wolfsentry_store_endpoints()`、`wolfSentry_NetworkFilterCallback()`、`wolfsentry_setup()` 和 `tcp_connect_with_wolfSentry()`。 另请参考 `examples/server/server.c` 和 `examples/client/client.c` 中受 `WOLFSSL_WOLFSENTRY_HOOKS` 保护的代码。 通过 `--enable-wolfsentry` 配置 wolfssl 以构建集成 wolfSentry 的版本，若 wolfSentry 安装在非标准位置，请使用 `--with-wolfsentry=/the/install/path`。 测试客户端/服务器可通过命令行使用用户提供的 wolfSentry JSON 配置文件加载：`--wolfsentry-config `。

标签：ARM嵌入式, Bing搜索, DDS, FreeRTOS, Green Hills Integrity, Homebrew安装, IDPS, JSON配置, lwIP, Nucleus, NUTTX, syslog, VxWorks, wolfSSL, Zephyr, 主机过滤, 事件动作关联, 事务语义, 传输无关日志, 入侵检测与防御, 内存占用优化, 前缀查找, 动态配置, 原子策略切换, 实时系统, 客户端加密, 嵌入式系统, 嵌入式防火墙, 应用层过滤, 确定性吞吐, 线程安全, 网络包过滤, 裸机, 资源受限, 远程日志, 连接属性, 通配符查找