TLS: IDF certificate bundle by default on WebSocket + MQTT transports (v0.5.1-dev) - #22
Merged
Merged
Conversation
…(v0.5.1-dev) WebSocketTransport::Config and MqttTransport::Config gain use_cert_bundle (default true), wiring esp_crt_bundle_attach into the IDF client — matching HttpTransport's existing default; the bundle is already always linked since 0.5.0. Precedence: cert_pem pin > bundle > WS-only embedded GTS Root R4 (use_default_certs, now the no-bundle fallback) > nothing. Consumers that pinned a root only to get TLS working can drop the pin and stop tracking CA rotations. useDefaultCerts() now expresses explicit intent (disables the bundle, selects the embedded root). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…undle_attach The bundled esp_websocket_client inside IDF 4.x Arduino cores predates the crt_bundle_attach config hook. Detect the member at compile time (expression SFINAE); when absent, fall back to the embedded GTS Root R4 — the pre-0.5.1 behavior — instead of failing to compile. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ference The v0.5.1-dev TLS change adds `use_cert_bundle` to the WebSocket and MQTT Config structs and reorders TLS precedence, but docs/api.md still described the old cert surface. Update both Config tables (new field + corrected `use_default_certs` meaning as the bundle-disabled fallback) and spell out the precedence chain. Also fill a pre-existing gap: HttpTransport (shipped 0.5.0) had no api.md section at all. Add a full reference — Config, methods, Response, and FetchOptions — plus the missing header-include row and a HttpTransport column in the SendOptions table. Bump the stale "0.4.0 API" header to 0.5.x. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Extends the cert-bundle default that
HttpTransportshipped with in 0.5.0 to the other two TLS transports, so consumers no longer need to pin (and track rotations of) a root CA just to get TLS working.Changes
use_cert_bundle(defaulttrue) onWebSocketTransport::ConfigandMqttTransport::Config, wiringesp_crt_bundle_attachinto the IDF client. The bundle is already always linked since 0.5.0, so this adds no binary size. TLS precedence per transport:cert_pem(pin) → cert bundle → WS-only embedded GTS Root R4 (use_default_certs, now the fallback for builds withoutMBEDTLS_CERTIFICATE_BUNDLE) → nothing.esp_websocket_clientinside IDF 4.x Arduino cores predates thecrt_bundle_attachconfig field; the member is detected at compile time (expression SFINAE) and such builds fall back to the embedded GTS Root R4 — the pre-0.5.1 behavior — instead of failing to compile. (Found building a core-2.x project downstream.)WebSocketTransport::useDefaultCerts()now expresses explicit intent: disables the bundle and selects the embedded root (previously it set an already-default flag).Behavior change: with no
cert_pem, WS validates against the bundle instead of only the embedded GTS Root R4 (strictly more permissive), and MQTT validates against the bundle instead of having no verification option configured.use_cert_bundle = falserestores the old behavior.Docs
docs/changelog.md: newv0.5.1-deventry (New + Upgrading notes).docs/api.md: documenteduse_cert_bundleon the WS and MQTTConfigtables and correcteduse_default_certsto read as the bundle-disabled fallback, with the precedence chain spelled out. Also filled a pre-existing gap — added a fullHttpTransportreference section (Config, methods,Response,FetchOptions; shipped in 0.5.0 with no api.md coverage), the missing header-include row, a HttpTransport column in the SendOptions table, and bumped the stale "0.4.0 API" header.Testing
159/159 native unit tests (mocks gain the
crt_bundle_attachfield; new cases cover pin-overrides-bundle, bundle-by-default, and the no-bundle fallbacks). Hardware-validated downstream in hawthorn-firmware (inanimate-tech/hawthorn-firmware#109): fan-p1 and m5sticks3 running WS + MQTT against a Cloudflare-fronted host on bundle TLS with no pinned roots, plus a core-2.x device (face-p1) exercising the SFINAE fallback.🤖 Generated with Claude Code