wolfIP

Description and project goals

wolfIP is a TCP/IP stack with no dynamic memory allocations, designed to be used in resource-constrained embedded systems.

wolfIP supports both endpoint-only mode and full multi-interface support with optional IP forwarding. By default, it operates as a network endpoint, but can be configured to forward traffic between multiple network interfaces.

Features supported

• BSD-like, non blocking socket API, with custom callbacks
• No dynamic memory allocation
  • Fixed number of concurrent sockets
  • Pre-allocated buffers for packet processing in static memory
• Multi-interface support
• Optional IPv4-forwarding
• Optional IPv4 UDP multicast with IGMPv3 ASM membership reports
• Reusable allocation-free TFTP module under src/tftp/
• Optional in-tree Wi-Fi supplicant (src/supplicant/) with WPA2-Personal (PSK 4-way), WPA2-Enterprise (EAP-TLS, optional PEAP/MSCHAPv2), and WPA3-Personal (SAE dragonfly with hunt-and-peck and RFC 9380 Hash-to-Element PWE, groups 19/20/21). See tools/hostapd/README.md for the build matrix and interop test harness.

Supported socket types

wolfIP exposes a BSD-like socket(2) API for IPv4 sockets:

Domain	Type	Protocol	Notes
AF_INET	SOCK_STREAM / IPSTACK_SOCK_STREAM	TCP	Connection-oriented TCP sockets
AF_INET	SOCK_DGRAM / IPSTACK_SOCK_DGRAM	UDP, or 0	UDP datagram sockets
AF_INET	SOCK_DGRAM / IPSTACK_SOCK_DGRAM	ICMP	ICMP datagram sockets, used for ping-style traffic
AF_INET	SOCK_RAW / IPSTACK_SOCK_RAW	IP protocol number	IPv4 raw sockets when WOLFIP_RAWSOCKETS is enabled
AF_PACKET	SOCK_RAW / IPSTACK_SOCK_RAW	Ethernet protocol number	Link-layer packet sockets when WOLFIP_PACKET_SOCKETS is enabled

Protocols and RFCs

Layer	Protocol	Features	RFC(s)
Data Link	Ethernet II	Frame encapsulation	IEEE 802.3
Data Link	ARP	Address resolution, request/reply	RFC 826
Network	IPv4	Datagram delivery, TTL handling	RFC 791
Network	IPv4 Forwarding	Multi-interface routing (optional)	RFC 1812
Network	ICMP	Echo request/reply, TTL exceeded	RFC 792
Network	IGMPv3	ASM membership reports for IPv4 multicast (optional)	RFC 3376
Network	IPsec	ESP Transport mode	RFC 4303
Transport	UDP	Unicast datagrams, checksum, optional IPv4 multicast	RFC 768
Transport	TCP	Connection management, reliable delivery	RFC 793, RFC 9293
Transport	TCP	Maximum Segment Size negotiation	RFC 793
Transport	TCP	TCP Timestamps, RTT measurement, PAWS, Window Scaling	RFC 7323
Transport	TCP	Retransmission timeout (RTO) computation	RFC 6298, RFC 5681
Transport	TCP	TCP SACK	RFC 2018, RFC 2883, RFC 6675
Transport	TCP	Congestion Control: Slow start, congestion avoidance	RFC 5681
Transport	TCP	Fast Retransmit, triple duplicate ACK detection	RFC 5681
Application	DHCP	Client only (DORA)	RFC 2131
Application	DNS	A and PTR record queries (client)	RFC 1035
Application	HTTP/HTTPS	Server with wolfSSL TLS support	RFC 9110
Application	TFTP	Client/server octet-mode transfers with callback-driven storage and verification	RFC 1350, RFC 2347, RFC 2348, RFC 2349, RFC 7440
VPN	wolfGuard	FIPS-compliant WireGuard (P-256, AES-256-GCM, SHA-256)	Wolfguard

wolfGuard (FIPS WireGuard)

wolfIP includes a native wolfGuard driver, which is a FIPS-compliant implementation of the WireGuard VPN protocol that operates entirely within the wolfIP stack. wolfGuard uses wolfSSL/wolfCrypt FIPS-certified cryptographic primitives:

WireGuard Primitive	wolfGuard FIPS Replacement
Curve25519	ECDH with SECP256R1 (P-256)
ChaCha20-Poly1305	AES-256-GCM
BLAKE2s	SHA-256
BLAKE2s-HMAC	HMAC-SHA-256

wolfGuard is NOT interoperable with standard WireGuard peers. It interoperates only with other wolfGuard instances (including the wolfGuard kernel module).

Building with wolfGuard

wolfGuard requires wolfSSL with --enable-wolfguard:

make unit-wolfguard # unit tests
make test-wolfguard-loopback # loopback integration tests
make test-wolfguard-interop # interop test binary (used by the script below)

Interop testing against the kernel wolfGuard module

The interop test validates bidirectional tunnel connectivity between wolfIP and the Linux kernel wolfGuard module. It tests both handshake directions (wolfIP as initiator and as responder) and verifies encrypted data flows end-to-end.

# Requires root, kernel headers, and network access (to clone wolfSSL/wolfGuard)
sudo ./tools/scripts/test-interop-wolfguard.sh

The script builds wolfSSL and the wolfGuard kernel module from source, loads them, generates fresh P-256 keys, and runs a two-phase interop test:

1. wolfIP initiates — wolfIP creates a handshake, sends a UDP probe through the tunnel, and verifies the echo reply.
2. Kernel initiates — the kernel creates a fresh handshake to wolfIP, sends data through the tunnel, and wolfIP verifies receipt.

Compile-time configuration

/* config.h */#defineWOLFGUARD 1 /* Enable wolfGuard support */#defineWOLFGUARD_MAX_PEERS 8 /* Max peers per device */#defineWOLFGUARD_MAX_ALLOWED_IPS 32 /* Max allowed-IP entries */#defineWOLFGUARD_STAGED_PACKETS 16 /* Packets queued during handshake */#defineWOLFGUARD_COUNTER_WINDOW 1024 /* Replay window size (bits) */

Functional tests with LD_PRELOAD

The POSIX shim builds libwolfip.so, which can be injected in front of host tools so that calls to socket(2) and friends are redirected to the wolfIP stack and the TAP device (wtcp0). After running make:

sudo LD_PRELOAD=$PWD/libwolfip.so nc 10.10.10.2 80

The example above mirrors the existing nc-driven demos: any TCP sockets opened by the intercepted process are serviced by wolfIP instead of the host kernel.

Ping over the TAP device

ICMP datagram sockets can be validated the same way. With the TAP interface created automatically by the shim and the host endpoint configured in config.h (HOST_STACK_IP defaults to 10.10.10.1), run:

sudo LD_PRELOAD=$PWD/libwolfip.so ping -I wtcp0 -c5 10.10.10.1

The -I wtcp0 flag pins the test to the injected interface and -c5 generates five echo requests. Successful replies confirm the ICMP datagram socket support end-to-end through the tap device.

Optional UDP Multicast

IPv4 UDP multicast is compiled out by default. Define IP_MULTICAST to enable BSD-style multicast socket options and IGMPv3 ASM membership reports:

• WOLFIP_IP_ADD_MEMBERSHIP
• WOLFIP_IP_DROP_MEMBERSHIP
• WOLFIP_IP_MULTICAST_IF
• WOLFIP_IP_MULTICAST_TTL
• WOLFIP_IP_MULTICAST_LOOP

The implementation supports any-source multicast joins and leaves. Source filter APIs such as MCAST_JOIN_SOURCE_GROUP are not implemented.

make unit-multicast
./build/test/unit
make build/test-multicast-interop
sudo ./build/test-multicast-interop

The multicast interop test creates a Linux TAP interface (wmcast0) and validates both directions: Linux sending to a wolfIP multicast receiver, and wolfIP sending to a Linux multicast receiver.

FreeRTOS Port

wolfIP now includes a dedicated FreeRTOS wrapper port at:

• src/port/freeRTOS/bsd_socket.c
• src/port/freeRTOS/bsd_socket.h

This port follows the same model as the POSIX wrapper:

• One background task loops on wolfIP_poll()
• Socket wrappers serialize stack access with a mutex
• Blocking operations wait on callback-driven wakeups (instead of busy polling)

Documentation

• API reference: core stack, socket, and protocol-client APIs
• Porting guide: designing device drivers (with and without DMA) and porting wolfIP to a new operating system

Module how-tos:

• TLS over wolfIP: running wolfSSL/TLS on wolfIP sockets, the I/O-callback bridge, and non-blocking handshakes

• HTTP/HTTPS server: the src/http/ server module, handler registration, and enabling HTTPS

• IPsec ESP: securing traffic with ESP transport mode, SA setup, and Linux ip xfrm interop

• wolfGuard (FIPS WireGuard): the in-stack WireGuard tunnel, peer/key setup, and kernel interop

• TFTP: the TFTP client/server module, callback wiring, and the firmware-download pattern

• DHCP & DNS clients: acquiring a lease, resolving names, and the poll-loop lifecycle

• Advanced IPv4: multicast/IGMP, IPv4 forwarding, multiple interfaces, and loopback

• Migrating from lwIP: mapping lwIP concepts and APIs onto wolfIP

Source Layout

• src/wolfip.c: core TCP/IP stack
• src/http/: optional HTTP/HTTPS server pieces
• src/tftp/: reusable TFTP module sources, auto-registered by the top-level Makefile and CMakeLists.txt when present
• src/port/: platform and OS adaptation layers
• src/test/: integration and unit tests

Copyright and License

wolfIP is licensed under the GPLv3 license. See the LICENSE file for details. Copyright (c) 2025 wolfSSL Inc.