wolfSSL · embhorn · Jan 20, 2026 · Jan 20, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,141 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+wolfMQTT is an MQTT client library written in C for embedded systems. It supports MQTT v3.1.1 and v5.0 protocols, MQTT-SN for sensor networks, and integrates with wolfSSL for TLS support.
+
+## Build Commands
+
+### Standard Build (Linux/macOS)
+```bash
+./autogen.sh          # Required if cloned from GitHub
+./configure           # See --help for options
+make
+sudo make install
+```
+
+### Run Tests
+```bash
+make check            # Runs all tests with local mosquitto broker
+```
+
+### Individual Test Scripts
+```bash
+./scripts/client.test       # Main MQTT client tests (QoS 0-2, TLS)
+./scripts/nbclient.test     # Non-blocking client tests
+./scripts/multithread.test  # Multi-threading tests
+./scripts/stress.test       # Stress testing (requires --enable-stress)
+```
+
+### CMake Build
+```bash
+mkdir build && cd build
+cmake .. -DWITH_WOLFSSL=/path/to/wolfssl/install/   # Use installed wolfSSL
+# OR
+cmake .. -DWITH_WOLFSSL_TREE=/path/to/wolfssl/      # Use source tree
+cmake --build .
+```
+
+### Common Configure Options
+```bash
+--enable-tls        # TLS support (default: enabled)
+--enable-v5         # MQTT v5.0 support
+--enable-sn         # MQTT-SN (Sensor Network) support
+--enable-nonblock   # Non-blocking I/O support
+--enable-mt         # Multi-threading support
+--enable-websocket  # WebSocket support (requires libwebsockets)
+--enable-curl       # libcurl backend support
+--enable-all        # Enable all features
+--enable-debug      # Debug mode (--enable-debug=verbose for extra logging)
+--enable-stress     # Stress testing (e.g., --enable-stress=t7,p8 for 7 threads, 8 pubs)
+--disable-tls       # Disable TLS for testing without wolfSSL
+```
+
+### Running Examples
+```bash
+./examples/mqttclient/mqttclient -?    # Show help with available options
+./examples/mqttclient/mqttclient -h localhost -p 1883   # Connect to local broker
+./examples/mqttclient/mqttclient -h localhost -t -p 8883  # TLS connection
+```
+
+## Architecture
+
+### Core Library Components (in /src/)
+
+1. **mqtt_client.c** - Top-level client API
+   - `MqttClient_Init()`, `MqttClient_Connect()`, `MqttClient_Publish()`
+   - `MqttClient_Subscribe()`, `MqttClient_WaitMessage()`, `MqttClient_Disconnect()`
+
+2. **mqtt_packet.c** - MQTT packet encoding/decoding
+   - Structures: `MqttConnect`, `MqttPublish`/`MqttMessage`, `MqttSubscribe`
+
+3. **mqtt_socket.c** - Transport layer with TLS integration
+   - Network callbacks via `MqttNet` structure
+
+4. **mqtt_sn_client.c / mqtt_sn_packet.c** - MQTT-SN protocol support
+
+### Public Headers (in /wolfmqtt/)
+
+- `mqtt_types.h` - Type definitions, error codes, platform abstractions
+- `mqtt_client.h` - Client API declarations
+- `mqtt_packet.h` - Packet structures
+- `mqtt_socket.h` - Network interface
+- `options.h` - Generated build configuration
+
+### Examples (in /examples/)
+
+- `mqttclient/` - Full-featured reference client (best starting template)
+- `mqttsimple/` - Standalone BSD sockets client
+- `nbclient/` - Non-blocking I/O example
+- `multithread/` - Multi-threaded publish/subscribe
+- `firmware/` - Firmware update (fwpush/fwclient)
+- `aws/`, `azure/`, `wiot/` - Cloud platform integrations
+- `sn-client/` - MQTT-SN client
+- `websocket/` - WebSocket client
+- `pub-sub/` - Simple mqtt-pub and mqtt-sub utilities
+
+### Shared Example Code
+
+- `examples/mqttnet.c` - Network callback reference implementation
+- `examples/mqttport.c` - Platform abstraction layer
+- `examples/mqttexample.c` - Common example utilities
+
+## Key Compile Macros
+
+```c
+ENABLE_MQTT_TLS           // TLS support
+WOLFMQTT_V5               // MQTT v5.0
+WOLFMQTT_SN               // MQTT-SN protocol
+WOLFMQTT_NONBLOCK         // Non-blocking I/O
+WOLFMQTT_MULTITHREAD      // Multi-threading
+WOLFMQTT_DYN_PROP         // Dynamic property allocation (v5.0)
+DEBUG_WOLFMQTT            // Debug mode
+```
+
+## Testing
+
+Tests require a local mosquitto broker. The CI uses `bubblewrap` for network isolation.
+
+To skip external broker tests:
+```bash
+WOLFMQTT_NO_EXTERNAL_BROKER_TESTS=1 ./configure --enable-all
+make check
+```
+
+Test certificates are in `/certs/` (RSA and ECC variants).
+Broker test config: `/scripts/broker_test/mosquitto.conf`
+
+## Code Style
+
+Uses `.clang-format` with LLVM base style:
+- Tab indentation (4-space tabs)
+- K&R inspired style
+
+## Dependencies
+
+- **wolfSSL** - Required for TLS support
+- **libwebsockets** - Optional, for WebSocket support
+- **libcurl** - Optional, for curl backend
+- **mosquitto** - For running tests
diff --git a/certs/client-cert.pem b/certs/client-cert.pem
@@ -2,16 +2,16 @@ Certificate:
     Data:
         Version: 3 (0x2)
         Serial Number:
-            73:fb:54:d6:03:7d:4c:07:84:e2:00:11:8c:dd:90:dc:48:8d:ea:53
+            6b:61:49:45:ff:4a:d1:54:16:b4:35:37:c4:98:5d:a9:f6:67:60:91
         Signature Algorithm: sha256WithRSAEncryption
-        Issuer: C = US, ST = Montana, L = Bozeman, O = wolfSSL_2048, OU = Programming-2048, CN = www.wolfssl.com, emailAddress = info@wolfssl.com
+        Issuer: C=US, ST=Montana, L=Bozeman, O=wolfSSL_2048, OU=Programming-2048, CN=www.wolfssl.com, emailAddress=info@wolfssl.com
         Validity
-            Not Before: Dec 16 21:17:49 2022 GMT
-            Not After : Sep 11 21:17:49 2025 GMT
-        Subject: C = US, ST = Montana, L = Bozeman, O = wolfSSL_2048, OU = Programming-2048, CN = www.wolfssl.com, emailAddress = info@wolfssl.com
+            Not Before: Nov 13 20:41:10 2025 GMT
+            Not After : Aug  9 20:41:10 2028 GMT
+        Subject: C=US, ST=Montana, L=Bozeman, O=wolfSSL_2048, OU=Programming-2048, CN=www.wolfssl.com, emailAddress=info@wolfssl.com
         Subject Public Key Info:
             Public Key Algorithm: rsaEncryption
-                RSA Public-Key: (2048 bit)
+                Public-Key: (2048 bit)
                 Modulus:
                     00:c3:03:d1:2b:fe:39:a4:32:45:3b:53:c8:84:2b:
                     2a:7c:74:9a:bd:aa:2a:52:07:47:d6:a6:36:b2:07:
@@ -38,37 +38,37 @@ Certificate:
             X509v3 Authority Key Identifier: 
                 keyid:33:D8:45:66:D7:68:87:18:7E:54:0D:70:27:91:C7:26:D7:85:65:C0
                 DirName:/C=US/ST=Montana/L=Bozeman/O=wolfSSL_2048/OU=Programming-2048/CN=www.wolfssl.com/emailAddress=info@wolfssl.com
-                serial:73:FB:54:D6:03:7D:4C:07:84:E2:00:11:8C:DD:90:DC:48:8D:EA:53
-
+                serial:6B:61:49:45:FF:4A:D1:54:16:B4:35:37:C4:98:5D:A9:F6:67:60:91
             X509v3 Basic Constraints: 
                 CA:TRUE
             X509v3 Subject Alternative Name: 
                 DNS:example.com, IP Address:127.0.0.1
             X509v3 Extended Key Usage: 
                 TLS Web Server Authentication, TLS Web Client Authentication
     Signature Algorithm: sha256WithRSAEncryption
-         36:cb:bc:c5:52:9a:66:cd:91:4d:8f:27:9f:b3:64:80:0e:64:
-         b4:cb:1a:cd:75:9e:82:7c:55:67:d8:9f:90:a3:34:96:99:43:
-         f7:49:53:a2:58:85:a0:b3:83:4f:af:b8:15:8a:88:1e:f3:60:
-         f4:7c:94:b5:58:68:f1:2a:13:80:34:c2:6f:a5:f8:7e:76:16:
-         81:4f:36:8b:c3:59:bd:51:dd:60:87:d7:1d:96:44:69:07:3c:
-         8f:28:56:b1:11:5c:4e:81:3f:57:25:fd:65:dd:07:cf:17:0a:
-         01:7e:4e:3f:8e:73:db:fe:f4:f2:c5:ff:a3:76:a8:74:46:2e:
-         47:0d:b0:ed:0a:c0:c5:0a:65:d3:dc:62:b2:e0:1e:8e:bd:f3:
-         bd:af:af:66:84:36:92:e2:3b:80:d0:57:a6:41:a3:62:d1:a6:
-         6d:14:6c:cd:82:b1:c1:c1:35:55:ae:59:49:a8:26:52:bd:ef:
-         1b:2c:1f:9d:39:04:d2:82:a0:6b:39:71:59:33:82:ba:55:6c:
-         97:f2:1b:5b:e0:4d:e2:cf:89:e7:26:b8:2c:6c:9f:83:d6:ed:
-         4e:2f:75:a9:30:4e:01:95:0d:4f:83:5e:c8:af:7f:67:ea:53:
-         bf:ca:9b:1f:d4:ff:36:97:02:71:8e:33:de:e2:58:27:aa:70:
-         0c:5b:de:0e
+    Signature Value:
+        85:8e:aa:c0:bd:0a:a7:a9:d2:33:ec:39:42:e8:3a:ca:ca:c0:
+        32:37:50:5f:ee:5c:5b:16:01:35:3e:e6:ad:53:46:f5:5e:1c:
+        ff:ce:5f:03:89:08:14:ee:c7:d9:1e:4b:85:42:0a:0d:c1:96:
+        61:4b:66:11:e1:a1:fd:6b:80:ee:cf:cd:02:96:d4:61:9f:54:
+        79:0e:07:4e:c5:5f:e2:64:dc:8f:fd:53:3a:4b:05:0d:9c:cb:
+        f8:02:c8:82:12:65:c8:62:f0:e7:27:cd:58:38:87:19:3a:cf:
+        a8:5e:f3:27:1b:e7:83:68:ad:36:71:42:20:70:bd:7e:84:a7:
+        56:d8:49:9f:8f:1e:3a:ad:86:0d:da:fb:f5:0c:0f:01:18:27:
+        6e:fb:6b:be:6b:78:f5:a0:c0:6d:5f:0a:56:d5:13:49:a4:4e:
+        6a:c3:0a:6e:89:f2:29:3a:30:49:be:99:84:a4:85:33:5f:8e:
+        41:f4:c3:4b:eb:d5:01:2e:f8:0e:f3:01:49:d4:45:08:f3:fd:
+        25:6a:1d:65:ac:9c:c8:46:2a:b9:1c:c6:a7:7b:82:60:31:bb:
+        0f:3d:87:8e:12:3d:c3:47:0b:bd:2d:97:22:b5:83:ec:9a:0f:
+        f3:29:ea:c9:ea:59:1d:75:2d:81:48:0f:e2:a6:69:e3:9c:03:
+        92:a2:0f:2d
 -----BEGIN CERTIFICATE-----
-MIIFHTCCBAWgAwIBAgIUc/tU1gN9TAeE4gARjN2Q3EiN6lMwDQYJKoZIhvcNAQEL
+MIIFHTCCBAWgAwIBAgIUa2FJRf9K0VQWtDU3xJhdqfZnYJEwDQYJKoZIhvcNAQEL
 BQAwgZ4xCzAJBgNVBAYTAlVTMRAwDgYDVQQIDAdNb250YW5hMRAwDgYDVQQHDAdC
 b3plbWFuMRUwEwYDVQQKDAx3b2xmU1NMXzIwNDgxGTAXBgNVBAsMEFByb2dyYW1t
 aW5nLTIwNDgxGDAWBgNVBAMMD3d3dy53b2xmc3NsLmNvbTEfMB0GCSqGSIb3DQEJ
-ARYQaW5mb0B3b2xmc3NsLmNvbTAeFw0yMjEyMTYyMTE3NDlaFw0yNTA5MTEyMTE3
-NDlaMIGeMQswCQYDVQQGEwJVUzEQMA4GA1UECAwHTW9udGFuYTEQMA4GA1UEBwwH
+ARYQaW5mb0B3b2xmc3NsLmNvbTAeFw0yNTExMTMyMDQxMTBaFw0yODA4MDkyMDQx
+MTBaMIGeMQswCQYDVQQGEwJVUzEQMA4GA1UECAwHTW9udGFuYTEQMA4GA1UEBwwH
 Qm96ZW1hbjEVMBMGA1UECgwMd29sZlNTTF8yMDQ4MRkwFwYDVQQLDBBQcm9ncmFt
 bWluZy0yMDQ4MRgwFgYDVQQDDA93d3cud29sZnNzbC5jb20xHzAdBgkqhkiG9w0B
 CQEWEGluZm9Ad29sZnNzbC5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEK
@@ -82,13 +82,13 @@ Ztdohxh+VA1wJ5HHJteFZcAwgd4GA1UdIwSB1jCB04AUM9hFZtdohxh+VA1wJ5HH
 JteFZcChgaSkgaEwgZ4xCzAJBgNVBAYTAlVTMRAwDgYDVQQIDAdNb250YW5hMRAw
 DgYDVQQHDAdCb3plbWFuMRUwEwYDVQQKDAx3b2xmU1NMXzIwNDgxGTAXBgNVBAsM
 EFByb2dyYW1taW5nLTIwNDgxGDAWBgNVBAMMD3d3dy53b2xmc3NsLmNvbTEfMB0G
-CSqGSIb3DQEJARYQaW5mb0B3b2xmc3NsLmNvbYIUc/tU1gN9TAeE4gARjN2Q3EiN
-6lMwDAYDVR0TBAUwAwEB/zAcBgNVHREEFTATggtleGFtcGxlLmNvbYcEfwAAATAd
+CSqGSIb3DQEJARYQaW5mb0B3b2xmc3NsLmNvbYIUa2FJRf9K0VQWtDU3xJhdqfZn
+YJEwDAYDVR0TBAUwAwEB/zAcBgNVHREEFTATggtleGFtcGxlLmNvbYcEfwAAATAd
 BgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwDQYJKoZIhvcNAQELBQADggEB
-ADbLvMVSmmbNkU2PJ5+zZIAOZLTLGs11noJ8VWfYn5CjNJaZQ/dJU6JYhaCzg0+v
-uBWKiB7zYPR8lLVYaPEqE4A0wm+l+H52FoFPNovDWb1R3WCH1x2WRGkHPI8oVrER
-XE6BP1cl/WXdB88XCgF+Tj+Oc9v+9PLF/6N2qHRGLkcNsO0KwMUKZdPcYrLgHo69
-872vr2aENpLiO4DQV6ZBo2LRpm0UbM2CscHBNVWuWUmoJlK97xssH505BNKCoGs5
-cVkzgrpVbJfyG1vgTeLPiecmuCxsn4PW7U4vdakwTgGVDU+DXsivf2fqU7/Kmx/U
-/zaXAnGOM97iWCeqcAxb3g4=
+AIWOqsC9Cqep0jPsOULoOsrKwDI3UF/uXFsWATU+5q1TRvVeHP/OXwOJCBTux9ke
+S4VCCg3BlmFLZhHhof1rgO7PzQKW1GGfVHkOB07FX+Jk3I/9UzpLBQ2cy/gCyIIS
+Zchi8OcnzVg4hxk6z6he8ycb54NorTZxQiBwvX6Ep1bYSZ+PHjqthg3a+/UMDwEY
+J277a75rePWgwG1fClbVE0mkTmrDCm6J8ik6MEm+mYSkhTNfjkH0w0vr1QEu+A7z
+AUnURQjz/SVqHWWsnMhGKrkcxqd7gmAxuw89h44SPcNHC70tlyK1g+yaD/Mp6snq
+WR11LYFID+KmaeOcA5KiDy0=
 -----END CERTIFICATE-----
diff --git a/certs/client-ecc-cert.pem b/certs/client-ecc-cert.pem
@@ -2,13 +2,13 @@ Certificate:
     Data:
         Version: 3 (0x2)
         Serial Number:
-            59:e6:5a:21:e0:c4:3f:67:06:9b:21:43:3e:76:ca:f0:3f:68:5b:53
+            02:f4:19:c0:e7:0a:07:8d:10:b6:e1:74:6f:e7:ce:da:e6:35:56:06
         Signature Algorithm: ecdsa-with-SHA256
-        Issuer: C = US, ST = Oregon, L = Salem, O = Client ECC, OU = Fast, CN = www.wolfssl.com, emailAddress = info@wolfssl.com
+        Issuer: C=US, ST=Oregon, L=Salem, O=Client ECC, OU=Fast, CN=www.wolfssl.com, emailAddress=info@wolfssl.com
         Validity
-            Not Before: Dec 16 21:17:49 2022 GMT
-            Not After : Sep 11 21:17:49 2025 GMT
-        Subject: C = US, ST = Oregon, L = Salem, O = Client ECC, OU = Fast, CN = www.wolfssl.com, emailAddress = info@wolfssl.com
+            Not Before: Nov 13 20:41:15 2025 GMT
+            Not After : Aug  9 20:41:15 2028 GMT
+        Subject: C=US, ST=Oregon, L=Salem, O=Client ECC, OU=Fast, CN=www.wolfssl.com, emailAddress=info@wolfssl.com
         Subject Public Key Info:
             Public Key Algorithm: id-ecPublicKey
                 Public-Key: (256 bit)
@@ -26,25 +26,25 @@ Certificate:
             X509v3 Authority Key Identifier: 
                 keyid:EB:D4:4B:59:6B:95:61:3F:51:57:B6:04:4D:89:41:88:44:5C:AB:F2
                 DirName:/C=US/ST=Oregon/L=Salem/O=Client ECC/OU=Fast/CN=www.wolfssl.com/emailAddress=info@wolfssl.com
-                serial:59:E6:5A:21:E0:C4:3F:67:06:9B:21:43:3E:76:CA:F0:3F:68:5B:53
-
+                serial:02:F4:19:C0:E7:0A:07:8D:10:B6:E1:74:6F:E7:CE:DA:E6:35:56:06
             X509v3 Basic Constraints: 
                 CA:TRUE
             X509v3 Subject Alternative Name: 
                 DNS:example.com, IP Address:127.0.0.1
             X509v3 Extended Key Usage: 
                 TLS Web Server Authentication, TLS Web Client Authentication
     Signature Algorithm: ecdsa-with-SHA256
-         30:45:02:20:70:f8:0e:6e:91:c9:09:77:25:8c:ba:99:6d:54:
-         2d:a8:52:87:17:51:24:8b:13:92:89:7d:c9:ba:b4:43:2e:48:
-         02:21:00:ab:41:13:3a:d5:eb:68:66:36:56:7c:75:5d:37:e3:
-         f6:27:7f:54:d5:42:80:29:db:e5:9b:16:8a:d3:c2:ad:d6
+    Signature Value:
+        30:44:02:20:13:c9:89:7e:31:21:9a:7b:1e:6c:cd:69:35:d1:
+        99:9e:65:a4:9c:07:35:b0:fb:56:e9:3c:17:e6:4b:a3:76:d9:
+        02:20:4a:e1:3e:e3:02:4c:f0:da:dd:c2:ac:7a:d1:41:0c:ef:
+        e6:aa:a3:88:7b:cb:0b:13:df:fd:b5:7f:ff:5a:90:41
 -----BEGIN CERTIFICATE-----
-MIIDXjCCAwSgAwIBAgIUWeZaIeDEP2cGmyFDPnbK8D9oW1MwCgYIKoZIzj0EAwIw
+MIIDXTCCAwSgAwIBAgIUAvQZwOcKB40QtuF0b+fO2uY1VgYwCgYIKoZIzj0EAwIw
 gY0xCzAJBgNVBAYTAlVTMQ8wDQYDVQQIDAZPcmVnb24xDjAMBgNVBAcMBVNhbGVt
 MRMwEQYDVQQKDApDbGllbnQgRUNDMQ0wCwYDVQQLDARGYXN0MRgwFgYDVQQDDA93
 d3cud29sZnNzbC5jb20xHzAdBgkqhkiG9w0BCQEWEGluZm9Ad29sZnNzbC5jb20w
-HhcNMjIxMjE2MjExNzQ5WhcNMjUwOTExMjExNzQ5WjCBjTELMAkGA1UEBhMCVVMx
+HhcNMjUxMTEzMjA0MTE1WhcNMjgwODA5MjA0MTE1WjCBjTELMAkGA1UEBhMCVVMx
 DzANBgNVBAgMBk9yZWdvbjEOMAwGA1UEBwwFU2FsZW0xEzARBgNVBAoMCkNsaWVu
 dCBFQ0MxDTALBgNVBAsMBEZhc3QxGDAWBgNVBAMMD3d3dy53b2xmc3NsLmNvbTEf
 MB0GCSqGSIb3DQEJARYQaW5mb0B3b2xmc3NsLmNvbTBZMBMGByqGSM49AgEGCCqG
@@ -54,9 +54,9 @@ WWuVYT9RV7YETYlBiERcq/Iwgc0GA1UdIwSBxTCBwoAU69RLWWuVYT9RV7YETYlB
 iERcq/KhgZOkgZAwgY0xCzAJBgNVBAYTAlVTMQ8wDQYDVQQIDAZPcmVnb24xDjAM
 BgNVBAcMBVNhbGVtMRMwEQYDVQQKDApDbGllbnQgRUNDMQ0wCwYDVQQLDARGYXN0
 MRgwFgYDVQQDDA93d3cud29sZnNzbC5jb20xHzAdBgkqhkiG9w0BCQEWEGluZm9A
-d29sZnNzbC5jb22CFFnmWiHgxD9nBpshQz52yvA/aFtTMAwGA1UdEwQFMAMBAf8w
+d29sZnNzbC5jb22CFAL0GcDnCgeNELbhdG/nztrmNVYGMAwGA1UdEwQFMAMBAf8w
 HAYDVR0RBBUwE4ILZXhhbXBsZS5jb22HBH8AAAEwHQYDVR0lBBYwFAYIKwYBBQUH
-AwEGCCsGAQUFBwMCMAoGCCqGSM49BAMCA0gAMEUCIHD4Dm6RyQl3JYy6mW1ULahS
-hxdRJIsTkol9ybq0Qy5IAiEAq0ETOtXraGY2Vnx1XTfj9id/VNVCgCnb5ZsWitPC
-rdY=
+AwEGCCsGAQUFBwMCMAoGCCqGSM49BAMCA0cAMEQCIBPJiX4xIZp7HmzNaTXRmZ5l
+pJwHNbD7Vuk8F+ZLo3bZAiBK4T7jAkzw2t3CrHrRQQzv5qqjiHvLCxPf/bV//1qQ
+QQ==
 -----END CERTIFICATE-----