Skip to main content
Version: Next

Memory Usage

Device teams need predictable ROM (code) and RAM (heap, stack, record buffers) when TLS is only one subsystem. This page documents a repeatable measurement method, practical tuning points, and the exact APIs/config knobs that influence footprint.

Footprint drivers​

AreaCrates / knobsNotes
Protocol + state machinenoxtlsTLS 1.2/1.3 and DTLS paths; handshake buffers dominate peak RAM.
Cryptonoxtls-cryptoAEAD, ECDH, signatures; ML-KEM / ML-DSA add code size.
X.509noxtls-x509, noxtls-pemChain depth and parser tables affect ROM; PEM is optional if you ingest DER only.
I/O adaptersnoxtls-ioThin; async stacks may pull larger dependency trees on host.

Build profiles to measure​

cargo build -p noxtls --release --no-default-features --features alloc,adapter-embedded-io

Use at least two profiles for apples-to-apples comparisons:

  • Baseline TLS: only the features your product ships.
  • Worst-case debug: include DTLS, certificate validation, and optional algorithms you might enable in field variants.

Then use llvm-size / cargo bloat on the produced artifact.

Capture RAM at these protocol milestones:

  1. Connection init (Connection::new) to establish baseline.
  2. ClientHello/ServerHello phase (send_client_hello_*, recv_server_hello) for first handshake growth.
  3. Certificate processing (recv_certificate, chain validation) for peak parsing allocations.
  4. Finished + data path (seal_record, open_record) for steady-state buffers.
  5. DTLS retransmit window (DtlsFlightRetransmitTracker) for lossy-network worst-case.

APIs and knobs affecting memory​

Record/data plane​

  • Connection::set_max_record_plaintext_len(&mut self, max_len: usize) -> Result<()>
    • Caps per-record plaintext accepted by seal_record / open_record.
    • Directly reduces peak per-record temporary buffer requirements.

Handshake policy​

  • Connection::set_dtls_operational_profile(...)
  • Connection::set_dtls_operational_policy(...)
    • Tune retransmit/backoff behavior and anti-amplification decisions.
    • Smaller retransmit windows reduce RAM but may reduce tolerance for loss/jitter.

Certificate/X.509 overhead​

  • Prefer DER ingest APIs over PEM conversion when possible.
  • Use minimal trust-anchor/intermediate sets for device images.
  • Validate only required policy constraints for your deployment.

Measuring on device​

  1. Link the same feature set you ship in production.
  2. Capture worst-case handshake RAM (full chain, largest cert messages, retransmission windows for DTLS).
  3. Add margin for application records and any middleware framing.

Practical reduction checklist​

  • Drop unused protocol versions via noxtls-core profile flags when both peers are under your control.
  • Prefer DER-only cert ingestion to avoid PEM tables if PEM is unused.
  • Use PSA offload (provider-psa) to move keys and AEAD into secure hardware with a smaller Rust surface.
  • Tune record buffer sizes and DTLS flight buffers per your Architecture integration.

Example measurement log template​

Track each firmware profile with:

  • Feature set / commit SHA
  • .text, .rodata, .data, .bss
  • Peak handshake RAM
  • Steady-state per-session RAM
  • DTLS loss simulation results (0%, 1%, 5% loss)

This keeps memory regressions reviewable across releases and aligns with the NoxTLS device-doc workflow.