turnloop-tls 0.1.0-beta.2

Unbuffered sans-I/O TLS with host-supplied time
Documentation

turnloop-tls

Unbuffered rustls TLS for a host-driven event loop. The host owns transport, ciphertext buffers, wall time and handshake deadlines. Handle each returned state, consume borrowed plaintext before advancing, and acknowledge encrypted writes only after their transport completion. No socket, scheduler or runtime is created.

By default client/server configurations use the ring provider (rustls defaults are disabled), including native Windows and wasm32. Browser entropy and PKI web features are enabled explicitly; building ring for wasm needs a wasm-capable C compiler. WASI obtains entropy through its host. No FIPS/PQ guarantee is claimed.

The provider is a host choice: ClientOptions::provider and ServerConfig::with_provider take any rustls CryptoProvider (aws-lc-rs, for example). ring is a default feature; with default-features = false the crate links no provider of its own, and new uses the provider the host passes or the rustls process default. Without ring, tls_server_end_point is unavailable and tls_server_end_point_hash names the hash for the host to compute.

Mozilla roots, host-supplied extra PEM, explicit replacement CAs, SNI and ALPN are supported. See public API docs and tests/tls.rs for checked handshake examples. Anything else rustls can configure (client certificates, SNI resolvers, custom verifiers, ticketers) goes through ClientConfig::from_rustls / ServerConfig::from_rustls: build the rustls config with builder_with_details(provider, host_time.time_provider()) so certificate checks keep following the wall time passed to process. PEM parsing uses rustls-pki-types through rustls’s maintained re-export.

Getting started on turnloop

Enable turnloop-tls/turnloop. TlsStream::connect and TlsStream::accept take an owned stream, shared TLS configuration, executor handle, absolute handshake deadline and host wall time. Await the handshake, inspect alpn_protocol(), then use turnloop_io::{read, write_all, close}. These helpers work on TCP and pipes and compose with HTTP/WebSocket adapters. close flushes close_notify; dropping aborts the transport. turnloop_io::shutdown flushes close_notify and half-closes the transport while decryption continues until the peer's close_notify or EOF, which is what a lingering server close uses. Refresh host wall time with set_unix_seconds when needed. The host continues calling LocalExecutor::turn throughout the connection.

After a successful handshake, peer_certificates() borrows the peer chain, leaf first, without copying. tls_server_end_point(leaf.as_ref()) derives the RFC 5929 certificate binding with ring and no heap allocation. It reads the outer certificate signature algorithm, supports RSA/ECDSA SHA-256/384/512 and RSA-PSS, and maps MD5/SHA-1 to SHA-256. Unsupported algorithms such as Ed25519 return None. This helper does not verify certificates: verification follows the TLS configuration, including any explicitly insecure host option.

The adapter retains ciphertext/plaintext storage and uses rustls's unbuffered state machine. rustls 0.23's plaintext record representation still allocates; transport scratch allocation freedom is distinct from upstream crypto storage. The real-socket allocation gate checks 100 bidirectional records: 400 existing rustls allocations and zero adapter overhead. Unread plaintext is bounded to 64 KiB. WASI sockets use the same implementation. Browser TLS is managed by host fetch or WebSocket and cannot expose raw TLS options.