Add IPsec ESP transport support, packet print debug functions, and misc cleanup. by philljj · Pull Request #4 · wolfSSL/wolfip

philljj · 2025-08-21T17:04:52Z

Description

Add IPsec ESP transport mode support for tcp/udp:
- rfc4106 gcm, rfc4543 gmac
- rfc3602 aes-cbc
- rfc2451 des3
- hmac (rfc2403 md5, rfc2404 sha, rfc4868 sha256).
Add debug packet print functions for: eth, ip, udp, esp.
Added ip-xfrm scripts, README, and wireshark esp_sa.txt config to tools/ip-xfrm/.
Add DHCP macros DHCP_OPT_data_to_u32(), DHCP_OPT_u32_to_data() to trim duplicated code.
misc cleanup: overlong lines, trailing whitespace, gitignore, gcc15 build error (error: initializer-string for array), etc.

Testing

See tools/ip-xfrm/README.md:

https://github.com/philljj/wolfip/tree/small_cleanup/tools/ip-xfrm

packet print functions

Added packet print functions wolfIP_print_X() for eth, ip, udp, esp:

eth hdr:                                                                        
+---------------------------------------+                                       
| 6e:50:61:b4:a7:02 | 22:9e:b1:02:39:77 | (src, dst)                            
+---------------------------------------+                                       
| 0x0800 |   110 bytes data             | (eth type, payload)                   
+---------------------------------------+

ip hdr:                                                                         
+-----------------------------+                                                 
| 0x04 | 0x45 | 0x00 |     96 | (ipv, hdr_len, tos, ip_len)                     
+-----------------------------+                                                 
|    0xcccf    |    0x4000    | (id, flags_fo)                                  
+-----------------------------+                                                 
|   64  | 0x32 |    0x4586    | (ttl, proto, chksum)                            
+-----------------------------+                                                 
|                10.10.10.1   | (src)                                           
+-----------------------------+                                                 
|                10.10.10.2   | (dst)                                           
+-----------------------------+

esp packet: (76 bytes)                                                          
+------------------+                                                            
|  01  01  01  01  | (spi, 4 bytes)                                             
+------------------+                                                            
|  00  00  00  01  | (seq, 4 bytes)                                             
+------------------+                                                            
|  0a  47  f4  53  | (iv, 8 bytes)                                              
|  19  03  f9  9c  |                                                            
+------------------+                                                            
|  c8  3c  00  08  | (payload, 56 bytes)                                        
|  80  d1  24  26  |                                                            
|  00  00  00  00  |                                                            
|  a0  02  fa  f0  |                                                            
|  60  10  00  00  |                                                            
|  ..  ..  ..  ..  |                                                            
+------------------+                                                            
| 0102 | 02 | 0x06 | (padding last 2 bytes, pad len, nxt hdr)                   
+------------------+                                                            
|  c6  ca  b6  ac  | (icv, 16 bytes)                                            
|  17  f5  39  68  |                                                            
|  0d  0c  18  9f  |                                                            
|  5a  55  71  35  |                                                            
+------------------+

gasbytes · 2026-02-10T11:55:14Z

src/wolfesp.c

+    printf(esp_str_4hex " (%s, %d bytes)\n",
+           val[0], val[1], val[2], val[3], fld, val_len);
+    if (val_len > 4) {
+        for (size_t i = 4; i < val_len; i += 4) {


can val_len be a non-multiple of 4? because if so this part of code can result in a buffer over-read in a last iteration.

e.g.: val_len is not a multiple of 4, and is >= 5 and <= 16 the loop could go over I think, and read up to 3 bytes past val_len on the last iteration of the loop.

I think all these fields must be 4 byte multiples, but I'll double check

After looking more I think this should be ok. esp_print_field() is only used with SPI (4 byte), SEQ (4 byte), IV (8 or 16 byte), ICV (12 or 16 byte), and the payload.

The payload can be any length, but will be at least 8 bytes (UDP header), and logs a skip and breaks if (i + 4) > val_len.

This is what it looks like with UDP + rfc4543 (gmac only) sending "00" across UDP

udp hdr: +-------------------+ | 8 | 12345 | (src_port, dst_port) +-------------------+ | 11 | 0x6d50 | (len, chksum) +-------------------+ | 00. | (payload first 16 bytes) +-------------------+ ... esp packet: (48 bytes) +------------------+ | 08 08 08 08 | (spi, 4 bytes) +------------------+ | 00 00 00 28 | (seq, 4 bytes) +------------------+ | 98 fe d8 93 | (iv, 8 bytes) | d1 61 ee 57 | +------------------+ | 00 08 30 39 | (payload, 11 bytes) | 00 0b 6d 50 | | .. .. .. .. | +------------------+ | 0203 | 03 | 0x11 | (padding last 2 bytes, pad len, nxt hdr) +------------------+

and same for "000"

udp hdr: +-------------------+ | 8 | 12345 | (src_port, dst_port) +-------------------+ | 12 | 0x4744 | (len, chksum) +-------------------+ | 000. | (payload first 16 bytes) +-------------------+ ... esp packet: (48 bytes) +------------------+ ... +------------------+ | 00 08 30 39 | (payload, 12 bytes) | 00 0c 47 44 | | 30 30 30 0a | +------------------+ | 0102 | 02 | 0x11 | (padding last 2 bytes, pad len, nxt hdr) +------------------+

"0000"

+------------------+ | 00 08 30 39 | (payload, 13 bytes) | 00 0d 3d 1c | | 30 30 30 30 | | .. .. .. .. | +------------------+

"00000"

+------------------+ | 00 08 30 39 | (payload, 14 bytes) | 00 0e 17 10 | | 30 30 30 30 | | .. .. .. .. | +------------------+

etc

gasbytes · 2026-02-10T11:58:17Z

src/wolfesp.c

+    case ESP_ENC_CBC_AES:
+        block_len = AES_BLOCK_SIZE;
+        break;
+    #ifndef NO_DES3


I don't see any definition of a wolfIP_esp_sa_new_des3, is this expected if the user decides to use DES3? Since the enum exists.

I was lazy and hadn't added des3 support yet! Doing it now.

danielinux · 2026-02-11T14:27:22Z

src/test/esp/esp_common.c

@@ -0,0 +1,48 @@
+/* esp_common.c
+ *
+ * Copyright (C) 2024 wolfSSL Inc.


Copilot

Pull request overview

This PR adds IPsec ESP transport-mode support (with multiple crypto/auth algorithms), introduces packet debug-print helpers, and includes supporting test tooling/scripts plus some cleanup/build fixes across the repo.

Changes:

Add ESP transport encapsulation/decapsulation for TCP/UDP traffic, plus SA management APIs and tests.
Add packet print debug helpers for Ethernet/IP/UDP/ESP and wire them into RX/TX paths.
Add ip xfrm helper scripts/README/Wireshark SA config and miscellaneous cleanup (formatting, gitignore, GCC build fix).

Reviewed changes

Copilot reviewed 26 out of 29 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
`wolfip.h`	Splits long prototypes, adds `tsocket_cb` typedef, and includes wolfCrypt headers when ESP is enabled.
`wolfesp.h`	New public header for ESP constants, enums, SA struct, and SA management APIs.
`src/wolfip.c`	Integrates ESP wrap/unwrap into RX/TX paths, adds DHCP helper macros, formatting cleanup.
`src/wolfip_debug.c`	New debug packet print helpers for Ethernet/IP/UDP.
`src/wolfesp.c`	New ESP transport-mode implementation (SA pool, replay window, encrypt/decrypt, send wrapper).
`src/test/esp/test_esp.c`	New standalone ESP test (host + wolfIP threads) with multiple modes.
`src/test/esp/esp_server.c`	New TCP/UDP echo server for manual ESP testing.
`src/test/esp/esp_common.c`	Shared ESP test SA/key material matching the `ip xfrm` scripts.
`tools/ip-xfrm/README.md`	Documentation for configuring/testing ESP with `ip xfrm` and Wireshark.
`tools/ip-xfrm/rfc4106`	Script to configure RFC4106 AES-GCM transport-mode state/policy.
`tools/ip-xfrm/rfc4543`	Script to configure RFC4543 AES-GMAC transport-mode state/policy.
`tools/ip-xfrm/cbc_auth`	Script to configure AES-CBC + HMAC transport-mode state/policy.
`tools/ip-xfrm/des3_auth`	Script to configure 3DES-CBC + HMAC transport-mode state/policy.
`tools/ip-xfrm/show`	Script to display current xfrm policies/states.
`tools/ip-xfrm/delete_all`	Script to delete all xfrm policies/states.
`tools/ip-xfrm/esp_sa.txt`	Wireshark ESP SA config sample to decrypt captures.
`Makefile`	Adds esp build targets (`test-esp`, `esp-server`) and ESP-specific CFLAGS.
`.github/workflows/linux.yml`	Runs ESP tests in CI using `ip xfrm` scripts.
`src/port/posix/tap_linux.c`	Gates TAP buffer printing behind `DEBUG_TAP`.
`.gitignore`	Ignores `*.swp`.
`README.md`	Whitespace cleanup.
`core.md`	ASCII diagram whitespace cleanup.
`src/port/raspberry-pico-usb-server/README.md`	Whitespace cleanup.
`src/test/test_native_wolfssl.c`	Fixes string initializer issue by using explicit bytes.
`src/test/test_eventloop.c`	Fixes string initializer issue by using explicit bytes.
`src/test/test_dhcp_dns.c`	Fixes string initializer issue by using explicit bytes.
`src/test/ipfilter_logger.c`	Fixes string initializer issue by using explicit bytes.
`src/test/test_httpd.c`	Removes stray blank lines.
`src/test/tcp_echo.c`	Removes stray blank line.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/wolfesp.c

wolfesp.h

src/wolfesp.c

tools/ip-xfrm/rfc4106

tools/ip-xfrm/rfc4543

tools/ip-xfrm/README.md

src/wolfesp.c

wolfesp.h

philljj self-assigned this Aug 21, 2025

philljj force-pushed the small_cleanup branch from d4b4452 to 7832450 Compare August 24, 2025 05:43

philljj marked this pull request as draft August 25, 2025 02:12

philljj changed the title ~~cleanup: add packet print debug functions, and small cleanup.~~ cleanup: add packet print debug functions, ESP auth support, and small cleanup. Aug 25, 2025

philljj changed the title ~~cleanup: add packet print debug functions, ESP auth support, and small cleanup.~~ cleanup: add IPsec ESP transport support, packet print debug functions, and misc cleanup. Sep 21, 2025

philljj force-pushed the small_cleanup branch from bffa3c2 to 2746fc1 Compare October 29, 2025 20:42

philljj force-pushed the small_cleanup branch from 2746fc1 to 3d47370 Compare January 28, 2026 22:44

philljj marked this pull request as ready for review February 1, 2026 00:36

philljj force-pushed the small_cleanup branch 2 times, most recently from 562fc2e to 5b92271 Compare February 5, 2026 21:28

philljj requested a review from danielinux February 6, 2026 02:54

philljj changed the title ~~cleanup: add IPsec ESP transport support, packet print debug functions, and misc cleanup.~~ Add IPsec ESP transport support, packet print debug functions, and misc cleanup. Feb 6, 2026

philljj assigned danielinux Feb 6, 2026

philljj requested a review from gasbytes February 6, 2026 16:53

philljj added 2 commits February 9, 2026 15:49

IPsec transport support, and misc cleanup.

ebb5dd3

esp: esp echo server test.

c2c3854

philljj force-pushed the small_cleanup branch from 5eb24a1 to c2c3854 Compare February 9, 2026 22:45

cleanup.

ca25dc7

gasbytes requested changes Feb 10, 2026

View reviewed changes

philljj added 3 commits February 10, 2026 13:16

esp: des3 support.

5f53eb9

esp udp support, refactor debug functions.

93a506e

esp: support rfc4543 gmac.

55ce272

danielinux reviewed Feb 11, 2026

View reviewed changes

refactor debug to use LOG, ESP README, and general cleanup.

065633f

philljj requested review from danielinux and gasbytes February 12, 2026 06:21

esp: add key length checks.

dda5e3b

philljj requested a review from Copilot February 12, 2026 17:54

Copilot started reviewing on behalf of philljj February 12, 2026 17:55 View session

Copilot AI reviewed Feb 12, 2026

View reviewed changes

philljj added 2 commits February 12, 2026 15:51

esp: address copilot feedback part 1.

e309706

esp: address copilot feedback part 2, and refactor gen_iv.

3b62f95

philljj removed their assignment Feb 13, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add IPsec ESP transport support, packet print debug functions, and misc cleanup.#4

Add IPsec ESP transport support, packet print debug functions, and misc cleanup.#4
philljj wants to merge 10 commits intowolfSSL:masterfrom
philljj:small_cleanup

philljj commented Aug 21, 2025 •

edited

Loading

Uh oh!

gasbytes Feb 10, 2026

Uh oh!

philljj Feb 10, 2026

Uh oh!

philljj Feb 12, 2026

Uh oh!

gasbytes Feb 10, 2026

Uh oh!

philljj Feb 10, 2026

Uh oh!

danielinux Feb 11, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

philljj commented Aug 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Testing

packet print functions

Uh oh!

gasbytes Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

philljj Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

philljj Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

gasbytes Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

philljj Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

danielinux Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

philljj commented Aug 21, 2025 •

edited

Loading