wolfSentry is the wolfSSL embedded IDPS (Intrusion Detection and Prevention System). In simple terms, wolfSentry is an embedded firewall engine (both static and fully dynamic), with prefix-based and wildcard-capable lookup of known hosts/netblocks qualified by interface, address family, protocol, port, and other traffic parameters. Additionally, wolfSentry can be used as a dynamically configurable logic hub, arbitrarily associating user-defined events with user-defined actions, contextualized by connection attributes. The evolution of client-server relationships can thus be tracked in detail, freely passing traffic matching expected usage patterns, while efficiently rejecting abusive traffic.
wolfSentry is fully integrated with the lwIP stack, through a patchset in the
lwip/ subdirectory of the source tree, and has basic integration with the
wolfSSL library for application-level filtering of inbound and outbound
connections.
The wolfSentry engine is dynamically configurable programmatically through an API, or from a textual input file in JSON supplied to the engine, or dynamically and incrementally with JSON fragments, or any combination of these methods. Reconfiguration is protected by transactional semantics, and advanced internal locks on threaded targets assure seamless service availability with atomic policy transition. Callbacks allow for transport-agnostic remote logging, e.g. through MQTT, syslog, or DDS message buses.
wolfSentry is designed from the ground up to function well in resource-constrained, bare-metal, and realtime environments, with algorithms to stay within designated maximum memory footprints and maintain deterministic throughput. This allows full firewall and IDPS functionality on embedded targets such as FreeRTOS, Nucleus, NUTTX, Zephyr, VxWorks, and Green Hills Integrity, and on ARM and other common embedded CPUs and MCUs. wolfSentry with dynamic firewalling can add as little as 64k to the code footprint, and 32k to the volatile state footprint, and can fully leverage the existing logic and state of applications and sibling libraries.
Basic application integration on FreeRTOS-lwIP is documented, with usable code fragments, in doc/freertos-lwip-app.md.
JSON configuration is documented in detail by doc/json_configuration.md.
With doxygen installed, the HTML version of the full API reference manual can
be generated from the top of the wolfSentry source tree with make doc-html.
This, and the source code itself, are the recommended API references.
The PDF version of the API reference manual is pregenerated and included with source
distributions in the doc/ subdirectory at doc/wolfSentry_refman.pdf. The latest version is always
available on GitHub.
The latest changes and additions are noted in the ChangeLog.md at the top of the repository.
In its default build, wolfSentry depends on a POSIX runtime, specifically the heap allocator, clock_gettime, stdio, semaphore, pthreads, and string APIs. However, these dependencies can be avoided with various build-time options. The recipe
make STATIC=1 SINGLETHREADED=1 NO_STDIO=1 EXTRA_CFLAGS="-DWOLFSENTRY_NO_CLOCK_BUILTIN -DWOLFSENTRY_NO_MALLOC_BUILTIN"
builds a libwolfsentry.a that depends on only a handful of basic string
functions and the inet_ntop() library function (from POSIX.1-2001, and also
implemented by lwIP). Allocator and time callbacks must then be set in a
struct wolfsentry_host_platform_interface supplied to wolfsentry_init().
The wolfSentry Makefile depends on a modern (v4.0+) Gnu make. The library
itself can be built outside make, within another project/framework, by
creating a user settings macro file and passing its path to the compiler with
the WOLFSENTRY_USER_SETTINGS_FILE macro.
wolfSentry was written with portability in mind, with provisions for non-POSIX and C89 targets. For example, all its dependencies can be met with the FreeRTOS/newlib-nano/lwIP runtime. If you have difficulty building wolfSentry, please don’t hesitate to seek support through our support forums or contact us directly at support@wolfssl.com.
The current wolfSentry release can be downloaded from the wolfSSL website as a ZIP file, and developers can browse the release history and clone the wolfSentry Git repository for the latest pre-release updates.
There are several flags that can be passed to make to control the build
parameters. make will store them at build time in
wolfsentry/wolfsentry_options.h in the build tree. If you are not
using make, then the C macro WOLFSENTRY_USER_SETTINGS_FILE should be
defined to the path to a file containing settings, both when building wolfSentry
and when building the application.
The following feature control variables are recognized. True/false features
(LWIP, NO_STDIO, NO_JSON, etc.) are undefined by default, and activated
when defined. Macros can be supplied using the EXTRA_CFLAGS option, or by
placing them in a USER_SETTINGS_FILE. More detailed documentation for macros
is available in the reference manual "Startup/Configuration/Shutdown Subsystem"
topic.
make Option | Macro Option | Description |
|---|---|---|
SHELL | Supplies an explicit/alternative path to bash. | |
AWK | Supplies an explicit/alternative path to Gnu awk. | |
V | Verbose make output e.g. make V=1 -j test | |
USER_MAKE_CONF | User-defined make clauses to include at the top of the main Makefile e.g. make -j USER_MAKE_CONF=Makefile.settings | |
EXTRA_CFLAGS | Additional arguments to be passed verbatim to the compiler | |
EXTRA_LDFLAGS | Additional arguments to be passed verbatim to the linker | |
SRC_TOP | The source code top level directory (default pwd -P) | |
BUILD_TOP | Build with artifacts in an alternate location (outside or in a subdirectory of the source tree) e.g. make BUILD_TOP=./build -j test | |
DEBUG | Compiler debugging flag to use (default -ggdb) | |
OPTIM | The optimizer flag to use (default -O3) | |
HOST | The target host tuple, for cross-compilation (default unset, i.e. native targeting) | |
RUNTIME | The target runtime ecosystem -- default unset, FreeRTOS-lwIP, Linux-lwIP and ThreadX-NetXDuo are recognized | |
C_WARNFLAGS | The warning flags to use (overriding the generally applicable defaults) | |
STATIC | Build statically linked unit tests | |
STRIPPED | Strip binaries of debugging symbols | |
FUNCTION_SECTIONS | Cull any unused object code (with function granularity) to minimize total size. | |
BUILD_DYNAMIC | Build dynamically linked library | |
VERY_QUIET | Inhibit all non-error output during build | |
TAR | Path to GNU tar binary for make dist, should be set to gtar for macOS | |
VERSION | The version to package for make dist | |
LWIP | WOLFSENTRY_LWIP | True/false -- Activates appropriate build settings for lwIP |
NO_STDIO_STREAMS | WOLFSENTRY_NO_STDIO_STREAMS | Define to omit functionality that depends on stdio stream I/O |
WOLFSENTRY_NO_STDIO_H | Define to inhibit inclusion of stdio.h | |
NO_ADDR_BITMASK_MATCHING | WOLFSENTRY_NO_ADDR_BITMASK_MATCHING | Define to omit support for bitmask matching of addresses, i.e. support only prefix matching. |
NO_IPV6 | WOLFSENTRY_NO_IPV6 | Define to omit support for the IPv6 address family. |
NO_JSON | WOLFSENTRY_NO_JSON | Define to omit JSON configuration support |
NO_JSON_DOM | WOLFSENTRY_NO_JSON_DOM | Define to omit JSON DOM API |
CALL_TRACE | WOLFSENTRY_DEBUG_CALL_TRACE | Define to activate runtime call stack logging (profusely verbose) |
USER_SETTINGS_FILE | WOLFSENTRY_USER_SETTINGS_FILE | A substitute settings file, replacing autogenerated wolfsentry_settings.h |
SINGLETHREADED | WOLFSENTRY_SINGLETHREADED | Define to omit thread safety logic, and replace thread safety functions and macros with no-op macros. |
WOLFSENTRY_NO_PROTOCOL_NAMES | If defined, omit APIs for rendering error codes and source code files in human readable form. They will be rendered numerically. | |
WOLFSENTRY_NO_GETPROTOBY | Define to disable lookup and rendering of protocols and services by name. | |
WOLFSENTRY_NO_ERROR_STRINGS | If defined, omit APIs for rendering error codes and source code files in human readable form. They will be rendered numerically. | |
WOLFSENTRY_NO_MALLOC_BUILTINS | If defined, omit built-in heap allocator primitives; the wolfsentry_host_platform_interface supplied to wolfSentry APIs must include implementations of all functions in struct wolfsentry_allocator. | |
WOLFSENTRY_HAVE_NONGNU_ATOMICS | Define if gnu-style atomic intrinsics are not available. WOLFSENTRY_ATOMIC_*() macro definitions for intrinsics will need to be supplied in WOLFSENTRY_USER_SETTINGS_FILE (see wolfsentry_util.h). | |
WOLFSENTRY_NO_CLOCK_BUILTIN | If defined, omit built-in time primitives; the wolfsentry_host_platform_interface supplied to wolfSentry APIs must include implementations of all functions in struct wolfsentry_timecbs. | |
WOLFSENTRY_NO_SEM_BUILTIN | If defined, omit built-in semaphore primitives; the wolfsentry_host_platform_interface supplied to wolfSentry APIs must include implementations of all functions in struct wolfsentry_semcbs. | |
WOLFSENTRY_USE_NONPOSIX_SEMAPHORES | Define if POSIX semaphore API is not available. If no non-POSIX builtin implementation is present in wolfsentry_util.c, then #WOLFSENTRY_NO_SEM_BUILTIN must be set, and the wolfsentry_host_platform_interface supplied to wolfSentry APIs must include a full semaphore implementation (shim set) in its wolfsentry_semcbs slot. | |
WOLFSENTRY_SEMAPHORE_INCLUDE | Define to the path of a header file declaring a semaphore API. | |
WOLFSENTRY_USE_NONPOSIX_THREADS | Define if POSIX thread API is not available. WOLFSENTRY_THREAD_INCLUDE, WOLFSENTRY_THREAD_ID_T, and WOLFSENTRY_THREAD_GET_ID_HANDLER will need to be defined. | |
WOLFSENTRY_THREAD_INCLUDE | Define to the path of a header file declaring a threading API. | |
WOLFSENTRY_THREAD_ID_T | Define to the appropriate type analogous to POSIX pthread_t. | |
WOLFSENTRY_THREAD_GET_ID_HANDLER | Define to the name of a void function analogous to POSIX pthread_self, returning a value of type WOLFSENTRY_THREAD_ID_T. | |
FREERTOS | Build for FreeRTOS |
Building and testing libwolfsentry.a on Linux:
make -j test
Build verbosely:
make V=1 -j test
Build with artifacts in an alternate location (outside or in a subdirectory of the source tree):
make BUILD_TOP=./build -j test
Install from an alternate build location to a non-standard destination:
make BUILD_TOP=./build INSTALL_DIR=/usr INSTALL_LIBDIR=/usr/lib64 install
Build libwolfsentry.a and test it in various configurations:
make -j check
Build and test libwolfsentry.a without support for multithreading:
make -j SINGLETHREADED=1 test
Other available make flags are STATIC=1, STRIPPED=1, NO_JSON=1, and
NO_JSON_DOM=1, and the defaults values for DEBUG, OPTIM, and C_WARNFLAGS
can also be usefully overridden.
Build with a user-supplied makefile preamble to override defaults:
make -j USER_MAKE_CONF=Makefile.settings
(Makefile.settings can contain simple settings like OPTIM := -Os, or
elaborate makefile code including additional rules and dependency mechanisms.)
Build the smallest simplest possible library:
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"
Build and test with user settings:
make -j USER_SETTINGS_FILE=user_settings.h test
Build for FreeRTOS on ARM32, assuming FreeRTOS and lwIP source trees are located as shown:
make -j HOST=arm-none-eabi RUNTIME=FreeRTOS-lwIP FREERTOS_TOP=../third/FreeRTOSv202212.00 LWIP_TOP=../third/lwip EXTRA_CFLAGS=-mcpu=cortex-m7
In the wolfsentry/examples/ subdirectory are a set of example ports and
applications, including a demo pop-up notification system implementing a toy
TLS-enabled embedded web server, integrating with the Linux D-Bus facility.
More comprehensive examples of API usage are in
tests/unittests.c, particularly test_static_routes(), test_dynamic_rules(),
and test_json(), and the JSON configuration files at tests/test-config*.json.
In the wolfSSL repository, see code in
wolfssl/test.h gated on WOLFSSL_WOLFSENTRY_HOOKS, including
wolfsentry_store_endpoints(), wolfSentry_NetworkFilterCallback(),
wolfsentry_setup(), and tcp_connect_with_wolfSentry(). See also code in
examples/server/server.c and examples/client/client.c gated on
WOLFSSL_WOLFSENTRY_HOOKS. Configure wolfssl with --enable-wolfsentry to
build with wolfSentry integration, and use --with-wolfsentry=/the/install/path
if wolfSentry is installed in a nonstandard location. The wolfSSL test
client/server can be loaded with user-supplied wolfSentry JSON configurations
from the command line, using --wolfsentry-config <file>.