`std/tls`

TLS over a TcpStream: TlsStream.connect for a client, TlsStream.accept with a ServerIdentity for a server, and a stream with the same two directions a TcpStream has (docs/design/NETWORK.md section 5). A client proves who it is with a ClientIdentity in its TlsSettings (mutual TLS) when the server asks for one through clientRoots. A Transport is one connection of TCP or TLS over TCP behind the same four operations, upgradable in the middle for protocols that ask for TLS after they began (Postgres, MySQL, STARTTLS).

const tcp = TcpStream.connectTo("example.test", 443).await()?
var stream = TlsStream.connect(tcp, "example.test").await()?
stream.send("GET / HTTP/1.1\r\nHost: example.test\r\n\r\n".bytes()).await()?

The protocol is mbedTLS 3, TLS 1.2 and 1.3. A client checks the server's certificate for the name it asks for: on Windows the platform decides - its roots, its enterprise roots, its policies - and elsewhere the system's bundle of roots does; TlsSettings.trusted replaces both with roots of the program's own. There is no switch that turns the check off.

TLS is a state machine over bytes here: every wait is a wait of the TcpStream under it, so a TLS read is cancelled, timed out and paced exactly as a TCP read is.

Modules

std/tls/libTLS over a TcpStream: [TlsStream.connect] for a client, [TlsStream.accept] with a [ServerIdentity] for a server, and a stream with the same two directions a TcpStream has (docs/design/NETWORK.md section 5).

Everything

type ClientIdentityWhat a client proves who it is with where a server asks for a certificate: its certificate chain and the private key of the first certificate, both PEM.
type ServerIdentityWhat a server proves who it is with: its certificate chain and the private key of the first certificate, both PEM.
type TlsResolverDNS over TLS (RFC 7858): the lookups of std/network's Resolver, asked of one name server over a TLS connection to its port 853 - the question and the answer each after their length in two bytes, as over TCP (RFC 7766) - with the server authenticated by the name its certificate has to carry (RFC 8310's strict profile: a server that cannot prove serverName is never asked).
type TlsSettingsWhat a client trusts.
type TlsSinkThe writing direction of a [TlsStream]: a Sink<Bytes, NetworkError>.
type TlsSourceThe reading direction of a [TlsStream]: a Source<Bytes, NetworkError>.
type TlsStreamOne TLS connection over a TcpStream: bytes in both directions, encrypted and authenticated.
type TransportA connection as a protocol reads and writes it: plain TCP, or TLS over TCP, behind the same four operations - receive, send, finish, remote - and upgradable in the middle of the connection, which is what Postgres's TLS request, MySQL's SSL request, SMTP's STARTTLS and an https URL have in common.