TLS API overview
This section documents how applications and firmware interact with NoxTLS Rust for TLS 1.2 / 1.3 and DTLS. It provides the canonical API narrative with device-relevant grouping: what types matter, when to call them, and where to read deeper.
Entry points
| Concern | Primary types / modules | Doc depth |
|---|---|---|
| Modeled connection | noxtls::Connection, HandshakeState, TlsVersion | Rustdoc + examples in repo |
| Record layer helpers | ProtectedRecord, TlsRecordDeframer, seal/open helpers exported from noxtls | Topic: TLS topic |
| DTLS | DtlsOperationalPolicy, replay trackers, flight helpers | Topic: TLS topic |
| Certificates | Parsed chains, hostname checks | X.509 topic |
Handshake lifecycle (conceptual)
- Build client/server context — versions, cipher suites, trust anchors, and optional session tickets.
- Drive handshake — feed records from your transport; advance
HandshakeStateuntilFinished(or terminal error). - Application data — seal/open application records with negotiated keys; respect MTU and fragmentation rules on DTLS.
- Renegotiation / resumption — follow product policy; many embedded products disable renegotiation entirely.
DTLS vs TLS on devices
- DTLS — expect loss, reordering, and duplication; size reassembly buffers to your network worst case.
- TLS — assume reliable byte stream below the record layer (TCP or an equivalent pipe).
Operational knobs are summarized in repository markdown docs/DTLS13_OPERATIONAL_POLICY.md (source tree), linked from the TLS topic page where relevant.
Deep dive
Continue to the TLS topic page for algorithm coverage, record layout notes, and cross-links to cryptography topics.
Per-version and DTLS pages
For crate-level metadata (package description, features), use Crate reference (generated) under Crypto API in the sidebar—those pages are generated from Cargo.toml and are supplemental, not a substitute for this TLS API narrative.