tls
import tls from "tls";tls is TLS 1.3 (RFC 8446), a client and a server, that never touches a
socket, a clock or a random source. Each is an engine: you feed it the
bytes your transport received, send the bytes it gives you, and read and
write plaintext through it. The time and 64 random bytes come in with its
configuration. So the same engine runs over OS sockets, over a kernel’s
own network stack, over a pipe, or in memory in a test. Most of this page
is the client; the server has the same shape.
A Client or a Server is a tls.Engine in that role: the engine does
everything both roles do (moving bytes, reading and writing, inspecting,
wiping), and c.engine reaches it. The client and the server add only
what differs: start, phase and failed_in, and the server’s
certificate choice. So code that only moves bytes takes a *tls.Engine
and serves either end.
var c: tls.Client; // one connection, about 53 KiB
c.start(&cfg) or { return; }; // the ClientHello is now in c.engine.output()
let e: *tls.Engine = &c.engine;
while (!e.is_connected()) {
send(e.output()); // your transport
e.advance_output(e.output().len);
let n: i64 = receive(buf[0..4096]); // your transport
e.feed(buf[0..n]) or { return; }; // the alert to send is in e.output()
}It checks the server’s certificate chain with x509 against
the roots you trust (usually ca_roots) and the server
name you asked for, verifies the server’s signature and Finished, and
protects every record with an AEAD from crypto. There is no
way to skip the server’s authentication: a pinned certificate (below)
replaces the chain, nothing replaces both.
What it supports: TLS 1.3 only (a TLS 1.2 server is refused); the suites
TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384 and
TLS_CHACHA20_POLY1305_SHA256; X25519, and P-256 when the server asks for
it with a HelloRetryRequest; server signatures by ECDSA P-256/SHA-256,
ECDSA P-384/SHA-384 and RSA-PSS with SHA-256/384/512; ALPN; KeyUpdate both
ways. Not: resumption, 0-RTT, client certificates (a server that asks
gets an empty Certificate).
The module is pure and works in every profile, t0 included: it allocates
nothing; all its buffers are inside the Engine of a Client or Server. In a hosted
program the net module drives it over sockets for you
(tls_connect, tls_accept); use tls directly for other transports or
your own event loop.
Configuration
pub struct Config {
server_name: []const u8; // host name or IP address literal
trust: ?*const x509.TrustStore; // the roots to trust; null only with a pin
now_unix: i64; // seconds since 1970 UTC
entropy: []const u8; // ENTROPY_LEN (64) random bytes
alpn: []const []const u8 = []; // protocols to offer, preferred first
pin_leaf_sha256: []const u8 = []; // the SHA-256 of the one leaf to accept
}
pub const ENTROPY_LEN: i64 = 64;
pub const MAX_ALPN: i64 = 256;server_nameis sent to the server as SNI (unless it is an IP address) and checked against the certificate’s subjectAltName.trustis read when the server’s certificate arrives; keep it alive and unchanged while the client runs.now_unixdecides whether the certificates are in their validity period. A wrong clock makes good certificates fail, never bad ones pass.entropymust be 64 bytes from a real random source (os.random_bytes); the engine draws its keys and its ClientHello random from them. Never reuse them.alpnis the Application-Layer Protocol Negotiation list, such as"h2"and"http/1.1"; the encoded list is at mostMAX_ALPNbytes.
import os from "os";
import time from "time";
import x509 from "x509";
import ca_roots from "ca_roots";
var anchors: [ca_roots.COUNT]x509.Cert;
var store: x509.TrustStore = x509.trust_store(anchors[0..ca_roots.COUNT]);
ca_roots.load(&store) or { return 1; };
var entropy: [64]u8;
os.random_bytes(entropy[0..64]) or { return 1; };
var protocols: [1][]const u8;
protocols[0] = "http/1.1";
let cfg: tls.Config = tls.Config {
server_name: "example.com";
trust: &store;
now_unix: time.unix_nanos() / 1000000000;
entropy: entropy[0..64];
alpn: protocols[0..1];
};Starting
pub fn Client.start(*self, cfg: *const Config) -> void or TlsErrorResets the client, checks the configuration and queues the ClientHello in
c.engine.output(). A Client can be started again for the next connection.
BadServerName when server_name is neither a host name (letters,
digits, - and ., labels of 1 to 63 bytes, at most 253 bytes; a
trailing dot is dropped) nor an IP address. These are mistakes in the
program and stop it (a trap): entropy not 64 bytes, an ALPN name empty
or over 255 bytes, an ALPN list over MAX_ALPN, a pin that is not 32
bytes, and no trust with no pin.
c.start(&cfg) or {
io.println("cannot start: {err}"); // "server name is not a valid host name or IP address"
return 1;
};Moving bytes
pub fn Engine.output(*const self) -> []const u8
pub fn Engine.advance_output(*self, n: i64)
pub fn Engine.input_space(*const self) -> i64
pub fn Engine.feed(*self, data: []const u8) -> i64 or TlsError
pub fn Engine.end_of_input(*self) -> void or TlsErrorThese, and everything below up to Pinning but
phase and failed_in, are the engine’s: c.engine.feed(data) for a
client, s.engine.feed(data) for a server.
output() is what to send next: a view into the engine, valid until the
next call that changes it. Send some or all of it and say how much with
advance_output(n).
feed takes what the transport delivered, as much as fits
(input_space() bytes), processes every whole record and returns how many
bytes it took. Records may arrive split anywhere, even a byte at a time.
When the server’s application data is waiting to be read, feed stops
taking records until you read it, and may take 0 bytes: read, then feed
the rest.
When the transport reaches its end, call end_of_input. After the
server’s close_notify that is fine; before it, it is Truncated: an
attacker who cuts the connection must not make a truncated answer look
complete.
Every error is fatal and comes with an alert for the server in
output(): send it if you can, then close the transport. From then on
feed returns the same error again.
fn flush(e: *tls.Engine, t: *Transport) -> bool { // a client's or a server's
while (e.output().len > 0) {
let n: i64 = t.send(e.output()) or { return false; };
e.advance_output(n);
}
return true;
}
fn handshake(e: *tls.Engine, t: *Transport) -> void or tls.TlsError {
var buf: [16384]u8;
while (!e.is_connected()) {
flush(e, t);
let n: i64 = t.receive(buf[0..16384]);
if (n == 0) { e.end_of_input() or return; }
var off: i64 = 0;
while (off < n) {
let took: i64 = e.feed(buf[off..n]) or {
flush(e, t); // the alert, best effort
return err;
};
off = off + took;
}
}
flush(e, t); // the client Finished
}handshake(&c.engine, &t) runs it for a client.
Reading and writing
pub const MAX_PLAINTEXT: i64 = 16384;
pub const MAX_RECORD: i64 = 16645;
pub fn Engine.read(*self, dst: []u8) -> i64
pub fn Engine.pending(*const self) -> i64
pub fn Engine.write(*self, src: []const u8) -> i64 or TlsError
pub fn Engine.update_keys(*self, request_peer: bool) -> bool
pub fn Engine.close(*self)read copies decrypted data into dst and returns the count, 0 when
nothing is waiting (pending says how much is). It never fails; errors come from feed. When it
empties a record, the client goes on with the records it already holds,
so after feeding everything you can keep reading.
write encrypts up to MAX_PLAINTEXT bytes of src into one record
queued in output() and returns how many it took; 0 when the output is
full: send it first. Writing before the handshake completes, or after
close, is a mistake in the program and traps (is_connected() says
when you may write).
update_keys replaces the client’s send key now (TLS 1.3 KeyUpdate), and
with request_peer asks the server to replace its own; false when the
output is full. The client also does this on its own before an AES-GCM
key has protected 2^24 records, and answers the server’s requests.
close sends close_notify. Writing after it traps, but reading goes on
until the server’s own close_notify (peer_closed()), as TLS 1.3
closes each direction on its own.
var sent: i64 = 0;
while (sent < body.len) {
let n: i64 = c.engine.write(body[sent..body.len]) or { return; };
if (n == 0) { flush(&c.engine, t); } // output full: send, then go on
sent = sent + n;
}
flush(&c.engine, t);
var answer: [4096]u8;
let got: i64 = c.engine.read(answer[0..4096]);Inspecting
pub fn Client.phase(*const self) -> State
pub fn Client.failed_in(*const self) -> ?State
pub fn Engine.is_connected(*const self) -> bool
pub fn Engine.peer_closed(*const self) -> bool
pub fn Engine.error(*const self) -> ?TlsError
pub fn Engine.cert_error(*const self) -> ?x509.X509Error
pub fn Engine.alert(*const self) -> ?Alert
pub fn Engine.suite(*const self) -> ?Suite
pub fn Engine.group(*const self) -> ?Group
pub fn Engine.retried(*const self) -> bool
pub fn Engine.alpn(*const self) -> ?[]const u8
pub fn Engine.leaf_sha256(*const self) -> ?[]const u8phase and failed_in are the client’s own (c.phase()), as a server’s
states differ; the rest are the engine’s (c.engine.alert()).
| Function | Gives |
|---|---|
phase() | where the handshake is: State.WaitServerHello … Connected, or Failed |
is_connected() | the handshake is complete: you may write |
peer_closed() | the server sent close_notify: no more data will come |
error() | the error that failed the client, null while it works |
failed_in() | the state it was in when it failed |
cert_error() | with a certificate failure, x509’s precise reason |
alert() | the last alert the server sent: fatal, and code, an AlertCode (its desc() is the RFC name) |
suite(), group() | the negotiated cipher suite and key-exchange group |
retried() | the server asked for another key share (HelloRetryRequest) |
alpn() | the protocol the server chose, null when none |
leaf_sha256() | the SHA-256 of the server’s certificate, once it arrived |
c.engine.feed(data) or {
io.println("TLS failed: {err} while {c.failed_in()!.desc()}");
let why: ?x509.X509Error = c.engine.cert_error();
if (why != null) { io.println(" certificate: {why!}"); }
let a: ?tls.Alert = c.engine.alert();
if (a != null) { io.println(" the server said: {a!.code}"); } // "no_application_protocol"
return;
};
io.println("{c.engine.suite()!.desc()} over {c.engine.group()!.desc()}"); // TLS_AES_128_GCM_SHA256 over x25519Pinning a certificate
For a server you know, you can pin its certificate by the SHA-256 of its
DER (what leaf_sha256() reports). With a trust store as well, the chain
must hold and the certificate must be the pinned one. With trust: null,
the pin is the whole check: no chain to a root, no name match and no
validity dates, so it works without a clock and for a self-signed
certificate. The server must still prove it holds the certificate’s key.
Any other certificate fails with LeafPinMismatch.
let pinned: tls.Config = tls.Config {
server_name: "debug.local";
trust: null; // the pin alone
now_unix: 0; // not used without a store
entropy: entropy[0..64];
pin_leaf_sha256: known_hash[0..32];
};A pin is only as good as the way the hash reached your program: ship it with the program, and ship a new one when the server’s certificate changes.
The server
pub struct ServerConfig {
entropy: []const u8; // ENTROPY_LEN (64) random bytes
alpn: []const []const u8 = []; // our protocols, preferred first
alpn_required: bool = false; // no protocol in common: refuse
}
pub fn Server.start(*self, cfg: *const ServerConfig) -> void or TlsError
pub fn Server.phase(*const self) -> ServerState
pub fn Server.failed_in(*const self) -> ?ServerState
pub fn Server.server_name(*const self) -> ?[]const u8
pub fn Server.use_certificate(*self, chain: []const []const u8, key: *const x509.PrivateKey) -> void or TlsError
pub fn Server.refuse(*self)A Server is the other end of the same protocol, the same size as a
Client, driven the same way through its engine: output,
advance_output, input_space, feed, end_of_input, read,
pending, write, update_keys, close and wipe, and for inspecting
is_connected, peer_closed, error, alert (the client’s), suite,
group, retried and alpn (the protocol chosen). phase and
failed_in are its own and give a ServerState. It sends no session
tickets, asks for no client certificate and takes no 0-RTT data.
start resets the server to wait for a ClientHello. When one has been
fed and checked, the server pauses: phase() is
ServerState.NeedCertificate, nothing has been sent yet, and
server_name() is the name the client asked for (null when it sent none,
as for an IP address). Choose a certificate chain by that name and call
use_certificate, or refuse when you have none for it (the client gets
unrecognized_name and the server fails with CertificateRefused). A
server with one certificate answers at once, in the same loop step;
net.Certificates does the choosing for several.
use_certificate takes the chain as DER certificates, the leaf first,
and the leaf’s private key as x509.parse_private_key reads it
(once, when the program loads its key). Nothing is copied but what is sent,
so the views need to live only through the call. It queues the server’s
whole answer and goes on with what was already fed. KeyMismatch when the
key is not the leaf’s; HandshakeFailure when the client cannot verify the
key’s signature (a P-256 key signs with ECDSA P-256/SHA-256, a P-384 key
with ECDSA P-384/SHA-384, an RSA key with RSA-PSS/SHA-256); either fails
the server, with its alert queued.
fn serve(s: *tls.Server, t: *Transport, chain: []const []const u8, key: *const x509.PrivateKey,
entropy: []const u8) -> void or tls.TlsError {
let cfg: tls.ServerConfig = tls.ServerConfig { entropy: entropy; };
s.start(&cfg) or return;
let e: *tls.Engine = &s.engine;
var buf: [16384]u8;
while (!e.is_connected()) {
flush(e, t); // the client's flush, as it is
let n: i64 = t.receive(buf[0..16384]);
if (n == 0) { e.end_of_input() or return; }
var off: i64 = 0;
while (off < n) {
let took: i64 = e.feed(buf[off..n]) or { flush(e, t); return err; };
off = off + took;
if (s.phase() == tls.ServerState.NeedCertificate) {
// one certificate for every name; refuse() when there is none
s.use_certificate(chain, key) or { flush(e, t); return err; };
}
}
}
flush(e, t);
}What the server chooses:
- The suite: the first the client offers of
TLS_AES_128_GCM_SHA256,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_256_GCM_SHA384, with ChaCha20 first on a processor without AES instructions. - The key exchange: the client’s X25519 share, else its P-256 share,
else one HelloRetryRequest asking for X25519 (
retried()); a second ClientHello still without it isIllegalParameter. - ALPN: the first of
alpnthat the client offers. None in common means no protocol (alpn()is null), or withalpn_requiredtheno_application_protocolalert andNoApplicationProtocol. A client that offers no ALPN at all is served without. - A client offering only TLS 1.2 or older gets
protocol_version(ProtocolVersion). A client in middlebox compatibility mode (a session id, as most browsers and OpenSSL send) gets its id back and achange_cipher_specrecord, and its ownchange_cipher_specrecords are dropped.
Types
pub enum Suite : u16 { Aes128GcmSha256 = 0x1301; Aes256GcmSha384 = 0x1302; ChaCha20Poly1305Sha256 = 0x1303; }
pub enum Group : u16 { Secp256r1 = 0x0017; X25519 = 0x001d; }
pub enum State : u8 {
Start; WaitServerHello; WaitRetriedServerHello; WaitEncryptedExtensions;
WaitCertificate; WaitCertificateVerify; WaitFinished; Connected; Failed;
}
pub enum ServerState : u8 {
Start; WaitClientHello; NeedCertificate; WaitRetriedClientHello;
WaitClientFinished; Connected; Failed;
}
pub enum AlertCode : u8 {
CloseNotify = 0: "close_notify";
UnexpectedMessage = 10: "unexpected_message";
// ... every TLS 1.3 alert (RFC 8446 §6), by its RFC name ...
NoApplicationProtocol = 120: "no_application_protocol";
}
pub struct Alert { fatal: bool; code: AlertCode; }
pub struct Engine { ... } // @opaque
pub struct Client { engine: Engine; }
pub struct Server { engine: Engine; }Each desc() is the IANA name ("TLS_CHACHA20_POLY1305_SHA256",
"secp256r1", "unrecognized_name") or the state in words ("waiting for Certificate"). A peer may send an alert code TLS 1.3 does not
define: code keeps it (code as u8 is the number) and its desc() is
empty. tls.AlertCode.desc(n) names a raw byte, such as the second byte
of an alert record.
An Engine (and so a Client or a Server) is a plain struct of about
53 KiB with no pointers into itself: put one in a global, on the heap or
in a large stack frame, and use one per connection.
Errors
pub enum TlsError : u8 {
BadRecord = 1: "malformed TLS record";
RecordOverflow = 2: "TLS record too large";
BadRecordMac = 3: "TLS record failed authentication";
UnexpectedMessage = 4: "unexpected TLS message";
DecodeError = 5: "malformed TLS handshake message";
HandshakeTooLarge = 6: "TLS handshake message exceeds the engine's buffer";
ProtocolVersion = 7: "server does not support TLS 1.3";
HandshakeFailure = 8: "no common cipher suite, group or signature algorithm";
IllegalParameter = 9: "server chose a value the client did not offer";
UnsupportedExtension = 10: "server sent an extension the client did not offer";
MissingExtension = 11: "server omitted a required extension";
BadCertificate = 12: "server certificate is malformed, unsupported or not allowed for this use";
CertificateExpired = 13: "server certificate has expired or is not yet valid";
UnknownCa = 14: "server certificate does not chain to a trusted root";
NameMismatch = 15: "server certificate does not match the server name";
BadCertificateVerify = 16: "server's CertificateVerify signature does not verify";
BadFinished = 17: "server's Finished does not verify";
PeerAlert = 18: "server sent a fatal alert";
Truncated = 19: "connection closed without close_notify";
BadServerName = 20: "server name is not a valid host name or IP address";
LeafPinMismatch = 21: "server certificate is not the pinned one";
NoApplicationProtocol = 22: "no ALPN protocol in common with the client";
KeyMismatch = 23: "private key does not match the certificate";
CertificateRefused = 24: "no certificate for the server name the client asked for";
}The certificate errors (BadCertificate, CertificateExpired,
UnknownCa, NameMismatch) keep x509’s reason in cert_error().
PeerAlert means the peer ended the connection: alert() says why (a
no_application_protocol, 120, when the server speaks none of your ALPN
protocols). A server uses the same errors where they apply (a client’s
Finished that does not verify is BadFinished, its fatal alert
PeerAlert); the last three are the server’s own.
Secrets
The key schedule and the record protection are @constant_time; the
engine wipes its key-exchange key and handshake secrets as soon as it no
longer needs them.
pub fn Engine.wipe(*self)wipe zeroes every secret left in the client or server (the traffic keys,
the buffers with their plaintext) when you are done with a connection; it
can then only be started again. What the inspecting functions report
stays. A server’s private key is yours: the engine reads it during
use_certificate and keeps nothing of it.
Notes
- The constant-time guarantee is for native code; the VM computes the same results without it.
- Tested with the RFC 8448 traces (the engine’s records match the RFC’s
byte for byte), in-memory handshakes against a test server with every
suite, chain, signature, HelloRetryRequest and ALPN case and every
misbehaviour it can be made to show, fed whole and a byte at a time,
and against OpenSSL’s
s_server. The server engine is tested against the client engine in memory (split into pieces of every size from 1 to 11 bytes) and against OpenSSL’ss_client.
Last modified: