Technical Details
This page covers the LibLoad bootstrap internals, memory layout, and the deeper engineering notes behind the stack.
LibLoad Environment
Bootstrapping
lwIP-CE is too big to statically include into every program that wants to use it. The core plus TLS is around 420 KiB, and the calculator only has just under 2 MB of Flash, so statically linking it into each consumer would burn that space fast. Instead, lwIP-CE ships as a resident application that other programs call into. One copy lives on the calculator; everything else dispatches to it.
That “call into a resident app” trick is built on top of the CE toolchain’s
LIBLOAD mechanism – but with some custom logic bolted on, because LIBLOAD
was not designed for this exact use case.
lwip.8xv is a LibLoad library that defines every function in lwIP that is part
of the public API as well as the bootstrapping function lwip_start().
Calling lwip_start():
Locates the resident lwIP App in Flash.
Jumps to a static offset from the start of the app, where the exports table is linked.
Copies the exports to the LibLoad exports table.
Calls
lwip_init_runtime_internal()with the CRT pointers and a pointer/length to a table of functions to import.Zeroes
.bss, copies.datato its correct location.Copies the CRT pointers and imports to an imports table within the App’s BSS.
Returns to the caller.
So the consumer links against the tiny stub; the stub, once bootstrapped, routes every call into the real app in Flash.
Heap Ownership
lwIP-CE is an oddity with regard to heap usage because the application itself needs some heap space of its own. However, when you use lwIP-CE as a dylib (via LibLoad), the heap allocations of the app are not active or initialized. This was solved by:
Setting lwIP-CE’s
BSSHEAP_HIGHto0xD072C6causing the app to build with only 8 KiB of BSS/Heap space. This was precomputed to fit the needed space plus some headroom.Direct developers building with lwIP-CE to set
BSSHEAP_LOWto0xD072C6in their program’s makefile. This ensures that the caller does not clash with the library’s heap usage.
The practical consequence for consumer programs: you must move your own
BSSHEAP_LOW up by 8 KiB so your variables start above lwIP-CE’s reserved
window. In other words, link with:
BSSHEAP_LOW = 0xD072C6
If you leave BSSHEAP_LOW at the default, your program’s BSS and lwIP-CE’s
will overlap, and you will have very bad things happen.
USB Device Mode and the Wi-Fi Bridge
With a USB Ethernet adapter the calculator is the USB host. With the lwIP-CE
Wi-Fi bridge the roles flip: the bridge is the host and the calculator is a USB
device, so the stock calculator cable works. usb_ethernet.c handles both;
which one applies is decided by the cable (usb_GetRole()).
As a device the calculator presents a CDC-ACM configuration (16c0:05e1,
“lwIP Wi-Fi”) with a notification endpoint 0x82, bulk OUT 0x04 and bulk
IN 0x83, 64 bytes each. CDC-ACM is used instead of CDC-ECM because its
configuration descriptor fits in a single 64-byte control packet and every
USB host stack has a driver for it. The calculator answers the class requests
itself:
Request |
Handling |
|---|---|
|
Accepted and echoed back; the values have no effect. |
|
DTR sets the netif link: the bridge raises DTR only while Wi-Fi is connected. |
|
Six bytes, the MAC the netif uses. The bridge sends its Wi-Fi station MAC, since a station may only transmit from its own address. |
When the host selects the configuration (USB_HOST_CONFIGURE_EVENT), an
en netif is created on the bulk endpoints. Each USB transfer carries one
Ethernet frame. The calculator ends IN transfers with a short or zero-length
packet (USB_AUTO_TERMINATE); the bridge pads frames whose length is a
multiple of 64 bytes by one byte, so every OUT transfer also ends short and the
calculator’s 1536-byte receive transfers complete per frame. The trailing byte
is ignored by IP. In device mode the receive transfer stays armed while the
link is down, so control frames still arrive when Wi-Fi is offline.
On the bridge, frames from the calculator go straight out of the Wi-Fi station interface and everything the station receives goes back to the calculator. The bridge runs no IP stack on Wi-Fi; the calculator gets its address from the network’s DHCP server.
Wi-Fi Control Frames
lwip/wireless/wifi.h talks to the bridge with Ethernet frames of EtherType
0x88B5 (IEEE local experimental) on the same link. The bridge consumes
them and never forwards them to Wi-Fi. On the calculator they are picked up by
LWIP_HOOK_UNKNOWN_ETH_PROTOCOL. All multi-byte values are little-endian and
strings are a length byte followed by the bytes, without a terminator.
Offset |
Field |
|---|---|
0 |
Destination MAC ( |
6 |
Source MAC |
12 |
EtherType |
14 |
Protocol version, |
15 |
Operation; replies set bit 7 |
16 |
Sequence number, echoed in the reply |
17 |
Status in replies: 0 ok, 1 bad request, 2 not found, 3 full, 4 busy, 5 rejected |
18 |
Body |
Op |
Name |
Body |
|---|---|---|
1 |
Status |
Reply: connected, slot, RSSI, channel, BSSID (6), saved count, SSID,
disconnect reason ( |
2 |
List |
Reply: count, then per network slot, flags, security, SSID. |
3 |
Scan |
Reply: count, then per network RSSI, channel, security, SSID. |
4 |
Save |
Request: slot ( |
5 |
Forget |
Request: slot. |
6 |
Enable |
Request: slot, enabled. |
7 |
Prefer |
Request: slot. |
8 |
Connect |
Request: slot, or |
9 |
Disconnect |
None. |
10 |
Info |
Reply: crypto capabilities (bit 0 X25519, bit 1 RSA, bit 2 TRNG, bit 3 P-256), firmware version (string, at most 32 characters; absent from older firmware). |
11 |
X25519 |
Request: scalar (32), point (32; |
12 |
RSA verify |
Request: algorithm (1 PKCS#1 v1.5, 2 PSS, both SHA-256), digest (32), modulus length (2), exponent length, modulus, exponent, signature (modulus length). Numbers are big-endian. Status 0 valid, 5 invalid. |
13 |
Random |
Request: count (at most 64). Reply: that many TRNG bytes. |
14 |
P-256 |
Request: scalar (32), then optionally the peer’s uncompressed point (65). Reply: our uncompressed public key (65) without a point, otherwise the shared secret’s x-coordinate (32). |
15 |
ECDSA verify |
Request: digest (32), uncompressed P-256 public key (65), signature as r then s (32 each). Status 0 valid, 5 invalid. |
64 |
Event |
Sent unprompted as op |
Ops 10 to 15 run on their own task on the bridge and may overlap, so their replies are matched by op and sequence number. The bridge answers status 1 whenever it cannot decide; the calculator then does the work itself. See Using Wi-Fi for how the calculator uses them.
Saved networks live in the bridge’s NVS under the lwip_wifi namespace.
TLS Details
The TLS stack is intentionally narrow: enough to make real secure client sockets, not a general-purpose OS crypto subsystem. A thin TLS 1.3 client is provided.
Algorithm Support
Component / Purpose |
Algorithm |
OID / Code |
Status |
|---|---|---|---|
Record encryption |
AES-128-GCM-SHA256 |
|
Done |
Record encryption |
AES-128-CCM-SHA256 |
|
Done |
Record encryption |
AES-256-GCM-SHA384 |
|
Not planned (optional per RFC 8446; contributions welcome) |
Record encryption |
ChaCha20-Poly1305-SHA256 |
|
Not planned (optional per RFC 8446) |
Key exchange (ECDHE) |
X25519 |
|
Done |
Key exchange (ECDHE) |
secp256r1 (P-256) |
|
Done |
Server signature verification |
rsa_pss_rsae_sha256 |
|
Done |
Server signature verification |
ecdsa_secp256r1_sha256 |
|
Done |
Server signature verification |
rsa_pkcs1_sha256 |
|
Done (chain walk only) |
Certificate chain — link signature |
sha256WithRSAEncryption (PKCS#1 v1.5) |
|
Done |
Certificate chain — link signature |
ecdsa-with-SHA256 (P-256) |
|
Done |
Trust store root verification |
RSA-PSS-SHA256 |
|
Done |
Trust store root verification |
ECDSA-SHA256 (P-256) |
|
Done |
ClientHello Profile
Every connection starts with a ClientHello whose extension set is fixed at
compile time. The table below lists every extension this implementation sends.
No other extensions are emitted; a server that requires an extension not in
this list will reject the handshake.
Extension |
Presence |
Value / Notes |
|---|---|---|
|
Always |
TLS 1.3 only ( |
|
Always |
|
|
Always |
ClientHello1 contains X25519 (32 B). ClientHello2 contains P-256 (65 B uncompressed) only when selected by HelloRetryRequest. |
|
Always |
|
|
Always |
|
|
Always |
4096 bytes as |
|
If hostname set |
Single |
|
If PSK mode |
|
|
If ALPN configured |
Ordered list supplied by the application. See |
|
On HRR retry |
Echo of the cookie from the server’s HelloRetryRequest. |
|
If PSK mode |
Identity + binder. Must be the last extension (RFC 8446 §4.2.11). Binder is HMAC-SHA-256 over the transcript up to but not including the binders field. |
ClientHello1 is gated only on X25519. P-256 generation proceeds speculatively
when Wi-Fi bridge offload is available; without offload, its blocking software
implementation is deferred until an HRR selects P-256. ClientHello2 then
contains exactly that P-256 share. An HRR that repeats X25519 or requests an
unadvertised group is rejected with illegal_parameter.
Security Posture
Area |
Position |
|---|---|
Threat model |
Algorithmic security is in scope. Side channels are partially mitigated and partially out of scope. Hardware security is out of scope: no root of trust, secure enclave, crypto accelerator, protected filesystem, or trusted clock. |
RNG |
SRAM-noise-derived, NIST SP 800-90A/90B aligned. Current data suggests Hmin around 0.267. See the whitepaper for the confidence bounds, lag-1 coefficients, dependency factors, and limitations of this non-certification analysis. |
TLS trust store |
A curated trust store derived from CA material staged on a common Linux
box, shipped as a signed AppVar and verified with RSA-PSS-SHA256 against
an embedded public key at |
Certificate chain |
The stack walks the server’s certificate chain link by link. Each link
is verified against the next certificate’s public key. RSA PKCS#1 v1.5 /
sha256WithRSAEncryption and ECDSA-P-256/SHA-256 links are verified for
real; a bad signature on either is an Once the adjacent-link walk finishes, the topmost certificate’s issuer
is looked up in the trust store by SKI and complete subject Name digest,
or by subject Name digest when AKI is absent. If found and the stored
key is RSA (PSS or PKCS#1-SHA256) or ECDSA P-256, the root signature is
verified for real – a bad signature is an |
Certificate revocation |
OCSP (RFC 6960), opt-in through the configuration wizard (off by
default). After a certificate’s signature verifies, the handshake is
held while a SHA-1 CertID request goes to the responder in its AIA
extension over plain HTTP. The issuer is the next presented
certificate or, for the topmost certificate, its truststore root. The
response must be signed by the issuer or a delegated responder,
match the CertID, and be fresh (5-minute skew, 24-hour maximum age
without |
CertificateVerify |
|
For more details, proofs, and datasets, see the whitepaper below.
The clause-by-clause mapping of the RFC, NIST SP, and FIPS requirements this implementation targets to the code that satisfies or deviates from them is published as the TLS specification compliance ledger as a static HTML report generated from the authoritative XML source during the documentation build.
CI And Test Harnesses
The test harnesses are not decoration. They are there because the platform is weird, the toolchain matters, and it is easy to pass a host-side test that says nothing about the calculator binary.
Harness |
What it proves |
|---|---|
CAVP primitive validation |
Packs CAVP-derived vectors into |
Timing profiler |
Runs calculator-side timing captures so crypto and stack hot paths can be measured in the environment that actually ships. |
RNG entropy capture |
Emits AppVars for raw and conditioned entropy paths, then analyzes the bit streams off-device. Entropy tests are not useful in the emulated CI pipeline because SRAM emulation is deterministic, so those captures are run on hardware and analyzed in the whitepaper instead. |
DAST hardware-in-the-loop |
Runs the calculator-side |
Doxygen/Sphinx docs build |
Builds the generated API reference and the project docs with the same release headers users will see. |
The CAVP harness uses AppVars because that is the natural calculator transport boundary: host tools generate inputs, CEmu runs the app, and host tools parse the saved output. That keeps the validation path close to how a real program interacts with calculator storage instead of pretending this is a POSIX target.
Whitepaper
The whitepaper covers the TLS implementation, RNG design, cryptographic constraints, and platform tradeoffs behind lwIP-CE. It is published separately by the whitepaper release workflow: